# 🎥 BantayCam

**Integrated License Plate + Face Recognition for Philippine CCTV Infrastructure**

Built with Python, FastAPI, YOLOv8, InsightFace, and PostgreSQL.

---

## Features

- 📡 **RTSP Camera Management** — Add any IP camera by RTSP URL, name it, start/stop anytime
- 🚗 **Vehicle Detection** — Detects car, motorcycle, jeepney, truck; identifies type + color
- 🔢 **License Plate Recognition** — Reads PH plates; logs every appearance with timestamp + camera
- 🏍️ **Motorcycle Person Count** — Counts riders on motorcycles
- 👤 **Face Detection** — Detects and embeds every face using InsightFace ArcFace
- 🔗 **Identity Grouping** — Auto-groups same face across events using pgvector similarity search
- 🗺️ **Movement Trail** — Query where a face or plate has been seen, on which camera, and when
- 🏷️ **Labeling** — Register identities with names, mark vehicles as resident/blacklisted

---

## Quick Start

### Requirements
- Docker + Docker Compose
- (Optional) NVIDIA GPU + CUDA for real-time processing

### Run with Docker

```bash
git clone http://192.168.1.159:3000/kibin/bantaycam.git
cd bantaycam
cp .env.example .env
docker-compose up -d
```

API available at: http://localhost:8000
Swagger docs: http://localhost:8000/docs

---

## API Endpoints

### Cameras
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/cameras/ | List all cameras |
| POST | /api/v1/cameras/ | Register new RTSP camera |
| POST | /api/v1/cameras/{id}/start | Start stream |
| POST | /api/v1/cameras/{id}/stop | Stop stream |
| GET | /api/v1/cameras/streams/status | Live stream status |

### Vehicles
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/vehicles/identities | List all known vehicles |
| GET | /api/v1/vehicles/identities/{id}/trail | Where was this vehicle seen? |
| GET | /api/v1/vehicles/events | Recent vehicle detection events |
| PATCH | /api/v1/vehicles/identities/{id} | Label/whitelist/blacklist a vehicle |

### Persons
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/persons/identities | List all detected identities |
| GET | /api/v1/persons/identities/{id}/trail | Where was this person seen? |
| PATCH | /api/v1/persons/identities/{id} | Register name/watchlist |
| GET | /api/v1/persons/events | Recent face detection events |

---

## Architecture

```
Camera (RTSP) → StreamWorker → Frame Queue → DetectionPipeline
                                                    │
                               ┌────────────────────┤
                               │                    │
                        VehicleDetector       FaceService
                        (YOLO + ALPR)         (InsightFace)
                               │                    │
                               └────────────────────┤
                                                    │
                                            PostgreSQL + pgvector
                                            (Events, Identities, Embeddings)
```

---

## Tech Stack

| Component | Technology |
|---|---|
| Backend API | FastAPI + Python 3.11 |
| Vehicle Detection | YOLOv8 (Ultralytics) |
| License Plate OCR | fast-alpr (YOLOv9 + ONNX) |
| Face Recognition | InsightFace ArcFace (buffalo_l) |
| Database | PostgreSQL 16 + pgvector |
| Containerization | Docker Compose |
| Stream Ingestion | OpenCV RTSP |

---

## Development Roadmap

- [ ] Phase 1: Core — RTSP + vehicle logging + face detection ← **YOU ARE HERE**
- [ ] Phase 2: Multi-stream + SMS/push alerts + gate relay
- [ ] Phase 3: Web dashboard + mobile app + LTO API integration