README.md

---
title: 3D Trajectory Tracker
emoji: 🎯
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
---

# 3D Trajectory Tracker

A web application that tracks objects in videos and visualizes their movement in 3D space using computer vision and Three.js.

## Features

- 🎥 Video upload and processing
- 🎯 Automatic object detection and tracking
- 📊 Real-time trajectory visualization in 3D
- 🎬 Playback controls for trajectory animation
- 📈 Statistics and analytics dashboard

## Technology Stack

- **Backend**: FastAPI, OpenCV, NumPy
- **Frontend**: Vanilla JavaScript, Three.js
- **Computer Vision**: Background subtraction for object detection

## Project Structure

```
trajectory-tracker/
├── backend/
│   ├── app.py              # FastAPI main application
│   ├── requirements.txt    # Python dependencies
│   ├── tracker.py         # Object tracking logic
│   └── utils.py           # Helper functions
├── frontend/
│   ├── index.html         # Main HTML file
│   ├── app.js             # Frontend logic
│   ├── styles.css         # Styling
│   └── visualizer.js      # 3D visualization with Three.js
├── uploads/                # Temporary video uploads (auto-created)
├── outputs/                # Processed trajectory data (auto-created)
└── README.md              # Documentation
```

## Installation & Setup

### Local Development (VS Code)

1. **Clone or create the project structure**
   ```bash
   mkdir trajectory-tracker
   cd trajectory-tracker
   ```

2. **Set up backend**
   ```bash
   # Create directories
   mkdir backend frontend uploads outputs
   
   # Install Python dependencies
   pip install -r backend/requirements.txt
   ```

3. **Run the application**
   ```bash
   # From the project root directory
   python backend/app.py
   ```

4. **Access the application**
   - Open browser to: `http://localhost:7860`

### Hugging Face Spaces Deployment

1. **Create a new Space**
   - Go to https://huggingface.co/spaces
   - Click "Create new Space"
   - Choose "Docker" as SDK

2. **Create Dockerfile in project root**
   ```dockerfile
   FROM python:3.9

   WORKDIR /app

   # Install system dependencies
   RUN apt-get update && apt-get install -y \
       libgl1-mesa-glx \
       libglib2.0-0 \
       && rm -rf /var/lib/apt/lists/*

   # Copy requirements and install
   COPY backend/requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt

   # Copy application files
   COPY backend/ ./backend/
   COPY frontend/ ./frontend/

   # Create directories
   RUN mkdir -p uploads outputs

   # Expose port
   EXPOSE 7860

   # Run the application
   CMD ["python", "backend/app.py"]
   ```

3. **Push to Hugging Face**
   ```bash
   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   git push -u origin main
   ```

## Usage

1. **Upload Video**
   - Click the upload box or drag and drop a video file
   - Supported formats: MP4, AVI, MOV, MKV

2. **Process Video**
   - Click "Process Video" button
   - Wait for processing to complete (may take a few moments)

3. **View Results**
   - See tracking statistics (objects tracked, frames, FPS, duration)
   - View 3D visualization of trajectories
   - Use playback controls:
     - ▶ Play/Pause: Animate the trajectories
     - ↻ Reset: Return to start
     - Show Trails: Toggle trajectory lines

4. **Interact with 3D View**
   - Click and drag to rotate camera
   - Scroll to zoom in/out

## Configuration

### Detection Methods

In `tracker.py`, you can choose detection methods:

```python
# Background subtraction (default)
tracker = VideoTracker('video.mp4', detection_method='background')

# Color-based detection
tracker = VideoTracker('video.mp4', detection_method='color')
```

### Tracking Parameters

Adjust in `tracker.py`:
- `area > 500`: Minimum object size (pixels)
- `max_distance=50`: Maximum movement between frames (pixels)
- `len(points) > 5`: Minimum trajectory length (frames)

## API Endpoints

- `GET /` - Main application interface
- `POST /api/upload` - Upload and process video
- `GET /api/trajectories/{filename}` - Get trajectory data
- `GET /api/list` - List all processed files
- `DELETE /api/clear` - Clear all data

## Troubleshooting

### Video Processing Fails
- Ensure video format is supported
- Check video file is not corrupted
- Verify OpenCV can read the codec

### No Objects Detected
- Adjust detection parameters in `tracker.py`
- Try different detection methods
- Ensure objects have sufficient movement/contrast

### 3D Visualization Issues
- Check browser console for JavaScript errors
- Ensure Three.js CDN is accessible
- Try refreshing the page

## Development

### Add New Features

1. **Custom Detection Methods**: Add to `tracker.py`
2. **UI Enhancements**: Modify `frontend/` files
3. **Export Options**: Add endpoints in `app.py`

### Testing

```bash
# Test with sample video
python backend/app.py

# Access http://localhost:7860 and upload test video
```

## Performance Tips

- Use smaller videos for faster processing
- Reduce video resolution before upload
- Adjust detection parameters for accuracy vs. speed

## License

MIT License

## Contributing

Pull requests welcome! Please ensure:
- Code follows existing style
- Add tests for new features
- Update documentation

## Support

For issues and questions:
- Open an issue on the repository
- Check existing issues for solutions

## Credits

- FastAPI for backend framework
- Three.js for 3D visualization
- OpenCV for computer vision