157 lines
8.0 KiB
Markdown
157 lines
8.0 KiB
Markdown
# SPEC — bytetrack-counter
|
||
|
||
## §G — Goal
|
||
|
||
RTSP camera → YOLO RKNN (NPU) → ByteTrack → line-crossing counter → SQLite + Flask dashboard.
|
||
Count `ayam` (chicken) crossing counting line. Close batch on `talenan` (cutting-board) crossing.
|
||
Daily cutoff @ HH:MM resets batch numbering. RK3588 hardware.
|
||
**Reference implementation for C++ port in separate repo.**
|
||
|
||
## §C — Constraints
|
||
|
||
- Python 3.10, `rknn-toolkit-lite2` (NPU), `opencv-python` (RTSP/FFmpeg)
|
||
- `numpy<2` (rknn-toolkit-lite2 incompatible with numpy≥2)
|
||
- `PYTHONNOUSERSITE=1` ! set or venv breaks
|
||
- SQLite for persistence, JSON file for active-batch state
|
||
- Flask on port 5000 (dashboard) + 5002 (recounting), systemd supervision
|
||
- `counter_live.py` ⊥ run on RK3588 — Jetson TensorRT artifact, ! port target
|
||
- `counter_live_rknn_bytetrack.py` — reference for C++ port, this is what systemd runs
|
||
- Single deployment: `counter_live_rknn_bytetrack.py` + `counter_dashboard.py` + `recounting_dashboard.py`
|
||
- `go2rtc` ! running for recounting MP4 streaming (port 1984)
|
||
|
||
## §I — Interfaces
|
||
|
||
### Systemd
|
||
```
|
||
unit: bytetrack-counter.service → `venv/bin/python counter_live_rknn_bytetrack.py`
|
||
unit: bytetrack-counter-dashboard.service → `venv/bin/python counter_dashboard.py`
|
||
unit: bytetrack-recounting-dashboard.service → `venv/bin/python recounting_dashboard.py`
|
||
env: PYTHONNOUSERSITE=1 ! set in all units
|
||
env: EnvironmentFile=/opt/bytetrack-counter/.env
|
||
user: root (not jetson)
|
||
path: /opt/bytetrack-counter (fixed in service file)
|
||
```
|
||
|
||
### `.env` config (40+ vars, gitignored)
|
||
```
|
||
env: SOURCE ! set → RTSP URL | file path
|
||
env: MODEL_PATH ! set → .rknn file
|
||
env: IMGSZ ! set → model input size (e.g. 320)
|
||
env: CORE_MASK → NPU core mask (1=core0, 2=core1, 3=dual, 7=all)
|
||
env: NUM_CLASSES ! match model output count
|
||
env: CONF → detection confidence threshold (default 0.3)
|
||
env: DAILY_CUTOFF_TIME → HH:MM, default "20:00"
|
||
env: CROSS_DIRECTION → rtl | ltr | both (default rtl)
|
||
env: LINE_X | LINE_X_FRAC → counting line position
|
||
env: CLASS_AYAM → class name for counted object (index 0)
|
||
env: CLASS_TALENAN → class name for batch-close trigger (index 1)
|
||
env: RESET_COUNTERS_AT_CUTOFF → defined in example, ! consumed by code ? zombie
|
||
env: MOTION_DETECTION_ENABLED | MOTION_THRESHOLD → skip inference on still frames ?
|
||
env: TRACK_HIGH_THRESH_{0,1} | TRACK_LOW_THRESH_{0,1} | TRACK_MATCH_THRESH_{0,1} → ByteTrack params per class
|
||
env: BATCH_TIMEOUT_SECONDS → auto-close after inactivity (default 300)
|
||
env: IGNORE_BATCH_LABEL_TIMEOUT_SECONDS → suppress talenan close after batch start (default 30)
|
||
env: MIN_OBJECT_PER_BATCH → min count to persist batch (default 60)
|
||
env: MIN_DURATION_PER_BATCH → min seconds to persist batch (default 60)
|
||
env: LIVE_STREAM_ENABLED → write annotated JPEG snapshot each N frames
|
||
env: EXPORT_CSV → write per-crossing CSV (default true)
|
||
|
||
### Recounting dashboard config
|
||
```
|
||
env: RECOUNTING_DASHBOARD_PORT → port for recounting UI (default 5002)
|
||
env: LIVE_API_URL → base URL of live counter API (default http://localhost:5000)
|
||
env: RECOUNT_API_URL → base URL of recounting counter API (second node)
|
||
env: GO2RTC_API_URL → go2rtc REST API (default http://localhost:1984)
|
||
env: GO2RTC_STREAM_NAME → go2rtc stream name for recount preview (default "recount")
|
||
```
|
||
```
|
||
|
||
### SQLite
|
||
```
|
||
table: batches (date, batch#, camera, label, count, start, end, created_at)
|
||
UNIQUE(counting_date, batch_number, camera_name, object_label)
|
||
table: daily_summaries (date, camera, label, total_count, total_batches, updated_at)
|
||
UNIQUE(counting_date, camera_name, object_label)
|
||
```
|
||
|
||
### JSON state file
|
||
```
|
||
path: /tmp/bytetrack_current_batch.json (default)
|
||
schema: {counting_date, batch_number, count, start_time, last_detection_time, counted_event_ids[]}
|
||
```
|
||
|
||
### Flask API
|
||
```
|
||
api: GET / → dashboard HTML
|
||
api: GET /api/current-batch → {count, batch_number, counting_date, start_time, last_detection_time}
|
||
api: GET /api/previous-batch → {date, batch#, count, start/end, duration_minutes}
|
||
api: GET /api/summary → {today, yesterday, all_time, average_per_day, best_day}
|
||
api: GET /api/daily-data?days=N → [ {date, total_count, total_batches, avg_per_batch} ]
|
||
api: GET /api/day-detail/<date> → {date, total_count, total_batches, total_duration, avg_duration, batches[]}
|
||
api: GET /api/recent-batches?limit=N → [ {date, batch#, count, start/end, duration} ]
|
||
api: GET /api/available-dates → [ {date, total_count, total_batches} ]
|
||
api: GET /api/export-daily-csv?days=N → .xlsx download (named csv, emits xlsx)
|
||
api: GET /api/export-day-csv/<date> → .xlsx download (named csv, emits xlsx)
|
||
api: GET /api/live-video → MJPEG stream from shared-memory JPEG
|
||
|
||
### Recounting dashboard
|
||
```
|
||
api: GET / → recounting HTML
|
||
api: GET /api/live-progress → proxy to LIVE_API_URL:/api/current-batch
|
||
api: GET /api/recount-progress → proxy to RECOUNT_API_URL:/api/current-batch
|
||
api: GET /api/batch-result?file=<path> → parse `batch_NN_YYYYMMDD_HHmmSS.mp4`, query live API for count
|
||
api: GET /api/mp4-files → [ {name, path, size, mtime} ... ]
|
||
api: POST /api/start-recount {path} → configure go2rtc stream, return {stream_url}
|
||
api: POST /api/stop-recount → tear down go2rtc stream
|
||
```
|
||
```
|
||
|
||
## §V — Invariants
|
||
|
||
```
|
||
V1: NUM_CLASSES must match model output → class 0=ayam, class 1=talenan
|
||
V2: line crossing → prev_cx > line_x ≥ cx (rtl) | prev_cx < line_x ≤ cx (ltr)
|
||
V3: ∀ track_id → counted at most once per batch (counted_event_ids set)
|
||
V4: batch persisted → count ≥ MIN_OBJECT_PER_BATCH & duration ≥ MIN_DURATION_PER_BATCH
|
||
V5: dt.time() < DAILY_CUTOFF_TIME → counting_date = today, else tomorrow
|
||
V6: talenan crossing → close batch, but ignored ∀ IGNORE_BATCH_LABEL_TIMEOUT_SEC after batch start
|
||
V7: batch inactivity ≥ BATCH_TIMEOUT_SECONDS → auto-close
|
||
V8: PYTHONNOUSERSITE=1 ! set for venv isolation
|
||
V9: .env ! exist before counter or dashboard starts
|
||
V10: DB tables ! exist on startup (created if absent, both store & dashboard)
|
||
V11: previous batch → last CARRY_IDS (default 50) track IDs carried forward to next batch
|
||
V12: ∃ ! batch per (date, batch#, camera, label) — UNIQUE constraint in DB
|
||
V13: counter & dashboard share DB path → no process-level coordination
|
||
V14: stream disconnect → reconnect with delay (RECONNECT_DELAY_SEC), ! block main loop
|
||
V15: model inference → letterbox-resize to IMGSZ×IMGSZ, BGR→RGB, run NPU
|
||
V16: NMS postprocessing → iou_thr=0.45, class-aware grouping, score > CONF
|
||
V17: tracks pruned after TRACKED_PRUNE_SEC (default 300s) without update
|
||
V18: .env missing → scripts fail at import (os.getenv falls back to defaults, may mismatch)
|
||
V19: stream reconnect → reset motion detection state (prev_gray = None)
|
||
```
|
||
|
||
## §T — Tasks
|
||
|
||
```
|
||
id|status|task|cites
|
||
T1|.|unify install paths — README/DEPLOY/setup-venv.sh/uninstall say `/opt/jetson-counter`, service files & .env.example say `/opt/bytetrack-counter`|
|
||
T2|.|zombie var RESET_COUNTERS_AT_CUTOFF — defined in .env.example, unused in code (confirmed by review)|
|
||
T3|.|add version flag — no `--version` or git-derived version exists|
|
||
T4|.|keep reference Python clean — counter_live.py is artifact; focus edits on counter_live_rknn_bytetrack.py as port source|
|
||
T5|.|rename export routes — routes named `export-daily-csv` but emit `.xlsx`|I.flask
|
||
T6|.|fix live-stream snapshot path — some scripts default `/dev/shm/jetson-counter/`, example says `bytetrack-counter`|
|
||
T7|.|add dashboard health-check endpoint (no `/health` or `/api/status` exists)|
|
||
T8|.|add model checks on startup — model class names ! validated against CLASS_AYAM/CLASS_TALENAN (TensorRT variant validates; RKNN variants do not)|
|
||
T9|.|reset prev_gray on stream reconnect — stale gray ref causes crash or false motion|V19,B1
|
||
T10|.|decay inf_ms toward 0 when inference skipped — stale display misleads operator|
|
||
T11|x|reduce live-counter poll interval 2000→200ms for real-time feel|
|
||
T12|x|add recounting dashboard — dual-API counter panels, MP4 browser, go2rtc streaming|
|
||
```
|
||
|
||
## §B — Bugs
|
||
|
||
```
|
||
id|date|cause|fix
|
||
B1|2026-07-29|prev_gray not reset on stream reconnect → cv2.absdiff crash or false motion|V19
|
||
```
|
||
|