README.md

---
title: MotionScope Pro
emoji: 🎥
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
app_file: app.py
pinned: false
---

# ⚠️ IMPORTANT SETUP STEP
**If you see "Welcome to your static Space"**:
1. Go to the **Settings** tab above.
2. Scroll to **Select Space SDK**.
3. Change it from **Static** to **Docker**.
4. Click **Update Space**.
The app will then build and start!

# 🎥 MotionScope Pro — Movement Detector

A professional Streamlit application combining **MediaPipe hand tracking** and **background subtraction motion detection**.

## Features

| Feature | Description |
|---|---|
| 🖐️ Hand Tracking | Real-time MediaPipe hand landmark detection |
| 🚗 Motion Detection | Background subtraction (MOG2) with contour filtering |
| ⚡ Combined Mode | Both hand tracking + motion detection simultaneously |
| 📹 Video Upload | Upload MP4/AVI/MOV/MKV → process → download result |
| 📷 Webcam Snapshot | Capture a photo and process it instantly |

## How to Download & Run

### Option 1: Run on Hugging Face Spaces
Click the **App** tab above to use the application directly in your browser!

### Option 2: Run Locally

1. **Clone the repository:**
   ```bash
   git clone https://huggingface.co/spaces/Jack1808/MotionScope-Pro
   cd MotionScope-Pro
   ```

2. **Create a virtual environment (recommended):**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Run the application:**
   - **Web Interface:**
     ```bash
     streamlit run app.py
     ```
   - **Real-time Webcam Window:**
     ```bash
     python live_run.py
     ```

1. **Sidebar** — choose detection mode and tune parameters (threshold, min area, confidence).
2. **Video Upload tab** — upload a video, click **Process Video**, watch the live preview, then download the result.
3. **Webcam Snapshot tab** — take a photo from your webcam and see the detected landmarks / motion overlay.

## Project Structure

```
motion_detector/
├── app.py              # Streamlit UI
├── detector.py         # Core MovementDetector class
├── requirements.txt    # Python dependencies
└── README.md           # This file
```

## Requirements

- Python 3.10+
- A webcam (for the snapshot tab)