{"id":13443719,"url":"https://github.com/cheind/py-motmetrics","last_synced_at":"2025-05-14T11:09:42.794Z","repository":{"id":37669296,"uuid":"87559569","full_name":"cheind/py-motmetrics","owner":"cheind","description":":bar_chart: Benchmark multiple object trackers (MOT) in Python","archived":false,"fork":false,"pushed_at":"2024-07-04T18:37:09.000Z","size":7160,"stargazers_count":1378,"open_issues_count":61,"forks_count":258,"subscribers_count":23,"default_branch":"develop","last_synced_at":"2024-10-29T15:35:07.635Z","etag":null,"topics":["benchmark","clear-mot-metrics","metrics","mot","mot-challenge","object-detection","object-tracking","tracker"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheind.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-07T15:16:59.000Z","updated_at":"2024-10-28T12:13:13.000Z","dependencies_parsed_at":"2023-01-30T23:45:19.535Z","dependency_job_id":"e8f9caed-7e4b-47e6-a0b9-c5eb94705f87","html_url":"https://github.com/cheind/py-motmetrics","commit_stats":{"total_commits":334,"total_committers":23,"mean_commits":"14.521739130434783","dds":"0.39820359281437123","last_synced_commit":"b68701366b3eee2e41e3273e3a7c9d27fc9cd71a"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheind%2Fpy-motmetrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheind%2Fpy-motmetrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheind%2Fpy-motmetrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheind%2Fpy-motmetrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheind","download_url":"https://codeload.github.com/cheind/py-motmetrics/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129489,"owners_count":22019628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["benchmark","clear-mot-metrics","metrics","mot","mot-challenge","object-detection","object-tracking","tracker"],"created_at":"2024-07-31T03:02:07.994Z","updated_at":"2025-05-14T11:09:42.741Z","avatar_url":"https://github.com/cheind.png","language":"Python","funding_links":[],"categories":["Python","评估指标","Evaluation"],"sub_categories":["SoccerNet Tracking"],"readme":"[![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) [![DOI](https://zenodo.org/badge/87559569.svg)](https://doi.org/10.5281/zenodo.14014773)\n\n# py-motmetrics\n\nThe **py-motmetrics** library provides a Python implementation of metrics for benchmarking multiple object trackers (MOT).\n\nWhile benchmarking single object trackers is rather straightforward, measuring the performance of multiple object trackers needs careful design as multiple correspondence constellations can arise (see image below). A variety of methods have been proposed in the past and while there is no general agreement on a single method, the methods of [[1,2,3,4]](#References) have received considerable attention in recent years. **py-motmetrics** implements these [metrics](#Metrics).\n\n\u003cdiv style=\"text-align:center;\"\u003e\n\n![](./motmetrics/etc/mot.png)\u003cbr/\u003e\n\n_Pictures courtesy of Bernardin, Keni, and Rainer Stiefelhagen [[1]](#References)_\n\n\u003c/div\u003e\n\nIn 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.\n\n## Features at a glance\n\n-   _Variety of metrics_ \u003cbr/\u003e\n    Provides MOTA, MOTP, track quality measures, global ID measures and more. The results are [comparable](#MOTChallengeCompatibility) with the popular [MOTChallenge][motchallenge] benchmarks [(\\*1)](#asterixcompare).\n-   _Distance agnostic_ \u003cbr/\u003e\n    Supports Euclidean, Intersection over Union and other distances measures.\n-   _Complete event history_ \u003cbr/\u003e\n    Tracks all relevant per-frame events suchs as correspondences, misses, false alarms and switches.\n-   _Flexible solver backend_ \u003cbr/\u003e\n    Support for switching minimum assignment cost solvers. Supports `scipy`, `ortools`, `munkres` out of the box. Auto-tunes solver selection based on [availability and problem size](#SolverBackends).\n-   _Easy to extend_ \u003cbr/\u003e\n    Events and summaries are utilizing [pandas][pandas] for data structures and analysis. New metrics can reuse already computed values from depending metrics.\n\n\u003ca name=\"Metrics\"\u003e\u003c/a\u003e\n\n## Metrics\n\n**py-motmetrics** implements the following metrics. The metrics have been aligned with what is reported by [MOTChallenge][motchallenge] benchmarks.\n\n```python\nimport motmetrics as mm\n# List all default metrics\nmh = mm.metrics.create()\nprint(mh.list_metrics_markdown())\n```\n\n| Name                 | Description                                                                        |\n| :------------------- | :--------------------------------------------------------------------------------- |\n| num_frames           | Total number of frames.                                                            |\n| num_matches          | Total number matches.                                                              |\n| num_switches         | Total number of track switches.                                                    |\n| num_false_positives  | Total number of false positives (false-alarms).                                    |\n| num_misses           | Total number of misses.                                                            |\n| num_detections       | Total number of detected objects including matches and switches.                   |\n| num_objects          | Total number of unique object appearances over all frames.                         |\n| num_predictions      | Total number of unique prediction appearances over all frames.                     |\n| num_unique_objects   | Total number of unique object ids encountered.                                     |\n| mostly_tracked       | Number of objects tracked for at least 80 percent of lifespan.                     |\n| partially_tracked    | Number of objects tracked between 20 and 80 percent of lifespan.                   |\n| mostly_lost          | Number of objects tracked less than 20 percent of lifespan.                        |\n| num_fragmentations   | Total number of switches from tracked to not tracked.                              |\n| motp                 | Multiple object tracker precision.                                                 |\n| mota                 | Multiple object tracker accuracy.                                                  |\n| precision            | Number of detected objects over sum of detected and false positives.               |\n| recall               | Number of detections over number of objects.                                       |\n| idfp                 | ID measures: Number of false positive matches after global min-cost matching.      |\n| idfn                 | ID measures: Number of false negatives matches after global min-cost matching.     |\n| idtp                 | ID measures: Number of true positives matches after global min-cost matching.      |\n| idp                  | ID measures: global min-cost precision.                                            |\n| idr                  | ID measures: global min-cost recall.                                               |\n| idf1                 | ID measures: global min-cost F1 score.                                             |\n| obj_frequencies      | `pd.Series` Total number of occurrences of individual objects over all frames.     |\n| pred_frequencies     | `pd.Series` Total number of occurrences of individual predictions over all frames. |\n| track_ratios         | `pd.Series` Ratio of assigned to total appearance count per unique object id.      |\n| id_global_assignment | `dict` ID measures: Global min-cost assignment for ID measures.                    |\n| deta_alpha           | HOTA: Detection Accuracy (DetA) for a given threshold.                             |\n| assa_alpha           | HOTA: Association Accuracy (AssA) for a given threshold.                           |\n| hota_alpha           | HOTA: Higher Order Tracking Accuracy (HOTA) for a given threshold.                 |\n\n\u003ca name=\"MOTChallengeCompatibility\"\u003e\u003c/a\u003e\n\n## MOTChallenge compatibility\n\n**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.\n\n```\n\nTUD-Campus\n IDF1  IDP  IDR| Rcll  Prcn   FAR| GT  MT  PT  ML|   FP    FN  IDs   FM| MOTA  MOTP MOTAL\n 55.8 73.0 45.1| 58.2  94.1  0.18|  8   1   6   1|   13   150    7    7| 52.6  72.3  54.3\n\nTUD-Stadtmitte\n IDF1  IDP  IDR| Rcll  Prcn   FAR| GT  MT  PT  ML|   FP    FN  IDs   FM| MOTA  MOTP MOTAL\n 64.5 82.0 53.1| 60.9  94.0  0.25| 10   5   4   1|   45   452    7    6| 56.4  65.4  56.9\n\n```\n\nIn comparison to **py-motmetrics**\n\n```\n                IDF1   IDP   IDR  Rcll  Prcn GT MT PT ML FP  FN IDs  FM  MOTA  MOTP\nTUD-Campus     55.8% 73.0% 45.1% 58.2% 94.1%  8  1  6  1 13 150   7   7 52.6% 0.277\nTUD-Stadtmitte 64.5% 82.0% 53.1% 60.9% 94.0% 10  5  4  1 45 452   7   6 56.4% 0.346\n```\n\n\u003ca name=\"asterixcompare\"\u003e\u003c/a\u003e(\\*1) Besides naming conventions, the only obvious differences are\n\n-   Metric `FAR` is missing. This metric is given implicitly and can be recovered by `FalsePos / Frames * 100`.\n-   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).\n\nYou can compare tracker results to ground truth in MOTChallenge format by\n\n```\npython -m motmetrics.apps.eval_motchallenge --help\n```\n\nFor MOT16/17, you can run\n\n```\npython -m motmetrics.apps.evaluateTracking --help\n```\n\n## Installation\n\nTo install latest development version of **py-motmetrics** (usually a bit more recent than PyPi below)\n\n```\npip install git+https://github.com/cheind/py-motmetrics.git\n```\n\n### Install via PyPi\n\nTo install **py-motmetrics** use `pip`\n\n```\npip install motmetrics\n```\n\nPython 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.\n\nAlternatively for developing, clone or fork this repository and install in editing mode.\n\n```\npip install -e \u003cpath/to/setup.py\u003e\n```\n\n### Install via Conda\n\nIn case you are using Conda, a simple way to run **py-motmetrics** is to create a virtual environment with all the necessary dependencies\n\n```\nconda env create -f environment.yml\n\u003e activate motmetrics-env\n```\n\nThen activate / source the `motmetrics-env` and install **py-motmetrics** and run the tests.\n\n```\nactivate motmetrics-env\npip install .\npytest\n```\n\nIn case you already have an environment you install the dependencies from within your environment by\n\n```\nconda install --file requirements.txt\npip install .\npytest\n```\n\n## Usage\n\n### Populating the accumulator\n\n```python\nimport motmetrics as mm\nimport numpy as np\n\n# Create an accumulator that will be updated during each frame\nacc = mm.MOTAccumulator(auto_id=True)\n\n# Call update once for per frame. For now, assume distances between\n# frame objects / hypotheses are given.\nacc.update(\n    [1, 2],                     # Ground truth objects in this frame\n    [1, 2, 3],                  # Detector hypotheses in this frame\n    [\n        [0.1, np.nan, 0.3],     # Distances from object 1 to hypotheses 1, 2, 3\n        [0.5,  0.2,   0.3]      # Distances from object 2 to hypotheses 1, 2, 3\n    ]\n)\n```\n\nThe 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.\n\n```python\nprint(acc.events) # a pandas DataFrame containing all events\n\n\"\"\"\n                Type  OId HId    D\nFrameId Event\n0       0        RAW    1   1  0.1\n        1        RAW    1   2  NaN\n        2        RAW    1   3  0.3\n        3        RAW    2   1  0.5\n        4        RAW    2   2  0.2\n        5        RAW    2   3  0.3\n        6      MATCH    1   1  0.1\n        7      MATCH    2   2  0.2\n        8         FP  NaN   3  NaN\n\"\"\"\n```\n\nThe above data frame contains `RAW` and MOT events. To obtain just MOT events type\n\n```python\nprint(acc.mot_events) # a pandas DataFrame containing MOT only events\n\n\"\"\"\n                Type  OId HId    D\nFrameId Event\n0       6      MATCH    1   1  0.1\n        7      MATCH    2   2  0.2\n        8         FP  NaN   3  NaN\n\"\"\"\n```\n\nMeaning 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).\n\nContinuing from above\n\n```python\nframeid = acc.update(\n    [1, 2],\n    [1],\n    [\n        [0.2],\n        [0.4]\n    ]\n)\nprint(acc.mot_events.loc[frameid])\n\n\"\"\"\n        Type OId  HId    D\nEvent\n2      MATCH   1    1  0.2\n3       MISS   2  NaN  NaN\n\"\"\"\n```\n\nWhile object `1` was matched, object `2` couldn't be matched because no hypotheses are left to pair with.\n\n```python\nframeid = acc.update(\n    [1, 2],\n    [1, 3],\n    [\n        [0.6, 0.2],\n        [0.1, 0.6]\n    ]\n)\nprint(acc.mot_events.loc[frameid])\n\n\"\"\"\n         Type OId HId    D\nEvent\n4       MATCH   1   1  0.6\n5      SWITCH   2   3  0.6\n\"\"\"\n```\n\nObject `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.\n\n### Computing metrics\n\nOnce the accumulator has been populated you can compute and display metrics. Continuing the example from above\n\n```python\nmh = mm.metrics.create()\nsummary = mh.compute(acc, metrics=['num_frames', 'mota', 'motp'], name='acc')\nprint(summary)\n\n\"\"\"\n     num_frames  mota  motp\nacc           3   0.5  0.34\n\"\"\"\n```\n\nComputing metrics for multiple accumulators or accumulator views is also possible\n\n```python\nsummary = mh.compute_many(\n    [acc, acc.events.loc[0:1]],\n    metrics=['num_frames', 'mota', 'motp'],\n    names=['full', 'part'])\nprint(summary)\n\n\"\"\"\n      num_frames  mota      motp\nfull           3   0.5  0.340000\npart           2   0.5  0.166667\n\"\"\"\n```\n\nFinally, you may want to reformat column names and how column values are displayed.\n\n```python\nstrsummary = mm.io.render_summary(\n    summary,\n    formatters={'mota' : '{:.2%}'.format},\n    namemap={'mota': 'MOTA', 'motp' : 'MOTP'}\n)\nprint(strsummary)\n\n\"\"\"\n      num_frames   MOTA      MOTP\nfull           3 50.00%  0.340000\npart           2 50.00%  0.166667\n\"\"\"\n```\n\nFor MOTChallenge **py-motmetrics** provides predefined metric selectors, formatters and metric names, so that the result looks alike what is provided via their Matlab `devkit`.\n\n```python\nsummary = mh.compute_many(\n    [acc, acc.events.loc[0:1]],\n    metrics=mm.metrics.motchallenge_metrics,\n    names=['full', 'part'])\n\nstrsummary = mm.io.render_summary(\n    summary,\n    formatters=mh.formatters,\n    namemap=mm.io.motchallenge_metric_names\n)\nprint(strsummary)\n\n\"\"\"\n      IDF1   IDP   IDR  Rcll  Prcn GT MT PT ML FP FN IDs  FM  MOTA  MOTP\nfull 83.3% 83.3% 83.3% 83.3% 83.3%  2  1  1  0  1  1   1   1 50.0% 0.340\npart 75.0% 75.0% 75.0% 75.0% 75.0%  2  1  1  0  1  1   0   0 50.0% 0.167\n\"\"\"\n```\n\nIn order to generate an overall summary that computes the metrics jointly over all accumulators add `generate_overall=True` as follows\n\n```python\nsummary = mh.compute_many(\n    [acc, acc.events.loc[0:1]],\n    metrics=mm.metrics.motchallenge_metrics,\n    names=['full', 'part'],\n    generate_overall=True\n    )\n\nstrsummary = mm.io.render_summary(\n    summary,\n    formatters=mh.formatters,\n    namemap=mm.io.motchallenge_metric_names\n)\nprint(strsummary)\n\n\"\"\"\n         IDF1   IDP   IDR  Rcll  Prcn GT MT PT ML FP FN IDs  FM  MOTA  MOTP\nfull    83.3% 83.3% 83.3% 83.3% 83.3%  2  1  1  0  1  1   1   1 50.0% 0.340\npart    75.0% 75.0% 75.0% 75.0% 75.0%  2  1  1  0  1  1   0   0 50.0% 0.167\nOVERALL 80.0% 80.0% 80.0% 80.0% 80.0%  4  2  2  0  2  2   1   1 50.0% 0.275\n\"\"\"\n```\n\n#### [Underdeveloped] Computing HOTA metrics\n\nComputing HOTA metrics is also possible. However, it cannot be used with the `Accumulator` class directly, as HOTA requires to computing a reweighting matrix from all the frames at the beginning. Here is an example of how to use it:\n\n```python\nimport os\nimport numpy as np\nimport motmetrics as mm\n\n\ndef compute_motchallenge(dir_name):\n    # `gt.txt` and `test.txt` should be prepared in MOT15 format\n    df_gt = mm.io.loadtxt(os.path.join(dir_name, \"gt.txt\"))\n    df_test = mm.io.loadtxt(os.path.join(dir_name, \"test.txt\"))\n    # Require different thresholds for matching\n    th_list = np.arange(0.05, 0.99, 0.05)\n    res_list = mm.utils.compare_to_groundtruth_reweighting(df_gt, df_test, \"iou\", distth=th_list)\n    return res_list\n\n# `data_dir` is the directory containing the gt.txt and test.txt files\nacc = compute_motchallenge(\"data_dir\")\nmh = mm.metrics.create()\n\nsummary = mh.compute_many(\n    acc,\n    metrics=[\n        \"deta_alpha\",\n        \"assa_alpha\",\n        \"hota_alpha\",\n    ],\n    generate_overall=True,  # `Overall` is the average we need only\n)\nstrsummary = mm.io.render_summary(\n    summary.iloc[[-1], :],  # Use list to preserve `DataFrame` type\n    formatters=mh.formatters,\n    namemap={\"hota_alpha\": \"HOTA\", \"assa_alpha\": \"ASSA\", \"deta_alpha\": \"DETA\"},\n)\nprint(strsummary)\n\"\"\"\n# data_dir=motmetrics/data/TUD-Campus\n         DETA  ASSA  HOTA\nOVERALL 41.8% 36.9% 39.1%\n# data_dir=motmetrics/data/TUD-Stadtmitte\n         DETA  ASSA  HOTA\nOVERALL 39.2% 40.9% 39.8%\n\"\"\"\n```\n\n### Computing distances\n\nUp 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.\n\n#### Euclidean norm squared on points\n\n```python\n# Object related points\no = np.array([\n    [1., 2],\n    [2., 2],\n    [3., 2],\n])\n\n# Hypothesis related points\nh = np.array([\n    [0., 0],\n    [1., 1],\n])\n\nC = mm.distances.norm2squared_matrix(o, h, max_d2=5.)\n\n\"\"\"\n[[  5.   1.]\n [ nan   2.]\n [ nan   5.]]\n\"\"\"\n```\n\n#### Intersection over union norm for 2D rectangles\n\n```python\na = np.array([\n    [0, 0, 1, 2],    # Format X, Y, Width, Height\n    [0, 0, 0.8, 1.5],\n])\n\nb = np.array([\n    [0, 0, 1, 2],\n    [0, 0, 1, 1],\n    [0.1, 0.2, 2, 2],\n])\nmm.distances.iou_matrix(a, b, max_iou=0.5)\n\n\"\"\"\n[[ 0.          0.5                nan]\n [ 0.4         0.42857143         nan]]\n\"\"\"\n```\n\n\u003ca name=\"SolverBackends\"\u003e\u003c/a\u003e\n\n### Solver backends\n\nFor large datasets solving the minimum cost assignment becomes the dominant runtime part. **py-motmetrics** therefore supports these solvers out of the box\n\n-   `lapsolver` - https://github.com/cheind/py-lapsolver\n-   `lapjv` - https://github.com/gatagat/lap\n-   `scipy` - https://github.com/scipy/scipy/tree/master/scipy\n-   `ortools\u003c9.4` - https://github.com/google/or-tools\n-   `munkres` - http://software.clapper.org/munkres/\n\nA comparison for different sized matrices is shown below (taken from [here](https://github.com/cheind/py-lapsolver#benchmarks))\n\nPlease note that the x-axis is scaled logarithmically. Missing bars indicate excessive runtime or errors in returned result.\n![](https://github.com/cheind/py-lapsolver/raw/master/lapsolver/etc/benchmark-dtype-numpy.float32.png)\n\nBy default **py-motmetrics** will try to find a LAP solver in the order of the list above. In order to temporarly replace the default solver use\n\n```python\ncosts = ...\nmysolver = lambda x: ... # solver code that returns pairings\n\nwith lap.set_default_solver(mysolver):\n    ...\n```\n\n## For custom dataset\n\nUse this section as a guide for calculating MOT metrics for your custom dataset.\n\nBefore you begin, make sure to have Ground truth and your Tracker output data in the form of text files. The code below assumes MOT16 format for the ground truth as well as the tracker ouput. The data is arranged in the following sequence:\n\n````\n\u003cframe number\u003e, \u003cobject id\u003e, \u003cbb_left\u003e, \u003cbb_top\u003e, \u003cbb_width\u003e, \u003cbb_height\u003e, \u003cconfidence\u003e, \u003cx\u003e, \u003cy\u003e, \u003cz\u003e\n````\n\nA sample ground truth/tracker output file is shown below. If you are using a custom dataset, then it is highly likely that you will have to create your own ground truth file. If you already have a MOT16 format ground truth file, you can use it directly otherwise, you will need a MOT16 annotator tool to create the annotations (ground truth). You can use any tool to create your ground truth data, just make sure it is as per MOT16 format.\n\nIf you can't find a tool to create your ground truth files, you can use this free MOT16 annotator [tool](https://github.com/khalidw/MOT16_Annotator) to create ground truth for your dataset which can then be used in conjunction with your tracker output to generate the MOT metrics.\n\n````\n1,1,763.00,272.00,189.00,38.00,1,-1,-1,-1\n1,2,412.00,265.00,153.00,30.00,1,-1,-1,-1\n2,1,762.00,269.00,185.00,41.00,1,-1,-1,-1\n2,2,413.00,267.00,151.00,26.00,1,-1,-1,-1\n3,1,760.00,272.00,186.00,38.00,1,-1,-1,-1\n````\n\nYou can read more about MOT16 format [here](https://arxiv.org/abs/1603.00831).\n\nFollowing function loads the ground truth and tracker object files, processes them and produces a set of metrices.\n\n```python\ndef motMetricsEnhancedCalculator(gtSource, tSource):\n  # import required packages\n  import motmetrics as mm\n  import numpy as np\n  \n  # load ground truth\n  gt = np.loadtxt(gtSource, delimiter=',')\n\n  # load tracking output\n  t = np.loadtxt(tSource, delimiter=',')\n\n  # Create an accumulator that will be updated during each frame\n  acc = mm.MOTAccumulator(auto_id=True)\n\n  # Max frame number maybe different for gt and t files\n  for frame in range(int(gt[:,0].max())):\n    frame += 1 # detection and frame numbers begin at 1\n\n    # select id, x, y, width, height for current frame\n    # required format for distance calculation is X, Y, Width, Height \\\n    # We already have this format\n    gt_dets = gt[gt[:,0]==frame,1:6] # select all detections in gt\n    t_dets = t[t[:,0]==frame,1:6] # select all detections in t\n\n    C = mm.distances.iou_matrix(gt_dets[:,1:], t_dets[:,1:], \\\n                                max_iou=0.5) # format: gt, t\n\n    # Call update once for per frame.\n    # format: gt object ids, t object ids, distance\n    acc.update(gt_dets[:,0].astype('int').tolist(), \\\n              t_dets[:,0].astype('int').tolist(), C)\n\n  mh = mm.metrics.create()\n\n  summary = mh.compute(acc, metrics=['num_frames', 'idf1', 'idp', 'idr', \\\n                                     'recall', 'precision', 'num_objects', \\\n                                     'mostly_tracked', 'partially_tracked', \\\n                                     'mostly_lost', 'num_false_positives', \\\n                                     'num_misses', 'num_switches', \\\n                                     'num_fragmentations', 'mota', 'motp' \\\n                                    ], \\\n                      name='acc')\n\n  strsummary = mm.io.render_summary(\n      summary,\n      #formatters={'mota' : '{:.2%}'.format},\n      namemap={'idf1': 'IDF1', 'idp': 'IDP', 'idr': 'IDR', 'recall': 'Rcll', \\\n               'precision': 'Prcn', 'num_objects': 'GT', \\\n               'mostly_tracked' : 'MT', 'partially_tracked': 'PT', \\\n               'mostly_lost' : 'ML', 'num_false_positives': 'FP', \\\n               'num_misses': 'FN', 'num_switches' : 'IDsw', \\\n               'num_fragmentations' : 'FM', 'mota': 'MOTA', 'motp' : 'MOTP',  \\\n              }\n  )\n  print(strsummary)\n```\n\nRun the function by pointing to the ground truth and tracker output file. A sample output is shown below.\n\n```python\n# Calculate the MOT metrics\nmotMetricsEnhancedCalculator('gt/groundtruth.txt', \\\n                             'to/trackeroutput.txt')\n\"\"\"\n     num_frames  IDF1       IDP       IDR      Rcll      Prcn   GT  MT  PT  ML  FP  FN  IDsw  FM      MOTA      MOTP\nacc         150  0.75  0.857143  0.666667  0.743295  0.955665  261   0   2   0   9  67     1  12  0.704981  0.244387\n\"\"\"\n```\n\n## Running tests\n\n**py-motmetrics** uses the pytest framework. To run the tests, simply `cd` into the source directly and run `pytest`.\n\n\u003ca name=\"References\"\u003e\u003c/a\u003e\n\n### References\n\n1. Bernardin, Keni, and Rainer Stiefelhagen. \"Evaluating multiple object tracking performance: the CLEAR MOT metrics.\"\n   EURASIP Journal on Image and Video Processing 2008.1 (2008): 1-10.\n2. Milan, Anton, et al. \"Mot16: A benchmark for multi-object tracking.\" arXiv preprint arXiv:1603.00831 (2016).\n3. Li, Yuan, Chang Huang, and Ram Nevatia. \"Learning to associate: Hybridboosted multi-target tracker for crowded scene.\"\n   Computer Vision and Pattern Recognition, 2009. CVPR 2009. IEEE Conference on. IEEE, 2009.\n4. 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.\n\n## Docker\n\n### Update ground truth and test data:\n\n/data/train directory should contain MOT 2D 2015 Ground Truth files.\n/data/test directory should contain your results.\n\nYou can check usage and directory listing at\nhttps://github.com/cheind/py-motmetrics/blob/master/motmetrics/apps/eval_motchallenge.py\n\n### Build Image\n\ndocker build -t desired-image-name -f Dockerfile .\n\n### Run Image\n\ndocker run desired-image-name\n\n(credits to [christosavg](https://github.com/christosavg))\n\n## License\n\n```\nMIT License\n\nCopyright (c) 2017-2022 Christoph Heindl\nCopyright (c) 2018 Toka\nCopyright (c) 2019-2022 Jack Valmadre\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n[pandas]: http://pandas.pydata.org/\n[motchallenge]: https://motchallenge.net/\n[devkit]: https://motchallenge.net/devkit/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheind%2Fpy-motmetrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheind%2Fpy-motmetrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheind%2Fpy-motmetrics/lists"}