{"id":9958,"library":"motmetrics","title":"Multiple Object Tracking Metrics (motmetrics)","description":"motmetrics is a Python library providing a comprehensive suite of metrics for benchmarking multiple object trackers (MOT). It simplifies the evaluation of tracker performance by handling associations between ground truth and hypothesis data, and calculating standard metrics like MOTA, MOTP, and more. The current version is 1.4.0, with an active but infrequent release cadence focused on maintenance and bug fixes.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/cheind/py-motmetrics","tags":["object-tracking","metrics","computer-vision","MOT"],"install":[{"cmd":"pip install motmetrics","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"MOTAccumulator","correct":"from motmetrics import MOTAccumulator"},{"symbol":"iou_matrix","correct":"from motmetrics.distances import iou_matrix"},{"note":"The 'create' function for metrics is located within 'motmetrics.metrics'. Importing from the top-level 'motmetrics' will result in an AttributeError.","wrong":"from motmetrics import create","symbol":"create","correct":"from motmetrics.metrics import create"}],"quickstart":{"code":"import motmetrics as mm\nimport numpy as np\n\n# Dummy data: Ground truth and tracker hypotheses for two frames\n# Format: [id, x, y, width, height] for bounding box coordinates\ngt_frame1 = np.array([[1, 10, 10, 5, 5], [2, 20, 20, 5, 5]])\nts_frame1 = np.array([[1, 10, 10, 5, 5], [2, 20, 20, 5, 5]])\n\ngt_frame2 = np.array([[1, 11, 11, 5, 5], [2, 21, 21, 5, 5]])\nts_frame2 = np.array([[1, 11, 11, 5, 5], [2, 21, 21, 5, 5]])\n\n# Create an accumulator to store tracking results\nacc = mm.MOTAccumulator(auto_id=True)\n\n# Process Frame 1:\n# Calculate Intersection over Union (IoU) distances between ground truth and hypotheses\n# Bounding boxes are expected as [x, y, width, height]\nC1 = mm.distances.iou_matrix(gt_frame1[:, 1:], ts_frame1[:, 1:], max_iou=0.5)\nacc.update(gt_frame1[:, 0], ts_frame1[:, 0], C1)\n\n# Process Frame 2:\nC2 = mm.distances.iou_matrix(gt_frame2[:, 1:], ts_frame2[:, 1:], max_iou=0.5)\nacc.update(gt_frame2[:, 0], ts_frame2[:, 0], C2)\n\n# Compute and display metrics\nmh = mm.metrics.create()\nsummary = mh.compute(acc, metrics=['mota', 'motp', 'num_frames'], name='dummy_tracking')\nprint(summary)","lang":"python","description":"Initialize a `MOTAccumulator`, then iterate frame by frame. For each frame, compute a distance matrix (e.g., IoU) between ground truth and tracker hypotheses bounding boxes, and update the accumulator. Finally, use `motmetrics.metrics.create()` to compute and display standard MOT metrics."},"warnings":[{"fix":"Upgrade motmetrics to version 1.4.0 or higher to resolve this: `pip install --upgrade motmetrics`.","message":"Older versions of motmetrics (prior to 1.4.0) may raise `FutureWarning: In the future `np.bool` will be a zero-dimensional array instead of a scalar instance.` when used with newer NumPy versions.","severity":"deprecated","affected_versions":"<1.4.0"},{"fix":"Ensure you are using motmetrics 1.4.0 or newer for accurate distance calculations, especially when using `motmetrics.utils.compare_to_groundtruth` with non-IoU metrics.","message":"The `motmetrics.utils.compare_to_groundtruth` function had a correction in version 1.4.0 regarding the usage of Euclidean distances. This could lead to subtle correctness issues or different results for users explicitly relying on that specific distance metric with older motmetrics versions.","severity":"gotcha","affected_versions":"<1.4.0"},{"fix":"Always ensure your bounding box data is in `[x, y, width, height]` format (often referred to as `xywh`) when passed to `motmetrics` distance functions like `iou_matrix`. Adjust your data preprocessing if necessary.","message":"Bounding box formats are crucial. `iou_matrix` and related distance functions primarily expect bounding boxes in `[x, y, width, height]` format. Misinterpreting this (e.g., using `x1, y1, x2, y2`) will lead to incorrect distance calculations and subsequently wrong metric results.","severity":"gotcha","affected_versions":"*"},{"fix":"Before passing ground truth and hypothesis IDs to `acc.update()`, verify that `gt_frame_ids` and `ts_frame_ids` contain unique identifiers for objects present in that specific frame.","message":"When processing data frame-by-frame, it's critical to ensure that object IDs within a single frame are unique for both ground truth and hypotheses. Duplicate IDs within a frame can lead to unexpected behavior or incorrect associations.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Import it from the `metrics` submodule: `from motmetrics.metrics import create` or access it as `mm.metrics.create()` if you imported `motmetrics as mm`.","cause":"The `create` function for instantiating a metrics host is not directly in the top-level `motmetrics` module.","error":"AttributeError: module 'motmetrics' has no attribute 'create'"},{"fix":"Ensure you are passing numpy arrays of shape `(N, 4)` (for N bounding boxes in `xywh` format) as the first two arguments to `iou_matrix`, not attempting to call an array object itself.","cause":"This typically occurs when attempting to call `iou_matrix` or other distance functions without providing the correct bounding box arguments, or if an argument is mistakenly treated as a function.","error":"TypeError: 'numpy.ndarray' object is not callable"},{"fix":"Verify that the number of ground truth IDs (`gt_ids.shape[0]`) matches the number of rows in your distance matrix (`C.shape[0]`), and similarly for hypothesis IDs (`ts_ids.shape[0] == C.shape[1]`) for the `acc.update(gt_ids, ts_ids, C)` call. The distance matrix `C` must precisely match the counts of ground truth and hypothesis objects for the current frame.","cause":"This error commonly arises within `acc.update()` if the number of ground truth IDs, hypothesis IDs, and the dimensions of the distance matrix do not align.","error":"ValueError: operands could not be broadcast together with shapes (X) (Y)"}]}