🎥 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

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