KD-VISION • Real-Time Event Visitor & Live Occupancy Counter

A high-performance Computer Vision intelligence system engineered for event venues to track visitors entering and exiting through doorways/gates, calculate real-time venue occupancy, and provide an interactive operator dashboard.

$$\text{Live Venue Occupancy} = \max(0, \text{Total IN} - \text{Total OUT})$$

---

🌟 Key Features

1. AI Object Detection & Multi-Object Tracking:
   • Powered by YOLO11 (with fallback support for YOLOv8) optimized with Apple Silicon MPS, NVIDIA CUDA, or CPU acceleration.
   • ByteTrack multi-object tracking ensures individuals are uniquely tracked across frames without double-counting even in dense crowds.
2. Interactive Day-of-Event Visual Calibrator:
   • Position and angle your camera anywhere at the entrance threshold.
   • Click "Calibrate Line" on the dashboard and drag the interactive handles directly over the camera stream to align the tripwire with the door frame.
   • Real-time directional crossing arrows (Green IN (+1) and Amber OUT (-1)) show crossing orientation.
   • 1-Click "Flip Direction" button to immediately invert IN $\leftrightarrow$ OUT vectors if camera angle is reversed.
   • Built-in presets for common doorway configurations (Door Right-In, Door Left-In, Horizontal, Diagonal).
