TraceME Pipeline

TraceME is a video tracking pipeline that runs SAM2 on frame sequences, produces per-frame CSV summaries, and exports annotated videos.

What You Get

  • Annotated MP4 outputs per chunk (and a merged MP4).
  • Per-frame CSVs per chunk (and a merged CSV).
  • A CLI for running the pipeline over frame folders and prompt YAMLs.

Requirements

  • Python 3.10+
  • SAM2 (installed automatically via pip)
  • CUDA GPU recommended for speed (CPU is supported but slow)

Install (PyPI)

pip install traceme-pipeline

Checkpoints (Auto-Download)

TraceME automatically downloads the required SAM2 checkpoint on first run if it is missing. By default, checkpoints are stored in:

~/.cache/traceme/sam2/checkpoints

You can also pre-download all checkpoints:

traceme-download-checkpoints

To change the checkpoint location:

  • SAM2_CHECKPOINT_DIR=/path/to/checkpoints

To disable auto-download:

  • TRACEME_AUTO_DOWNLOAD=0

Dev Helper (SAM2 + Checkpoints)

If you prefer a local clone of SAM2 (for development), you can still use:

make install

This creates a venv, installs TraceME in editable mode, clones SAM2 into third_party/sam2, and downloads checkpoints.

Configure SAM2 (optional)

If SAM2 lives somewhere else, set:

  • SAM2_ROOT=/path/to/sam2 (should contain sam2/ and checkpoints/)
  • SAM2_MODEL=tiny|small|base_plus|large (default: large)

Usage

Run the pipeline:

traceme -i /path/to/frames -o /path/to/output -p /path/to/prompts.yaml

Generate a tasks file for batch runs:

traceme-gen-tasks /path/to/root -o tasks.tsv

Prompt YAML Format

Prompt files must contain a top-level prompts list. See src/traceme/prompts/parser.py for the exact schema and examples.

Outputs

Given frame_dir=/data/frames/clipA, outputs are:

  • /output/clipA.csv (merged CSV)
  • /output/clipA.mp4 (merged annotated video)
  • /output/clipA_tmp/ (intermediate chunk files; removed if --del_tmp is set)

Troubleshooting

  • If SAM2 configs or checkpoints are missing, TraceME will raise a clear error with the expected paths.
  • Set HYDRA_FULL_ERROR=1 for detailed SAM2 errors.

License

See LICENSE.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for StevetheGreek97 from gravatar.com StevetheGreek97

License

MIT

Requires

Python >=3.10

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

traceme_pipeline-0.2.0.tar.gz (29.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

traceme_pipeline-0.2.0-py3-none-any.whl (35.3 kB view details)

Uploaded Python 3

File details

Details for the file traceme_pipeline-0.2.0.tar.gz.

File metadata

  • Download URL: traceme_pipeline-0.2.0.tar.gz
  • Upload date:
  • Size: 29.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for traceme_pipeline-0.2.0.tar.gz
Algorithm Hash digest
SHA256 5d565a5d7a99acf5a168b9ae06c7647e68268d1236f6918ed99443efb2d3ce93
MD5 ad71d8784a13d51125fa2eefa31efc02
BLAKE2b-256 f810b024bb2ad5d125093fec11c08c0b07e607f6ad046a4c99b88848ac5d7c44

See more details on using hashes here.

Provenance

The following attestation bundles were made for traceme_pipeline-0.2.0.tar.gz:

Publisher: publish.yml on StevetheGreek97/TraceME

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file traceme_pipeline-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for traceme_pipeline-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f49636b5da4616bc6554be79e2421e5c8965cd2031b9c02d22fb56135f4daafe
MD5 92a1600cb2f62bfe7c2781689cf21293
BLAKE2b-256 b25a1e06951060810811782186fcd63c165262d9f80d20721bec9e2559696e4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for traceme_pipeline-0.2.0-py3-none-any.whl:

Publisher: publish.yml on StevetheGreek97/TraceME

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

This release

0.2.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page