karung-counting-feedmill-semarang/README.md

# 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 (v3, `src/`)

```
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: --model/--output-json/--sack-conf/--truck-conf/--box-conf/--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)) — the `src/` package is the clean
re-implementation; `predict.py` / `predict_new.py` are the deployed legacy pipelines that
add SQLite persistence, live-frame publishing to `/dev/shm`, and zone polygons.

## Models

All weights live in `models/` (see [`models/README.md`](models/README.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 |
|---|---|
| `.env` (see `.env.example`) | DB paths, camera name, object label, cutoff time, ports, RTSP URL |
| `zones.json` | Calibrated pallet / truck / counting polygons + tuning knobs |
| `cfg/tracker.yaml` | FastTrack/ByteTrack occlusion tuning (buffer 60, re-ID windows) |
| `rpo_iki/configs/` | Alternate counting engine configs (areas, params, model registry, cameras) |

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` (manual batch start/stop),
`history.html`, `analytics.html`. JSON APIs under `/api/*` (live video MJPEG, current/
previous batch, summary, daily data, CSV/Excel export). Data source:
`jetson_counter.db` + `current_batch.json` (+ `batch_mode.json`).

## Repository layout

```
src/                  Shared library (streaming, detection, tracking, stabilizer,
                      truck_roi, counting, batch, dashboard, logger, config, main)
cfg/tracker.yaml      Tracker tuning
predict.py            Single entrypoint: production service + dev CLI (see --help)
counter_dashboard.py  Flask dashboard + APIs  |  templates/*.html  pages
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 zones
batch_history_folder/ Per-batch JSON reports
```

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/scripts.md`](docs/scripts.md) — entry points & utility scripts