How montero52/vision-activity-analytics works
From the file tree + README, this is a single-node, edge-deployed computer-vision analytics system with a Flask web dashboard that drives two execution modes:
• Live (streaming / preview) pipeline: camera/video stream → YOLOv8(OpenVINO) inference → tracking + seat-based spatial logic → on-screen/live dashboard updates (+ optional event logging).
• Batch (offline / export) pipeline: video file upload → faster processing/export → FFmpeg H.264 transcoding → saved outputs + Excel reports + SQLite events.
It’s optimized for Intel CPUs with OpenVINO and is intended to run as one “appliance-like” process (plus external tools like FFmpeg).
Read the repo structure as architecture boundaries
• app.py: system entrypoint; Flask routes + orchestration between UI and pipelines.
• src/:
• src/camera.py: capture/stream handling, frame loop, likely live pipeline integration.
• src/database.py: SQLite event logging interface.
• config.py: global configuration (paths, toggles, thresholds, model paths).
• templates/ + static/: web UI (HTML + JS + CSS).
• models/: model artifacts/config (bytetrack.yaml, exported OpenVINO model directory).
• scripts/:
• export_model.py: pulls YOLOv8n and exports to OpenVINO IR (build step).
• draw_zones.py: zone authoring tool that produces polygon definitions.
• data/:
• data/office_*_zones.json: the seat/zone geometry configs (core to “seat-locking” logic).
• data/uploads/: user-uploaded videos for batch mode.
• data/outputs/: processed videos/images.
• data/reports/: Excel outputs for HR reporting.
• data/samples/employee_template.xlsx: reporting template.
• run_system.bat: Windows automation (venv setup, dependency install, warmup, launch).
Client/UI layer
• Browser
• Loads templates/index.html
• Runs static/js/script.js for:
• starting/stopping live preview
• triggering batch upload/export
• polling results / rendering stats
Web/API serving layer
• Waitress WSGI Server (production runtime per README)
• Hosts the Flask app
• Flask Application (app.py)
• Route handlers:
• live preview endpoints
• batch upload endpoints
• results/report download endpoints
• Orchestration: calls into camera/inference/db modules
Core CV pipeline layer (backend internal “engine”)
• Frame Acquisition (src/camera.py)
• RTSP/USB camera feed or video file reader (OpenCV)
• Pre/Post Processing
• resize/normalize, bbox parsing, filtering (anti-merging rules from README)
• Inference Engine
• YOLOv8 model executed via OpenVINO Runtime
• “model warming / JIT” (not a file, but a real lifecycle step worth annotating)
• Tracking
• ByteTrack configuration (models/bytetrack.yaml)
• Seat-Based Spatial Logic
• loads polygons from data/office_*_zones.json
• anchor-point heuristic (25% bbox height) + pointPolygonTest
• maps tracked person → workstation seat (identity anchoring)
Storage layer
As separate stores (not one generic “DB”):
• SQLite DB (via src/database.py) for event logging
• Filesystem stores
• data/uploads/ (inputs)
• data/outputs/ (rendered video/results)
• data/reports/ (Excel exports)
Batch export/transcoding/reporting layer
• Batch Processor (likely orchestrated by Flask route)
• consumes uploaded video
• produces processed video + event summaries
• FFmpeg (external process dependency)
• H.264 transcoding for browser playback
• Excel Report Generator
• uses Pandas + template data/samples/employee_template.xlsx
Configuration flows
• Zone JSON → Seat Logic: polygons loaded at startup or per-job
• config.py → Flask/CV Engine/Batch: thresholds, model paths, directories
Lifecycle / provisioning flows (often omitted, but this project benefits from it)
• run_system.bat → venv/pip → launch waitress/flask
• scripts/export_model.py → models/: produces runtime model artifacts
• Edge deployment / single-node: all components run on one machine (Intel CPU).
• Dual-mode architecture: *Live Preview* vs *Turbo Batch Export* (make them two distinct pipelines sharing the same CV core).
• External tool boundary: FFmpeg is not a Python module—show it as an external executable invoked by the backend.
• Persistence split: SQLite for events + filesystem for artifacts + Excel for human deliverables.
• User (HR/Manager)
• Browser UI
• External Dependencies: FFmpeg, (optional) Camera/RTSP source, Ultralytics model source (for export step)
• user uses browser
• browser interacts with VAA
• VAA reads camera stream / video uploads
• VAA calls FFmpeg
• (optional) export script pulls model weights from internet
Inside VAA:
• Web Server (Waitress + Flask)
• CV Engine (OpenVINO + OpenCV + tracker)
• Batch Export/Transcode
• SQLite DB
• File Stores (uploads/outputs/reports)
• Config/Zone definitions
Inside CV Engine:
• Frame Acquisition (src/camera.py)
• Pre/Post Processing
• OpenVINO Inference (YOLOv8)
• Tracking (ByteTrack config)
• Seat Logic (polygon test + anchor heuristic + anti-merging filters)
• Event Logger (src/database.py)