TraXie

TraXie is our little GUI for tracking stuff in videos.

It is based on Cutie, which is the actually clever bit. We took the Cutie idea/code and vibecoded this into something that fits how we wanted to use it. Very explicitly: we are not this good at coding, and we do not have the time to become this good at coding just for one tool, so we used AI to bash it into shape. Use it if you want. This is how it is done.

What The GUI Can Do

• Load a video and step through it frame by frame.
• Click on the object and background to make masks.
• Track one object or a bunch of objects.
• Rename objects, hide/show them, and show bounding boxes.
• Propagate masks forward, backward, or both ways through the video.
• Pick the exact propagation range on the timeline.
• Commit good frames to memory so the tracker has better examples.
• Reset the current frame, reset one object, or reset memory when things get cursed.
• Zoom, pan, scrub, and play through the clip while checking the masks.
• Import masks/layers for extra workflow chaos.
• Export tracking data to tracking_data.h5, including masks, object names, colors, boxes, centers, centroids, frame times, and metadata.

Why

We wanted a simple-ish desktop tool where we can click a thing, let the model follow it, fix the bad frames, and export useful tracking data without living in notebooks forever.

Cutie does the hard model work. TraXie is the friendly-ish button machine around it.

Install

This repo uses Pixi.

First, clone the repo and go into the folder:

git clone https://github.com/DevStart-Hub/TraXie.git
cd TraXie

Then install the environment:

pixi install

The app downloads/checks the needed model weights on first launch if they are missing.

Warning

We tested this on Windows. The pixi.toml has Mac and Linux platform bits in it too, but we have not tested those yet. They might work. They might do something weird...Let us know.

For decent performance, a GPU is recommended. CPU-only should still work because TraXie falls back to CPU when CUDA/MPS is not available. It will just be slower, possibly very slower. On Windows/Linux the Pixi setup may still install GPU/CUDA PyTorch packages, which is bigger and a bit silly on a CPU-only machine, but TraXie should use CPU if no GPU is found.

Run

pixi run traxie

Basic Workflow

1. Run TraXie.
2. Load a video.
3. Add/select an object.
4. Left-click the object.
5. Right-click the background if the mask spills out.
6. Hit Enter or the propagate button.
7. Fix bad frames when the tracker drifts.
8. Press C to commit clean frames to permanent memory.
9. Export H5 when you are happy enough.

Handy Controls

• Left click: foreground/object hint.
• Right click: background hint.
• Enter: propagate using the selected mode.
• F: propagate forward.
• B: propagate backward.
• C: commit current frame to permanent memory.
• Ctrl+Z: undo last click.
• Arrow keys: move frame by frame.
• Shift + arrows: jump 10 frames.
• Mouse wheel: zoom.
• Middle drag or hold Space: pan.
• Shift+Space: reset zoom.

More notes live in TraXie/docs/TIPS.md.

Notes

• GPU is nice for speed. CPU should work too, but bring snacks.
• Big videos and lots of objects can use a lot of memory.
• Bad committed masks can poison tracking, so only commit frames that look good.
• This is a practical tool, not a polished product. If it helps you, excellent. If it breaks, well, same.

Credits

• Built from/around Cutie.
• Uses the Cutie model weights and interactive segmentation pieces.
• Vibecoded into TraXie with AI because time is real and patience is finite.