karung-counting-feedmill-semarang/AGENTS.md

# AGENTS.md — Feedmill Counting Platform (karung = sack counter)

Repo: `https://git.proit.id/andrew/karung-counting-feedmill-semarang` (transferred from `ervan/`; old remote redirects, but `git remote set-url origin` to the new URL).

AI video analytics (Jetson) counting feed sacks loaded onto trucks. UI/log strings are
Indonesian (`karung`=sack, `truk`=truck); YOLO class names are English
(`sack`, `box`, `truck`, `person`). Details: `README.md`, `docs/`.

## Which pipeline to touch

- `predict.py` = **production AND dev CLI** (runs as `karung-counter.service` with
  zero args). Dev flags: `--source VID --env .env --config YAML --model X --output-dir D
  --output-json F --sack-conf C --truck-conf C --box-conf C --box-model P
  --model-mode M --batch-timeout S --max-frames N --no-dashboard --no-db`.
  Zero flags = systemd behaviour (`config.yaml` + `.env`).
  Model modes are DATA in `config.yaml` `models.modes` (engines + class filters
  only; conf/iou/min_bbox in `models.detection_params`):
  A=combined only; B=v4 truck + yolo11n sack+box; C=A + yolo11n box-only (default);
  D=v4 truck + best sack-only + yolo11n box-only. New modes need no code change.
  All modes load `.engine` files (2-3 coexist, ~24 MB peak); never mix load
  order assumptions — PyTorch `.pt` must load before TensorRT `.engine`.
- `src/` = shared library (detection/tracking/counting/batch). `python -m src.main`
  still works but prints a deprecation pointer to `predict.py`.
- `archive/` = retired experiments (`predict_new.py`, `rpo_iki/`, `simple_predict.py`,
  check/merge/test scripts). Git history preserved via `git mv`. Don't resurrect
  without asking.

## Gotchas

- **Unified config**: `config.yaml` is canonical (stream/models/counting/batch/do/
  output/camera via `src/config_loader.py`); `.env` holds secrets + deployment
  only (`RTSP_URL`, dashboard host/ports/secret/site); `zones.json` holds
  geometry (polygons + left/right limits — knob keys there are ignored, warned);
  `cfg/tracker.yaml` holds tracker hyperparams. `src/config.py` (v3 keys like
  `LOCAL_RTSP`) is deprecated — don't add keys there. Dashboard mode switches
  write `config.yaml` `models.active_mode` (atomic, manual restart to apply);
  `batch_mode.json` keeps only batch flow mode (`auto`|`do_manual`|`manual`,
  default seed `batch.default_mode: manual`). `manual` start requires plate
  (`canonical_plate`: spaces/dots/hyphens stripped, upper; DB stores canonical,
  render `pretty_plate`); `auto` merges batches when a sack sits in the counting
  ROI — known limitation, fix not landed.
  **Port split:** `mode` / `model_mode` / `require_plate` / `require_do` POSTs →
  office `:5721` only (403 on `:5000`); **`ocr_engine` office-only too**
  (default `rapid`). Discard batch only if both **gross** `count==0` and
  `box_loading==0` (nets kept in DB/API). DO helpers: `src/do_batch.py`, OCR: `src/do_ocr.py`;
  ERD: `ERD.md` (repo root).
- **Counting filters by class name, not ID**: `SackDetector`/`BoxDetector`/
  `TruckDetector` filter via `BaseDetector(class_filter)` (`src/detection.py`);
  tracker keeps `("sack", "truck", "box")` (`src/tracking.py`); counting uses
  `MultiClassLineCounter` = dual `LineCrossCounter`s on one shared line
  (`src/counting.py`). Same line geometry + 30px dedup for sacks and boxes.
- All weights live in `models/` (`.pt`/`.onnx` tracked; `.engine` gitignored —
  rebuild via `export_model.py`; per-mode detector/filter matrix in
  `models/modelREADME.md`). Verified classes: `truck-detector`={truck},
  `model_karung_truk`/`v4-best`={sack,truck}, `karung-dimuat-*-seg-200e`=
  {person,sack} (seg; persons drawn, never counted), `best`={sack},
  `yolo11n-…-sack+box`={sack,box}. `predict.py` auto-picks `MODEL_PATH` env, else
  `models/v4-best.engine` > `.pt` > `v4-best (1).pt` > `models/model_karung_truk.*`.
  `src/config.py` defaults: `models/best.engine` (sack) / `models/truck-detector.engine`.
- Counting trigger is the bbox **top edge (y1)** vs a truck-anchored line band
  (`src/counting.py`, `src/truck_roi.py`); truck detect runs every 15th frame only.
- Auto-mode batch timers (`config.yaml batch:`): `timeout_seconds` = sack-idle
  pause (→ `WAITING_FOR_ACTIVITY`), `truck_gone_tolerance_seconds` = truck-gone
  finalize (hardcoded 30 s override in `predict.py` removed). `truck_in_area`
  accepts ≥50 % bbox overlap of `detection_polygon` (100 % containment flickered
  False for big docked trucks → split batches); transitions log `[TRUCK] truck_in_area`.
- **Tests:** `python -m pytest tests/ -q` (smoke tests for `counting`, `batch`,
  `config`, `do_batch` — pure-Python; Flask API tests skip if flask/openpyxl
  missing). Deps: `requirements.txt` (unpinned; **never** pip-install torch from
  PyPI on the Jetson — use the NVIDIA wheels already on device). For visual checks
  run on a video file (`--source`), not the live RTSP.
- **Don't commit state**: `.gitignore` excludes `*.engine` (rebuildable),
  `*.mp4/*.jpg/*.png`, `*.db`, `.env`, `batch_history_folder/`. Videos and local
  DBs already sit untracked in the working tree — leave them alone.

## Deploy (Jetson `192.168.192.96`, user `jetson`)

- `deploy_to_jetson.py` syncs `predict.py`, `counter_dashboard.py`,
  `templates/{operator,monitoring,base}.html`, `.env`, **plus `models/*.engine`**
  (skips missing local files; creates remote `models/`). `.pt`/`.onnx` stay local.
  Edits elsewhere (e.g. `src/`, `zones.json`) need manual sync.
- Services: `karung-counter` (`predict.py`), `karung-counter-dashboard`
  (`counter_dashboard.py`, ports 5000/5721). TensorRT export:
  `python export_model.py models/<name>.pt` — run on the Jetson.