139 lines
7.2 KiB
Markdown
139 lines
7.2 KiB
Markdown
# Karung Counter
|
|
|
|
> Repo: `https://git.proit.id/andrew/karung-counting-feedmill-semarang`
|
|
|
|
AI video-analytics system that **counts feed sacks (`karung-pakan`) being loaded onto /
|
|
unloaded from trucks** at a feedmill loading gate. It watches an RTSP camera, detects the
|
|
truck bed, tracks sacks with persistent IDs, counts line-crossings per truck (batch),
|
|
persists results to SQLite/CSV, and serves a live Flask dashboard.
|
|
|
|
> **Language note:** UI strings, logs and comments are largely in Indonesian
|
|
> (`karung` = sack/bag, `truk` = truck, `muat` = load). Class names inside the YOLO
|
|
> models are English (`sack`, `box`, `truck`, `person`).
|
|
|
|
## Pipeline (production, `predict.py`)
|
|
|
|
```
|
|
Frame → TruckDetect → ROI → SackTrack → Stabilize → Count → Dashboard / DB
|
|
```
|
|
|
|
| Stage | Module | What it does |
|
|
|---|---|---|
|
|
| Stream | `src/streaming.py` | RTSP (`RTSPSource`) or video file (`VideoFileSource`) |
|
|
| Truck detect | `src/detection.py` (`TruckDetector`) | Dedicated truck model, run every 15 frames |
|
|
| ROI | `src/truck_roi.py` (`TruckROITracker`) | Picks main truck in lane, EMA-smooths bbox, derives counting line |
|
|
| Sack track | `src/tracking.py` (`ByteTrackTracker`) | YOLO + FastTrack/ByteTrack, tuned via `cfg/tracker.yaml` |
|
|
| Stabilize | `src/stabilizer.py` (`BboxStabilizer`) | EMA bbox smoothing + occlusion hold + height clamps |
|
|
| Count | `src/counting.py` (`LineCrossCounter`) | Zone-based line crossing: loading / unloading / net, 3-layer dedup |
|
|
| Batch | `src/batch.py` (`BatchLifecycleManager`) | 4-state FSM: IDLE → TRUCK_STABILIZING → COUNTING_SACKS ⇄ WAITING_FOR_ACTIVITY |
|
|
| Output | `src/logger.py`, `src/dashboard.py` | CSV logs + on-frame overlay |
|
|
|
|
Full detail: [`docs/architecture.md`](docs/architecture.md).
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
pip install -r requirements.txt # Jetson: never pip-install torch from PyPI, use NVIDIA wheels
|
|
cp .env.example .env # then edit RTSP_URL / paths
|
|
|
|
# Dev / offline (any flags omitted = production defaults):
|
|
python predict.py --source path/to/video.mp4 --env .env
|
|
python predict.py --source vid.mp4 --no-dashboard --no-db --output-dir /tmp/out --max-frames 500
|
|
python predict.py --help # all flags: --config/--model/--model-mode/--output-json/--sack-conf/--truck-conf/--box-conf/--box-model/--batch-timeout
|
|
|
|
# Production (Jetson systemd, zero flags):
|
|
sudo systemctl restart karung-counter karung-counter-dashboard
|
|
```
|
|
|
|
Production on the Jetson runs `predict.py` + `counter_dashboard.py` as systemd services
|
|
(see [`docs/deployment.md`](docs/deployment.md)) — `predict.py` is the production
|
|
pipeline (SQLite persistence, live-frame publishing to `/dev/shm`, zone polygons);
|
|
the `src/` package is the shared detection/tracking/counting library it builds on
|
|
(the old v3 `src/main.py` loop is deprecated). Retired experiments live in `archive/`.
|
|
|
|
## Models
|
|
|
|
All weights live in `models/` (see [`models/modelREADME.md`](models/modelREADME.md) for the
|
|
per-mode detector/filter matrix).
|
|
|
|
| File | Classes | Role |
|
|
|---|---|---|
|
|
| `models/truck-detector.{pt,engine}` | `truck` | Specialized truck detector (ROI, batch lifecycle) |
|
|
| `models/v4-best.{pt,onnx,engine}` / `models/model_karung_truk.{pt,onnx,engine}` | `sack`, `truck` | Combined sack+truck (Modes A/B/C/D truck; Modes A/C sack) |
|
|
| `models/karung-dimuat-…-seg-200e.{pt,onnx,engine}` | `person`, `sack` | Segmentation model: sacks counted, persons drawn/skipped |
|
|
| `models/yolo11n-bbox-100ep-sack+box-20260909-best.{pt,onnx,engine}` | `sack`, `box` | Unified sack+box (Modes B/C/D) |
|
|
| `models/best.{pt,onnx,engine}` | `sack` | Sack-only specialist (Mode D sack) |
|
|
|
|
`.pt` = PyTorch, `.engine` = TensorRT FP16 (Jetson GPU, what production loads),
|
|
`.onnx` = ONNX export artifact.
|
|
See [`docs/models.md`](docs/models.md) for the multi-model / multi-class / hybrid
|
|
support matrix.
|
|
|
|
## Configuration
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `config.yaml` | Canonical config: stream, model modes/presets, counting knobs, batch, output paths, camera |
|
|
| `.env` (see `.env.example`) | Secrets + deployment only: RTSP URL, dashboard host/ports/secret/site |
|
|
| `zones.json` | Calibrated pallet / truck / counting polygons + left/right limits (geometry only) |
|
|
| `cfg/tracker.yaml` | FastTrack/ByteTrack occlusion tuning (buffer 60, re-ID windows) |
|
|
|
|
See [`docs/configuration.md`](docs/configuration.md) for every variable.
|
|
|
|
## Dashboard (`counter_dashboard.py`, port 5000 / office 5721)
|
|
|
|
Pages in `templates/`: `monitoring.html`, `operator.html` (batch start/stop;
|
|
DO panel in `do_manual`), `history.html`, `analytics.html`. JSON APIs under
|
|
`/api/*` (live video MJPEG, current/previous batch, summary, daily data,
|
|
batch mode, DO upload/staged/settings, CSV/Excel export). Data source:
|
|
`jetson_counter.db` + `current_batch.json` + `batch_mode.json`
|
|
(batch flow: `auto` | `do_manual` | `manual`; model mode in `config.yaml`).
|
|
|
|
### Batch modes
|
|
|
|
| Mode | Who opens/closes batch | DO gate |
|
|
|---|---|---|
|
|
| `auto` (default) | AI truck FSM | — |
|
|
| `do_manual` | Operator + DO photo scan | yes |
|
|
| `manual` | Operator buttons (legacy) | no |
|
|
|
|
Office (`:5721`) switches mode / model mode / require_plate (403 on operator
|
|
POST). **DO manual flow:** open `http://<jetson>:5000/operator` on a phone →
|
|
Ambil Foto DO → review/edit OCR fields → Mulai Batch → count → Selesai
|
|
(soft-warn if zone busy). Discard only when both sack and box nets are 0.
|
|
ERD: [`docs/do-erd.md`](docs/do-erd.md).
|
|
Plan: [`docs/do-batch-implementation-plan.md`](docs/do-batch-implementation-plan.md).
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
src/ Shared library (streaming, detection, tracking, stabilizer,
|
|
truck_roi, counting, batch, dashboard, logger, config_loader, main)
|
|
config.yaml Canonical config (stream/models/counting/batch/output/camera)
|
|
cfg/tracker.yaml Tracker tuning
|
|
predict.py Single entrypoint: production service + dev CLI (see --help)
|
|
counter_dashboard.py Flask dashboard + APIs | templates/*.html pages
|
|
tests/ Pytest smoke tests (counting, batch, config, config_loader)
|
|
archive/ Retired experiments (predict_new.py, rpo_iki/, simple_predict.py,
|
|
check/merge/test scripts) — history preserved, not imported
|
|
export_model.py Export .pt → TensorRT .engine (FP16) | export_v4.py variant
|
|
deploy_to_jetson.py Paramiko sync + service restart
|
|
*.service systemd units (counter, dashboard, mediamtx)
|
|
zones.json Calibrated zone geometry
|
|
batch_history_folder/ Per-batch JSON reports
|
|
CHANGELOG.md Release history (dated entries, Keep-a-Changelog style)
|
|
```
|
|
|
|
Script-by-script reference: [`docs/scripts.md`](docs/scripts.md).
|
|
|
|
## Docs
|
|
|
|
- [`docs/architecture.md`](docs/architecture.md) — pipeline stages, modules, batch FSM
|
|
- [`docs/models.md`](docs/models.md) — model inventory & detection-mode support matrix
|
|
- [`docs/configuration.md`](docs/configuration.md) — all config files/variables
|
|
- [`docs/deployment.md`](docs/deployment.md) — Jetson services, TensorRT, deploy flow
|
|
- [`docs/do-erd.md`](docs/do-erd.md) — delivery-order / batch ERD (Mermaid)
|
|
- [`docs/do-batch-implementation-plan.md`](docs/do-batch-implementation-plan.md) — DO manual batch plan
|
|
- [`docs/scripts.md`](docs/scripts.md) — entry points & utility scripts
|
|
- [`CHANGELOG.md`](CHANGELOG.md) — release history
|