Create README.md

README.md

@@ -1,11 +1,234 @@
 ---
-title: Trajectory Tracker
-emoji: 👁
-colorFrom: purple
+title: 3D Trajectory Tracker
+emoji: 🎯
+colorFrom: blue
 colorTo: purple
 sdk: docker
+app_file: app.py
 pinned: false
-license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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