3. Dual-Server Mobile Camera Transmitter (Android & iPhone):
   • Zero-Install Wireless Transmitter (https://<ip>:8443/phone.html): Scan the QR code with any Android or iPhone to beam low-latency HD camera frames directly into the AI engine.
   • Automatic SSL Provisioning: Built-in dual HTTP (:8000) and HTTPS (:8443) server architecture ensures mobile browsers (Chrome / Safari) grant secure getUserMedia camera permissions over local Wi-Fi / hotspot.
   • Camera Selection & Dim Mode: Switch between Rear Wide, Ultra-Wide, and Front cameras with a blackout screen curtain to prevent phone overheating during all-day events.
   • USB Cable Support: Direct plug-and-play for Android 14+ USB Webcam mode, DroidCam, Camo, and standard USB UVC capture cards.
4. Live Venue Occupancy & Operator Dashboard:
   • Hero Occupancy KPI: Displays live in-venue visitor count, venue capacity threshold, staff/vendor offset note, glowing progress bar, and dynamic status badges (COMFORTABLE / NEAR CAPACITY / MAX CAPACITY REACHED).
   • Total In & Total Out Metrics: Real-time entry and exit totals with multi-tier manual nudge controls (+1, +10, +100, +1000, -1, -10, -100, -1000) for rapid crowd and staff/VIP bypass adjustments.
   • Venue Occupancy Timeline Graph: Interactive canvas chart with dynamic time-range filters (Minutes Live, Hourly Trend, Today Day), peak occupancy tracking, and capacity threshold indicator.
   • Real-Time Audit Log & CSV Export: Live streaming event log showing crossing direction and timestamps, with 1-click CSV download for post-event analytics.
   • Stream Source Exclusivity & Safety: Dedicated Start and Stop controls with automatic device detection and exclusive feed locking.
5. Secure Operator Access Control:
   • Protected Dashboard: Blocks public unauthorized access to the dashboard, camera stream, telemetry WebSockets, and control APIs.
   • Environment Credentials (.env): Zero hardcoded secrets. Operator username and password are configurable via .env.
   • Seamless Phone QR Authentication: The mobile transmitter QR code generated on the dashboard embeds secure session tokens so event staff connect immediately without manual password entry on mobile devices.

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• macOS (Apple Silicon MPS), Linux (CUDA/CPU), or Windows

1. Installation

Clone the repository and install dependencies:

git clone https://github.com/Krackeddevs-Org/kd-vision.git
cd kd-vision
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure Environment Credentials

Copy the example environment file and set your desired operator credentials:

cp .env.example .env

Edit .env:

ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password

3. Launch Server

./run.sh

The startup script automatically generates local SSL certificates and launches both the HTTP operator dashboard and the HTTPS mobile transmitter:

• Operator Dashboard: http://localhost:8000 (or http://<your-ip>:8000)
• Phone Camera Transmitter: https://<your-ip>:8443/phone.html

---

📱 Mobile Phone Camera Setup

1. Connect your laptop and phone to the same Wi-Fi network (or phone Personal Hotspot).
2. On the dashboard, click "📱 Connect Phone / Android" in the top header.
3. Scan the QR code with your phone camera or open https://<your-ip>:8443/phone.html.
4. Tap "Advanced" $\rightarrow$ "Proceed to site" to accept the local self-signed certificate.
5. Tap "Start Camera Transmitter" — the dashboard feed will instantly switch to your phone's live video stream!

---

🎯 Day-of-Event Calibration Guide

Camera Mounting Best Practices:

• Mount Height: Best mounted 2.5m – 3.5m high, angled 30°– 45° downwards facing the entrance doorway.
• Angle Alignment: Position the camera so visitors walk across the doorway plane from one side to the other.

3-Step Calibration:

1. Open the dashboard at http://localhost:8000 and log in with your configured credentials.
2. Select your camera source (e.g. MacBook Camera, Android Camera, Phone Transmitter, or Sample Entrance Video) and click Start.
3. Click "Calibrate Line" in the header.
4. Drag the circular handles ($P_1$ and $P_2$) to align the virtual line with the physical door threshold.
5. Verify the arrows:
   • Green Arrow (IN +1) points into the venue.
   • Amber Arrow (OUT -1) points out of the venue.
   • Click "Flip IN / OUT Direction" if reversed.
6. Click "Done Calibrating" — settings persist automatically to backend/config.json.

---

📁 Project Structure

kd-vision/
├── backend/
│   ├── app.py                 # FastAPI dual HTTP/HTTPS server, WebSockets, MJPEG streaming
│   ├── vision_engine.py       # YOLO11 + ByteTrack + crossing vector engine
│   ├── config.py              # Pydantic configuration schemas and JSON persistence
│   ├── config.json            # Persistent calibration and venue settings
│   └── certs/                 # Auto-generated local SSL certificates
├── frontend/
│   ├── index.html             # Glassmorphic dark-mode live operator dashboard
│   ├── login.html             # Cyber-styled operator authentication page
│   ├── phone.html             # Mobile camera web transmitter with dark dim mode
│   ├── kd-logo.png            # Application brand assets
│   ├── css/
│   │   └── style.css          # Design tokens, glowing status pills & responsive layout
│   └── js/
│       ├── app.js             # WebSocket telemetry, device scanner, audio cues & controls
│       ├── calibrator.js      # Interactive HTML5 canvas tripwire calibrator
│       └── occupancy-chart.js # Live occupancy timeline chart and peak tracking
├── sample_videos/
│   ├── generate_test_video.py # Synthetic event entrance video generator
│   └── test_entrance.mp4      # Sample entrance test video
├── uploads/                   # Uploaded video storage directory
├── .env.example               # Template environment configuration file
├── requirements.txt           # Python dependencies
├── run.sh                     # One-click startup script
└── README.md                  # Documentation

---

🛠️ REST & WebSocket API

Endpoint	Protocol	Description	Auth Required
GET /	HTTP	Main operator dashboard UI (redirects to /login.html if unauthenticated)	Yes
GET /login.html	HTTP	Operator login page	No
POST /api/auth/login	HTTP	Authenticate operator session and set cookie	No
POST /api/auth/logout	HTTP	Terminate active session	Yes
GET /api/auth/check	HTTP	Verify session authentication state	No
GET /phone.html	HTTPS	Mobile phone camera transmitter UI	Yes (or Token)
GET /video_feed	HTTP	MJPEG video stream with bounding boxes and tripwire	Yes
WS /ws	WebSocket	Real-time JSON telemetry (STATS, EVENT, STREAM_SOURCE_SWITCHED)	Yes
WS /ws/video	WebSocket	High-efficiency binary JPEG stream	Yes
WS /ws/camera_stream	WebSocket	Local browser webcam ingestion	Yes
WS /ws/phone_camera	WebSocket	Mobile phone camera frame ingestion	Yes
POST /api/control/source	HTTP	Switch active video source	Yes
POST /api/control/stop	HTTP	Halt all streams and return to standby	Yes
POST /api/control/pause	HTTP	Pause/resume AI detection	Yes
POST /api/control/reset	HTTP	Reset in/out counts and visitor tracker	Yes
POST /api/control/adjust	HTTP	Manual visitor count delta adjustments (+1 / -1)	Yes
POST /api/config/line	HTTP	Update tripwire coordinates and direction	Yes
GET /api/export/csv	HTTP	Download attendance audit log CSV	Yes

---

👥 Authors & Maintainers

• Kracked Devs • hello@krackeddevs.com
• Repository: https://github.com/Krackeddevs-Org/kd-vision