7c43e4580d
- FastAPI backend with async SQLAlchemy - Camera RTSP management (add, start, stop) - Vehicle detection (YOLO + fast-alpr) - Type: car, motorcycle, truck, jeepney - Color detection (HSV) - License plate OCR - Motorcycle person count - Face detection + InsightFace ArcFace embedding - pgvector identity grouping (auto-cluster same face) - Vehicle + person movement trail APIs - Docker Compose with pgvector/pg16 - Models: Camera, VehicleIdentity, VehicleEvent, PersonIdentity, FaceEvent
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# 🎥 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
|