Merge branch 'release/1.3.0'

Author: Christoph.Heindl

.github/workflows/python-package.yml

@@ -0,0 +1,41 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python package
+
+on:
+  push:
+    branches: [ develop ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:        
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest pytest-benchmark        
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        pip install lap scipy ortools lapsolver munkres        
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest

.travis.yml

@@ -1,8 +1,6 @@
+[![PyPI version](https://badge.fury.io/py/motmetrics.svg)](https://badge.fury.io/py/motmetrics) [![Build Status](https://github.com/cheind/py-motmetrics/actions/workflows/python-package.yml/badge.svg)](https://github.com/cheind/py-motmetrics/actions/workflows/python-package.yml)
 
-
-[![PyPI version](https://badge.fury.io/py/motmetrics.svg)](https://badge.fury.io/py/motmetrics) [![](https://travis-ci.org/cheind/py-motmetrics.svg?branch=master)](https://travis-ci.org/cheind/py-motmetrics)
-
-## py-motmetrics
+# py-motmetrics
 
 The **py-motmetrics** library provides a Python implementation of metrics for benchmarking multiple object trackers (MOT).
 
@@ -17,9 +15,9 @@ While benchmarking single object trackers is rather straightforward, measuring t
 
 In particular **py-motmetrics** supports `CLEAR-MOT`[[1,2]](#References) metrics and `ID`[[4]](#References) metrics. Both metrics attempt to find a minimum cost assignment between ground truth objects and predictions. However, while CLEAR-MOT solves the assignment problem on a local per-frame basis, `ID-MEASURE` solves the bipartite graph matching by finding the minimum cost of objects and predictions over all frames. This [blog-post](https://web.archive.org/web/20190413133409/http://vision.cs.duke.edu:80/DukeMTMC/IDmeasures.html) by Ergys illustrates the differences in more detail.
 
-### Features at a glance
+## Features at a glance
 - *Variety of metrics* <br/>
-Provides MOTA, MOTP, track quality measures, global ID measures and more. The results are [comparable](#MOTChallengeCompatibility) with the popular [MOTChallenge][MOTChallenge] benchmarks.
+Provides MOTA, MOTP, track quality measures, global ID measures and more. The results are [comparable](#MOTChallengeCompatibility) with the popular [MOTChallenge][MOTChallenge] benchmarks [(*1)](#asterixcompare).
 - *Distance agnostic* <br/>
 Supports Euclidean, Intersection over Union and other distances measures.
 - *Complete event history* <br/>
@@ -30,7 +28,7 @@ Support for switching minimum assignment cost solvers. Supports `scipy`, `ortool
 Events and summaries are utilizing [pandas][pandas] for data structures and analysis. New metrics can reuse already computed values from depending metrics.
 
 <a name="Metrics"></a>
-### Metrics
+## Metrics
 
 **py-motmetrics** implements the following metrics. The metrics have been aligned with what is reported by [MOTChallenge][MOTChallenge] benchmarks.
 
@@ -74,9 +72,9 @@ id_global_assignment| `dict` ID measures: Global min-cost assignment for ID meas
 
 
 <a name="MOTChallengeCompatibility"></a>
-### MOTChallenge compatibility
+## MOTChallenge compatibility
 
-**py-motmetrics** produces results compatible with popular [MOTChallenge][MOTChallenge] benchmarks. Below are two results taken from MOTChallenge [Matlab devkit][devkit] corresponding to the results of the CEM tracker on the training set of the 2015 MOT 2DMark.
+**py-motmetrics** produces results compatible with popular [MOTChallenge][MOTChallenge] benchmarks [(*1)](#asterixcompare). Below are two results taken from MOTChallenge [Matlab devkit][devkit] corresponding to the results of the CEM tracker on the training set of the 2015 MOT 2DMark.
 
 ```
 
@@ -98,7 +96,7 @@ TUD-Campus     55.8% 73.0% 45.1% 58.2% 94.1%  8  1  6  1 13 150   7   7 52.6% 0.
 TUD-Stadtmitte 64.5% 82.0% 53.1% 60.9% 94.0% 10  5  4  1 45 452   7   6 56.4% 0.346
 ```
 
-Besides naming conventions, the only obvious differences are
+<a name="asterixcompare"></a>(*1) Besides naming conventions, the only obvious differences are
 - Metric `FAR` is missing. This metric is given implicitly and can be recovered by `FalsePos / Frames * 100`.
 - Metric `MOTP` seems to be off. To convert compute `(1 - MOTP) * 100`. [MOTChallenge][MOTChallenge] benchmarks compute `MOTP` as percentage, while **py-motmetrics** sticks to the original definition of average distance over number of assigned objects [[1]](#References).
 
@@ -111,25 +109,31 @@ For MOT16/17, you can run
 python -m motmetrics.apps.evaluateTracking --help
 ```
 
-### Installation
+## Installation
+
+To install latest development version of **py-motmetrics** (usually a bit more recent than PyPi below)
+
+```
+pip install git+https://github.com/cheind/py-motmetrics.git
+```
 
-#### PyPi and development installs
 
+### Install via PyPi
 To install **py-motmetrics** use `pip`
 
 ```
 pip install motmetrics
 ```
 
-Python 3.5/3.6 and numpy, pandas and scipy is required. If no binary packages are available for your platform and building source packages fails, you might want to try a distribution like Conda (see below) to install dependencies.
+Python 3.5/3.6/3.9 and numpy, pandas and scipy is required. If no binary packages are available for your platform and building source packages fails, you might want to try a distribution like Conda (see below) to install dependencies.
 
 Alternatively for developing, clone or fork this repository and install in editing mode.
 
 ```
 pip install -e <path/to/setup.py>
 ```
 
-#### Conda
+### Install via Conda
 In case you are using Conda, a simple way to run **py-motmetrics** is to create a virtual environment with all the necessary dependencies
 
 ```
@@ -153,9 +157,9 @@ pip install .
 pytest
 ```
 
-### Usage
+## Usage
 
-#### Populating the accumulator
+### Populating the accumulator
 
 ```python
 import motmetrics as mm
@@ -167,31 +171,31 @@ acc = mm.MOTAccumulator(auto_id=True)
 # Call update once for per frame. For now, assume distances between
 # frame objects / hypotheses are given.
 acc.update(
-    ['a', 'b'],                 # Ground truth objects in this frame
+    [1, 2],                     # Ground truth objects in this frame
     [1, 2, 3],                  # Detector hypotheses in this frame
     [
-        [0.1, np.nan, 0.3],     # Distances from object 'a' to hypotheses 1, 2, 3
-        [0.5,  0.2,   0.3]      # Distances from object 'b' to hypotheses 1, 2, 3
+        [0.1, np.nan, 0.3],     # Distances from object 1 to hypotheses 1, 2, 3
+        [0.5,  0.2,   0.3]      # Distances from object 2 to hypotheses 1, 2, 3
     ]
 )
 ```
 
-The code above updates an event accumulator with data from a single frame. Here we assume that pairwise object / hypothesis distances have already been computed. Note `np.nan` inside the distance matrix. It signals that `a` cannot be paired with hypothesis `2`. To inspect the current event history simple print the events associated with the accumulator.
+The code above updates an event accumulator with data from a single frame. Here we assume that pairwise object / hypothesis distances have already been computed. Note `np.nan` inside the distance matrix. It signals that object `1` cannot be paired with hypothesis `2`. To inspect the current event history simple print the events associated with the accumulator.
 
 ```python
 print(acc.events) # a pandas DataFrame containing all events
 
 """
                 Type  OId HId    D
 FrameId Event
-0       0        RAW    a   1  0.1
-        1        RAW    a   2  NaN
-        2        RAW    a   3  0.3
-        3        RAW    b   1  0.5
-        4        RAW    b   2  0.2
-        5        RAW    b   3  0.3
-        6      MATCH    a   1  0.1
-        7      MATCH    b   2  0.2
+0       0        RAW    1   1  0.1
+        1        RAW    1   2  NaN
+        2        RAW    1   3  0.3
+        3        RAW    2   1  0.5
+        4        RAW    2   2  0.2
+        5        RAW    2   3  0.3
+        6      MATCH    1   1  0.1
+        7      MATCH    2   2  0.2
         8         FP  NaN   3  NaN
 """
 ```
@@ -204,19 +208,19 @@ print(acc.mot_events) # a pandas DataFrame containing MOT only events
 """
                 Type  OId HId    D
 FrameId Event
-0       6      MATCH    a   1  0.1
-        7      MATCH    b   2  0.2
+0       6      MATCH    1   1  0.1
+        7      MATCH    2   2  0.2
         8         FP  NaN   3  NaN
 """
 ```
 
-Meaning object `a` was matched to hypothesis `1` with distance 0.1. Similarily, `b` was matched to `2` with distance 0.2. Hypothesis `3` could not be matched to any remaining object and generated a false positive (FP). Possible assignments are computed by minimizing the total assignment distance (Kuhn-Munkres algorithm).
+Meaning object `1` was matched to hypothesis `1` with distance 0.1. Similarily, object `2` was matched to hypothesis `2` with distance 0.2. Hypothesis `3` could not be matched to any remaining object and generated a false positive (FP). Possible assignments are computed by minimizing the total assignment distance (Kuhn-Munkres algorithm).
 
 Continuing from above
 
 ```python
 frameid = acc.update(
-    ['a', 'b'],
+    [1, 2],
     [1],
     [
         [0.2],
@@ -228,16 +232,16 @@ print(acc.mot_events.loc[frameid])
 """
         Type OId  HId    D
 Event
-2      MATCH   a    1  0.2
-3       MISS   b  NaN  NaN
+2      MATCH   1    1  0.2
+3       MISS   2  NaN  NaN
 """
 ```
 
-While `a` was matched, `b` couldn't be matched because no hypotheses are left to pair with.
+While object `1` was matched, object `2` couldn't be matched because no hypotheses are left to pair with.
 
 ```python
 frameid = acc.update(
-    ['a', 'b'],
+    [1, 2],
     [1, 3],
     [
         [0.6, 0.2],
@@ -249,14 +253,14 @@ print(acc.mot_events.loc[frameid])
 """
          Type OId HId    D
 Event
-4       MATCH   a   1  0.6
-5      SWITCH   b   3  0.6
+4       MATCH   1   1  0.6
+5      SWITCH   2   3  0.6
 """
 ```
 
-`b` is now tracked by hypothesis `3` leading to a track switch. Note, although a pairing `(a, 3)` with cost less than 0.6 is possible, the algorithm prefers prefers to continue track assignments from past frames which is a property of MOT metrics.
+Object `2` is now tracked by hypothesis `3` leading to a track switch. Note, although a pairing `(1, 3)` with cost less than 0.6 is possible, the algorithm prefers prefers to continue track assignments from past frames which is a property of MOT metrics.
 
-#### Computing metrics
+### Computing metrics
 Once the accumulator has been populated you can compute and display metrics. Continuing the example from above
 
 ```python
@@ -350,10 +354,10 @@ OVERALL 80.0% 80.0% 80.0% 80.0% 80.0%  4  2  2  0  2  2   1   1 50.0% 0.275
 """
 ```
 
-#### Computing distances
+### Computing distances
 Up until this point we assumed the pairwise object/hypothesis distances to be known. Usually this is not the case. You are mostly given either rectangles or points (centroids) of related objects. To compute a distance matrix from them you can use `motmetrics.distance` module as shown below.
 
-##### Euclidean norm squared on points
+#### Euclidean norm squared on points
 
 ```python
 # Object related points
@@ -378,7 +382,7 @@ C = mm.distances.norm2squared_matrix(o, h, max_d2=5.)
 """
 ```
 
-##### Intersection over union norm for 2D rectangles
+#### Intersection over union norm for 2D rectangles
 ```python
 a = np.array([
     [0, 0, 1, 2],    # Format X, Y, Width, Height
@@ -399,7 +403,7 @@ mm.distances.iou_matrix(a, b, max_iou=0.5)
 ```
 
 <a name="SolverBackends"></a>
-#### Solver backends
+### Solver backends
 For large datasets solving the minimum cost assignment becomes the dominant runtime part. **py-motmetrics** therefore supports these solvers out of the box
   - `lapsolver` - https://github.com/cheind/py-lapsolver
   - `lapjv` - https://github.com/gatagat/lap
@@ -422,7 +426,7 @@ with lap.set_default_solver(mysolver):
     ...
 ```
 
-### Running tests
+## Running tests
 **py-motmetrics** uses the pytest framework. To run the tests, simply `cd` into the source directly and run `pytest`.
 
 <a name="References"></a>
@@ -434,31 +438,31 @@ EURASIP Journal on Image and Video Processing 2008.1 (2008): 1-10.
 Computer Vision and Pattern Recognition, 2009. CVPR 2009. IEEE Conference on. IEEE, 2009.
 4. Performance Measures and a Data Set for Multi-Target, Multi-Camera Tracking. E. Ristani, F. Solera, R. S. Zou, R. Cucchiara and C. Tomasi. ECCV 2016 Workshop on Benchmarking Multi-Target Tracking.
 
-### Docker
+## Docker
 
-#### Update ground truth and test data:
+### Update ground truth and test data:
 /data/train directory should contain MOT 2D 2015 Ground Truth files.
 /data/test directory should contain your results.
 
 You can check usage and directory listing at
 https://github.com/cheind/py-motmetrics/blob/master/motmetrics/apps/eval_motchallenge.py
 
-#### Build Image
+### Build Image
 docker build -t desired-image-name -f Dockerfile .
 
-#### Run Image
+### Run Image
 docker run desired-image-name
 
 (credits to [christosavg](https://github.com/christosavg))
 
-### License
+## License
 
 ```
 MIT License
 
-Copyright (c) 2017-2020 Christoph Heindl
+Copyright (c) 2017-2022 Christoph Heindl
 Copyright (c) 2018 Toka
-Copyright (c) 2019-2020 Jack Valmadre
+Copyright (c) 2019-2022 Jack Valmadre
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal