tracewave 0.1.0

TraceWave video tracking pipeline using SAM2

TraceWave Pipeline

TraceWave 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 tracewave

Checkpoints (Auto-Download)

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

~/.cache/tracewave/sam2/checkpoints

You can also pre-download all checkpoints:

tracewave-download-checkpoints

To change the checkpoint location:

• SAM2_CHECKPOINT_DIR=/path/to/checkpoints

To disable auto-download:

• TRACEWAVE_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 TraceWave 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:

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

Generate a tasks file for batch runs:

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

Prompt YAML Format

Prompt files must contain a top-level prompts list. See src/tracewave/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)

Build + Verify Before Publishing

Use these make targets to validate the package before uploading to PyPI:

python -m pip install --upgrade build twine
make build
make test-install
make check-dist

What they do:

• make build: builds sdist + wheel into dist/
• make test-install: installs the wheel into a clean venv and verifies tracewave imports and CLI help
• make check-dist: runs twine check dist/*

Development

Create a dev environment (with SAM2):

make install

Run the pipeline (after install):

make run ARGS="-i /path/to/frames -o /path/to/output -p /path/to/prompts.yaml"

Troubleshooting

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

License

See LICENSE.