{"id":42761213,"url":"https://github.com/starwit/movement-predictor","last_synced_at":"2026-01-29T20:34:09.218Z","repository":{"id":314476476,"uuid":"911266720","full_name":"starwit/movement-predictor","owner":"starwit","description":"The Probabilistic Motion Forecaster (PMF) models plausible near-future motion given surrounding traffic, and flags anomalies via trajectory-level scoring.","archived":false,"fork":false,"pushed_at":"2025-09-22T18:34:33.000Z","size":145410,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-22T20:36:47.378Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/starwit.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-02T16:08:58.000Z","updated_at":"2025-09-12T16:29:17.000Z","dependencies_parsed_at":"2025-09-12T18:50:03.772Z","dependency_job_id":"2efe7122-6d14-4af2-b2a6-7d580899e0e4","html_url":"https://github.com/starwit/movement-predictor","commit_stats":null,"previous_names":["starwit/movement-predictor"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/starwit/movement-predictor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starwit%2Fmovement-predictor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starwit%2Fmovement-predictor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starwit%2Fmovement-predictor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starwit%2Fmovement-predictor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starwit","download_url":"https://codeload.github.com/starwit/movement-predictor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starwit%2Fmovement-predictor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28884291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T19:55:09.949Z","status":"ssl_error","status_checked_at":"2026-01-29T19:55:08.490Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-29T20:34:07.460Z","updated_at":"2026-01-29T20:34:09.212Z","avatar_url":"https://github.com/starwit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Anomaly Detection Through Probabilistic Movement Forecasting\n\n## Description\n\nThis project detects anomalies in vehicle behavior not only by path deviations but also by velocity and traffic context. It leverages all vehicles in a scene to spot right-of-way violations or overly cautious waiting. Detected anomalies can be clustered at runtime with human feedback into categories (e.g. “not interesting”, “critical”, “dangerous”). A visualization of the approach is in `docs/ApproachVisualization.pdf`.\n\n## Prerequisites\n\n- Python 3.10  \n- Virtual env (e.g. sudo apt install python3.10-venv) \n- Poetry  \n\n## Setup\n\n```bash\ngit clone \u003crepo-url\u003e\ncd \u003crepo\u003e\npython3 -m venv .venv\nsource .venv/bin/activate\npoetry install\n```\n\n## Usage\n\nExample parameter values are provided in `movementpredictor/.env.template`. To run the full pipeline—or any subset of its steps—follow these instructions:\n\n1. **Configure**  \n   Create a `.env` in the project root (or copy `movementpredictor/.env.template`) and fill in your paths and parameters. In particular, set:\n   - `PATH_SAE_DATA_TRAIN`, `PATHS_SAE_DATA_TEST` (SAE-dump files for training \u0026 validation)  \n   - `TIME_DIFF_PREDICTION` (seconds ahead to predict)  \n   - `CAMERA`, `NAME_DATA` (used to name output folders)  \n   - `PIXEL_PER_AXIS` (frame resolution)  \n   - `MODEL_ARCHITECTURE`, `OUTPUT_DISTR` (e.g. “asymmetric”)  \n   - `PERCENTAGE_OF_ANOMALIES` (e.g. 99.95)  \n   - `COMPUTE_STEPS` (comma-separated subset of `prepare,train,threshold`)  \n   - etc.\n\n2. **Run the pipeline**  \n   ```bash\n   python3 movementpredictor/main.py\n   ```\n\nBy default, all three stages run in order (`prepare`, `train`, `threshold`).\nIf the .env Parameter `VISUALIZE` is set, plots and videos of found anomalies during the last stage are stored in folder `plots/\u003cCAMERA\u003e/\u003cNAME_DATA\u003e/…`. Frames are needed for this, so only set `VISUALIZE=True` if your sae-dumps contain frames. \n\n### Select individual stages\n\nAdjust the `COMPUTE_STEPS` env var to run only the steps you need:\n\n| Step         | What it does                                                                                                                |\n|--------------|-----------------------------------------------------------------------------------------------------------------------------|\n| **prepare**   | Builds the train \u0026 test datasets from the SAE-dump files.                                                                  |\n| **train**     | Trains the movement-prediction CNN and saves model weights and parameters.                                                                |\n| **threshold** | Runs inference on the test set to compute the anomaly threshold so that `PERCENTAGE_OF_ANOMALIES` % are normal; saved alongside the model.|\n\n\n_Example:_ To only prepare data and train the model, set:\n\n```dotenv\nCOMPUTE_STEPS=\"prepare,train\"\n```\n\n## Outputs\n\nAfter running, you’ll find:\n\n- **Datasets** under  \n  `movementpredictor/data/datasets/\u003cCAMERA\u003e/\u003cNAME_DATA\u003e/…`\n\n- **Model \u0026 parameters** under  \n  `models/\u003cCAMERA\u003e/\u003cNAME_DATA\u003e/…` (weights + `parameters.json`)\n\n- **Anomaly threshold** in the same folder as the model, added to the `parameters.json`\n  \n- **plots \u0026 Videos** under `plots/\u003cCAMERA\u003e/\u003cNAME_DATA\u003e/…` if the .env Parameter `VISUALIZE` is set\n\nAll steps share the same configuration and folder conventions, making it easy to automate or integrate into larger workflows.\n\n  \n## Library Usage\n\nAfter performing the 3 setup steps the movement predictor anomaly detection is ready to be used. All necessary functions and classes can be imported via 'from movementpredictor import ...'. To perform inferencing and extraction of anomalies the recommended workflow is the following: \n- extract sae data with `TrackingDataManager`\n- smooth and filter the tracks with `DataFilterer.apply_filtering`\n- generate the dataset with `makeTorchDataLoader` \n- load the model: \n  - `import torch`\n  - `from movementpredictor.cnn import model_architectures`\n  - `model = model_architectures.get_model(architecture=\"MobileNet_v3\", output_prob=\"asymmetric\", path_model=\"path-to-your-model-weights.pth\")`\n- inferencing with `inference_with_stats`\n- extract anomalies with `get_meaningful_unlikely_samples`\n\n## Model Evaluation and Dataset Generation\n\nThis repo includes supplementary scripts for model evaluation (`movementpredictor/evaluation/`)\nand for generating the anomaly dataset released on [Hugging Face](https://huggingface.co/datasets/starwit/overhead-traffic-anomalies) (`movementpredictor/anomalydataset/`).\n\nThese scripts were used for the master’s thesis *Anomaly Detection in Traffic Applications:\nA Probabilistic Forecasting Approach Based on Object Tracking* (Hanna Lichtenberg).\nThe exact model weights and configs used in the thesis are available here:[OneDrive](https://1drv.ms/f/c/29bd20621baa5af0/En9bfIFXlP5FqIJN5uQKIdkB31psQElUbdLvwUHE5YdH1A?e=XteuXG)\n\n## Github Workflows and Versioning\n\nThe following Github Actions are available:\n\n* [PR build](.github/workflows/pr-build.yml): Builds docker image for each pull request to main branch. Inside the docker image, `poetry install` and `poetry run python test.py` are executed, to compile and test entire python code.\n* [Create release](.github/workflows/create-release.yml): Manually executed action. Creates a github release with tag. Poetry is updating to next version by using \"patch, minor and major\" keywords. If you want to change to non-incremental version, set version in directly in pyproject.toml and execute create release afterwards.\n\n## Dependabot Version Update\n\nWith [dependabot.yml](.github/dependabot.yml) a scheduled version update via Dependabot is configured. Dependabot creates a pull request if newer versions are available and the compilation is checked via PR build.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarwit%2Fmovement-predictor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarwit%2Fmovement-predictor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarwit%2Fmovement-predictor/lists"}