README.md

---
title: Sam3 Demo
emoji: 📉
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: apache-2.0
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## SAM3 Vehicle Trajectory Space

This Space turns `facebook/sam3` into a ready-to-use pipeline for extracting
small- and large-vehicle trajectories from aerial surveillance videos.

### Quick start

1. Authenticate with Hugging Face to access the gated SAM3 checkpoint:
   ```bash
   hf auth login
   ```
2. Upload an aerial MP4/MOV clip. The app automatically sends the prompts
   `small-vehicle` and `large-vehicle` to SAM3, overlays the resulting masks,
   and links detections over time to form trajectories.
3. Download the rendered video and inspect the per-track summary table.

The UI exposes stride, resize, and frame-limit controls so you can trade off
latency versus coverage depending on the clip length. All heavy lifting (frame
decoding, segmentation, mask rendering, trajectory stitching) happens on the
Space so you only need to provide the footage.