🎯 Sentinel

Real-time object detection and tracking system

YOLO11 × BoT-SORT × FastAPI

Demo • Quick Start • Features • Usage • Docker

---

🎬 Demo

📸 Object Detection

Pedestrian Detection

Traffic Detection

🎥 Multi-Object Tracking

Real-time tracking of 20+ pedestrians with trajectory prediction

📥 Download Full Quality Video (34MB MP4)

---

🚀 Quick Start

Try it in 3 commands:

git clone https://github.com/bcpmarvel/sentinel.git
cd sentinel
uv run detect image demos/inputs/images/pedestrian.jpg

Models download automatically on first run. Output saved to demos/outputs/.

Prerequisites

• Python 3.12+
• uv package manager (install)

Installation

git clone https://github.com/bcpmarvel/sentinel.git
cd sentinel
uv sync

Try It Out

Detect objects in demo images:

# Pedestrian detection
uv run detect image demos/inputs/images/pedestrian.jpg

# Traffic detection
uv run detect image demos/inputs/images/traffic.jpg

Run on webcam:

uv run detect video --source 0

Track objects in video:

uv run detect video --source demos/inputs/videos/mot17-05.mp4 --track

Start API server:

uv run serve

Test the API:

curl -X POST http://localhost:8000/api/detect \
  -F "file=@demos/inputs/images/pedestrian.jpg"

---

✨ Features

Feature	Description	Status
🎯 YOLO11 Detection	State-of-the-art object detection at 30+ FPS	✅
🔄 BoT-SORT Tracking	Multi-object tracking with trajectory prediction	✅
📊 Zone Analytics	Count objects, measure dwell time, detect entries/exits	✅
🚀 REST API	Production-ready FastAPI server	✅
🔌 WebSocket Streaming	Real-time video streaming	✅
⚡ GPU Acceleration	MPS (Apple Silicon) and CUDA support	✅
🐳 Docker Ready	Containerized deployment with docker-compose	✅

---

🐳 Docker Deployment

# Development (hot reload)
docker-compose up api

# Production
docker-compose --profile production up api-prod

---

🛠️ Usage

CLI Commands

Image Detection:

uv run detect image <image_path> [--conf 0.5] [--model yolo11m.pt]

Video Detection:

# Basic detection
uv run detect video --source 0                           # Webcam
uv run detect video --source video.mp4                   # Video file
uv run detect video --source rtsp://camera.ip            # RTSP stream

# With tracking
uv run detect video --source video.mp4 --track

# Advanced options
uv run detect video --source 0 \
  --model yolo11s.pt \
  --conf 0.6 \
  --track \
  --analytics \
  --zones zones.json

Available Models:

• yolo11n.pt - Nano (fastest)
• yolo11s.pt - Small
• yolo11m.pt - Medium (default, balanced)
• yolo11l.pt - Large
• yolo11x.pt - Extra large (most accurate)

Advanced CLI Options

uv run detect video --help

Common options:

• --conf: Confidence threshold (0-1, default: 0.25)
• --device: Device (cpu/mps/cuda, auto-detected)
• --model: YOLO model path
• --track: Enable object tracking
• --analytics: Enable zone analytics
• --zones: Path to zones.json file
• --no-display: Run without GUI window
• --save-video: Save output video

API Endpoints

Start the server:

uv run serve

Health Check:

curl http://localhost:8000/api/health

Detect Objects:

curl -X POST http://localhost:8000/api/detect \
  -F "file=@demos/inputs/images/pedestrian.jpg" \
  -F "conf_threshold=0.5"

Response:

{
  "detections": [
    {
      "x1": 123.4, "y1": 456.7,
      "x2": 789.0, "y2": 321.5,
      "confidence": 0.89,
      "class_id": 0,
      "class_name": "person"
    }
  ],
  "image_width": 1280,
  "image_height": 720,
  "processing_time_ms": 45.2,
  "model_name": "yolo11m.pt",
  "device": "mps"
}

Interactive API Docs:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

More API Examples

With custom confidence threshold:

curl -X POST http://localhost:8000/api/detect \
  -F "file=@myimage.jpg" \
  -F "conf_threshold=0.7"

Using Python requests:

import requests

with open("image.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/detect",
        files={"file": f},
        data={"conf_threshold": 0.5}
    )

print(response.json())

Zone Analytics

Create zones.json to define monitoring zones:

[
  {
    "id": "zone_1",
    "name": "Entrance",
    "polygon": [[100, 100], [500, 100], [500, 400], [100, 400]],
    "color": [255, 0, 0]
  }
]

Metrics tracked:

• Object count in zone
• Average/max dwell time
• Entry/exit events

---

⚙️ Configuration

Docker/API Deployment

Use .env for environment variables:

cp .env.example .env

MODEL_NAME=yolo11m.pt
DEVICE=cpu
API_HOST=0.0.0.0
API_PORT=8000
LOG_FORMAT=json

CLI Configuration

Configuration is managed through:

• Command-line options for per-run settings
• Environment variables (via .env) for persistent settings

See Docker/API Deployment section above for .env configuration.

---

🏗️ Architecture

Note: Architecture diagram placeholder

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Input     │─────▶│   YOLO11     │─────▶│  BoT-SORT   │
│ (Video/API) │      │  Detection   │      │  Tracking   │
└─────────────┘      └──────────────┘      └─────────────┘
                                                   │
                                                   ▼
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Output    │◀─────│ Visualization│◀─────│  Analytics  │
│ (API/Stream)│      │  & Rendering │      │   (Zones)   │
└─────────────┘      └──────────────┘      └─────────────┘

Project Structure

src/sentinel/
├── api/              # FastAPI routes, schemas, dependencies
│   ├── app.py
│   ├── routes.py
│   ├── schemas.py
│   └── dependencies.py
├── analytics/        # Zone analytics, dwell time tracking
│   ├── service.py
│   ├── models.py
│   └── dwell.py
├── detection/        # YOLO11 detector, service
│   ├── service.py
│   └── models.py
├── visualization/    # Annotators for drawing
│   └── annotators.py
├── cli.py            # CLI entrypoint
├── server.py         # API server entrypoint
├── config.py         # Pydantic settings
└── pipeline.py       # Video processing pipeline

---

🧰 Tech Stack

Component	Technology
Detection	YOLO11 (Ultralytics)
Tracking	BoT-SORT
Deep Learning	PyTorch (MPS/CUDA)
API Framework	FastAPI
Computer Vision	OpenCV, Supervision
CLI	Typer
Logging	Structlog
Packaging	uv

---

🧪 Development

Setup

uv sync --dev

Code Quality

# Format
uv run ruff format .

# Lint
uv run ruff check .

# Fix
uv run ruff check --fix .

Testing

uv run pytest
uv run pytest -v --cov=sentinel

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Ultralytics for YOLO11
• BoT-SORT for multi-object tracking
• Roboflow for Supervision library

---

⬆ Back to Top