{"id":13643980,"url":"https://github.com/opendatacam/node-moving-things-tracker","last_synced_at":"2025-04-29T09:31:15.881Z","repository":{"id":35695911,"uuid":"113296661","full_name":"opendatacam/node-moving-things-tracker","owner":"opendatacam","description":"javascript implementation of \"tracker by detections\" for realtime multiple object tracking (MOT)","archived":false,"fork":false,"pushed_at":"2022-12-06T21:35:51.000Z","size":2124,"stargazers_count":107,"open_issues_count":11,"forks_count":26,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-05T14:41:54.767Z","etag":null,"topics":["algorithm","detections","mot","opendatacam","tracker","yolo"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/opendatacam.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}},"created_at":"2017-12-06T09:34:23.000Z","updated_at":"2024-12-05T01:51:31.000Z","dependencies_parsed_at":"2023-01-16T03:30:52.718Z","dependency_job_id":null,"html_url":"https://github.com/opendatacam/node-moving-things-tracker","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendatacam%2Fnode-moving-things-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendatacam%2Fnode-moving-things-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendatacam%2Fnode-moving-things-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opendatacam%2Fnode-moving-things-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opendatacam","download_url":"https://codeload.github.com/opendatacam/node-moving-things-tracker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251473236,"owners_count":21595027,"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":["algorithm","detections","mot","opendatacam","tracker","yolo"],"created_at":"2024-08-02T01:01:55.754Z","updated_at":"2025-04-29T09:31:14.603Z","avatar_url":"https://github.com/opendatacam.png","language":"JavaScript","readme":"# node-moving-things-tracker\n\nnode-moving-things-tracker is a javascript implementation of a _\"tracker by detections\"_ for realtime multiple object tracking (MOT) in node.js / browsers. \n\nCommissioned by moovel lab for [Beat the Traffic X](http://beatthetraffic.moovellab.com/) and the [Open Data Cam](http://opendatacam.moovellab.com/) project.\n\n## Problem\n\nHow to track persistently multiple moving things from frame-by-frame object detections inputs? How to assign an unique identifier to frame-by-frame object detection results?\n\nOften object detection framework don't have any memory of their detection results over time e.g. Yolo provides every frame an array of detections results in the form of `[[x,y,w,h,confidence,name] ...]`, note that there isn't any unique ID to indentify the same detected object in future frames.\n\n**Detections Input**\n\nRaw Yolo detection results\n\n![detections](https://user-images.githubusercontent.com/533590/33817459-030e3822-de40-11e7-979d-0c8071ea2a94.gif)\n\n**Tracker Output**\n\nYolo detection results enhanced with unique IDs after beeing processed by node-moving-things-tracker. Note that now every object has been assigned an unique ID\n\n![tracker](https://user-images.githubusercontent.com/533590/33817550-6913047c-de40-11e7-8552-f284c738f1c0.gif)\n\n## Installation\n\n```bash\n# Install globaly to use as command line tool\nnpm install -g node-moving-things-tracker \n\n# Install localy your node.js / javascript project\nnpm install --save node-moving-things-tracker \n```\n\n## Usage\n\n**As a node module**\n\n```javascript\nconst Tracker = require('node-moving-things-tracker').Tracker;\n\nTracker.updateTrackedItemsWithNewFrame(detectionScaledOfThisFrame, currentFrame);\n\nconst trackerDataForThisFrame = Tracker.getJSONOfTrackedItems();\n```\n\nExample: [`Opendatacam.js`](https://github.com/opendatacam/opendatacam/blob/master/server/Opendatacam.js#L228) of the Open Data Cam project.\n\n**Command line usage**\n\nnode-moving-things-tracker takes as an input a txt file generated by [node-yolo](https://github.com/moovel/node-yolo) and outputs a `tracker.json` file that assigns unique IDs to the YOLO detections bbox.\n\nThe detections entry file could also be generated by another object detection algorithm than YOLO, it just needs to respects the [same format](https://github.com/tdurand/node-moving-things-tracker#detections-input-and-tracker-output-format).\n\n\u003e NOTE : usage is customized for the use case of [Beat the Traffic X](https://beatthetraffic.moovellab.com) \n\n```bash\nnode-moving-things-tracker --input PATH_TO_YOLO_DETECTIONS.txt\n# This will output a tracker.json file in the same folder containing the tracker data\n```\n\n## Detections Input and tracker output format\n\nSee example [here](https://github.com/tdurand/node-moving-things-tracker/tree/master/example): \n\n**Coordinate space:**\n\n![coordinates of tracker input](https://user-images.githubusercontent.com/533590/35881673-60f4e8f8-0b60-11e8-837c-b2b8ec3bff67.jpg)\n\n**Detections Input**\n\nrawdetections.txt\n\n```json\n{\"frame\":0,\"detections\":[{\"x\":699,\"y\":99,\"w\":32,\"h\":19,\"confidence\":34,\"name\":\"car\"},{\"x\":285,\"y\":170,\"w\":40,\"h\":32,\"confidence\":26,\"name\":\"car\"},{\"x\":259,\"y\":178,\"w\":75,\"h\":46,\"confidence\":42,\"name\":\"car\"},{\"x\":39,\"y\":222,\"w\":91,\"h\":52,\"confidence\":61,\"name\":\"car\"},{\"x\":148,\"y\":199,\"w\":123,\"h\":55,\"confidence\":53,\"name\":\"car\"}]}\n{\"frame\":1,\"detections\":[{\"x\":699,\"y\":99,\"w\":32,\"h\":19,\"confidence\":31,\"name\":\"car\"},{\"x\":694,\"y\":116,\"w\":34,\"h\":23,\"confidence\":25,\"name\":\"car\"},{\"x\":285,\"y\":170,\"w\":40,\"h\":32,\"confidence\":27,\"name\":\"car\"},{\"x\":259,\"y\":178,\"w\":75,\"h\":46,\"confidence\":42,\"name\":\"car\"},{\"x\":39,\"y\":222,\"w\":91,\"h\":52,\"confidence\":61,\"name\":\"car\"},{\"x\":148,\"y\":199,\"w\":123,\"h\":55,\"confidence\":52,\"name\":\"car\"}]}\n```\n\n**Tracker Output**\n\n_Normal mode:_\n\n```javascript\n{\n  // Tracker data for each frame\n  \"43\": [\n    {      \n      \"id\": 0,\n      \"x\": 628,\n      \"y\": 144,\n      \"w\": 48,\n      \"h\": 29,\n      \"confidence\": 80,\n      \"name\": \"car\",\n      \"isZombie\": false\n    },\n    {\n      \"id\": 1,\n      \"x\": 620,\n      \"y\": 154,\n      \"w\": 50,\n      \"h\": 35,\n      \"confidence\": 80,\n      \"name\": \"car\",\n      \"isZombie\": true\n    }\n  ]\n}\n```\n\n_Debug mode:_\n\n```bash\n#Run with ---debug flag at the end\nnode-moving-things-tracker --debug --input PATH_TO_YOLO_DETECTIONS.txt\n```\n\n```javascript\n{\n  // Tracker data for each frame\n  \"43\": [\n    {\n      \"id\": \"900e36a2-cbc7-427c-83a9-819d072391f0\",\n      \"idDisplay\": 0,\n      \"x\": 628,\n      \"y\": 144,\n      \"w\": 48,\n      \"h\": 29,\n      \"confidence\": 80,\n      \"name\": \"car\",\n      \"isZombie\": false,\n      \"zombieOpacity\": 1,\n      \"appearFrame\": 35,\n      \"disappearFrame\": null\n    },\n    {\n      \"id\": \"38939c38-c977-40a9-ad6a-3bb916c37fa1\",\n      \"idDisplay\": 1,\n      \"x\": 620,\n      \"y\": 154,\n      \"w\": 50,\n      \"h\": 35,\n      \"confidence\": 80,\n      \"name\": \"car\",\n      \"isZombie\": false,\n      \"zombieOpacity\": 1,\n      \"appearFrame\": 43,\n      \"disappearFrame\": null\n    }\n  ]\n}\n```\n\n# Run on opendatacam/darknet detection data\n\nUsage with opendatacam/darknet (https://github.com/opendatacam/darknet/pull/2) generated tracker data \n\n```bash\nnode-moving-things-tracker --mode opendatacam-darknet --input detectionsFromDarknet.json\n# This will output a tracker.json file in the same folder containing the tracker data\n# Output format is the same as previously\n```\n\nExample detections.json file\n\n```json\n[\n  {\n    \"frame_id\":0, \n    \"objects\": [ \n      {\"class_id\":5, \"name\":\"bus\", \"relative_coordinates\":{\"center_x\":0.394363, \"center_y\":0.277938, \"width\":0.032596, \"height\":0.106158}, \"confidence\":0.414157}, \n      {\"class_id\":5, \"name\":\"bus\", \"relative_coordinates\":{\"center_x\":0.363555, \"center_y\":0.285264, \"width\":0.062474, \"height\":0.133008}, \"confidence\":0.402736}\n    ] \n  },\n  {\n    \"frame_id\":0, \n    \"objects\": [ \n      {\"class_id\":5, \"name\":\"bus\", \"relative_coordinates\":{\"center_x\":0.394363, \"center_y\":0.277938, \"width\":0.032596, \"height\":0.106158}, \"confidence\":0.414157}, \n      {\"class_id\":5, \"name\":\"bus\", \"relative_coordinates\":{\"center_x\":0.363555, \"center_y\":0.285264, \"width\":0.062474, \"height\":0.133008}, \"confidence\":0.402736}\n    ] \n  }\n]\n```\n\n\n## Run on MOT Challenge dataset\n\n```bash\nnode-moving-things-tracker --mode motchallenge --input PATH_TO_MOT_DETECTIONS.txt\n\n# Output will be in the same folder as input under the name outputTrackerMOT.txt\n```\n\n## Benchmark\n\nHow to benchmark against MOT Challenge : https://github.com/opendatacam/node-moving-things-tracker/blob/master/documentation/BENCHMARK.md\n\n## Limitations\n\nNo params tweaking is possible via command-line for now, it is currently optimized for tracking cars in traffic videos.\n\n## How does it work\n\nBased on V-IOU tracker: https://github.com/bochinski/iou-tracker/ , paper: http://elvera.nue.tu-berlin.de/files/1547Bochinski2018.pdf\n\nIn order to define if an object is the same from one frame to another, we compare the overlapping areas between the two detections between the frames.\n\n![screen shot 2017-10-18 at 15 57 25](https://user-images.githubusercontent.com/533590/31719755-295303c0-b41d-11e7-8059-3ff7bcefd722.png)\n\nBy computing the intersection over union:\n\n![screen shot 2017-10-18 at 16 02 12](https://user-images.githubusercontent.com/533590/31719948-c6b69abe-b41d-11e7-8aac-5306e331f8b1.png)\n\nOn top of this we added some prediction mecanism for next frame based on velocity / acceleration vector to avoid ID reassignment when the object is missed only for a few frames.\n\n\n## License\n\n[MIT License](LICENSE)\n\n\n## Acknowledgments\n\nnode-moving-things-tracker is based on the ideas and work of the following people. References are listed chronologicaly how we encounter them.\n\n- [OpenCV Matching Faces Over Time](http://shiffman.net/general/2011/04/26/opencv-matching-faces-over-time/) by Daniel Shiffman\n- [Filter for interupting values](https://discourse.vvvv.org/t/filter-for-interupting-values/15601) related thread in the VVVV forum with source code and approaches. Pointer via [Joreg](https://github.com/joreg) \n- [IOU Tracker](https://github.com/bochinski/iou-tracker/) by Erik Bochinski, Volker Eiselein and Thomas Sikora, based on this [paper](elvera.nue.tu-berlin.de/files/1517Bochinski2017.pdf).\n- [SORT Tracker](https://github.com/abewley/sort) by Alex Bewley, based on this [paper](https://arxiv.org/abs/1602.00763).\n","funding_links":[],"categories":["JavaScript","Object Detection Applications"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopendatacam%2Fnode-moving-things-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopendatacam%2Fnode-moving-things-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopendatacam%2Fnode-moving-things-tracker/lists"}