# Models

Class names below are read directly from each checkpoint (`YOLO(path).names`).
Formats present: `.pt` (PyTorch) → `.onnx` (ONNX) → `.engine` (TensorRT FP16 for Jetson;
see `export_model.py` / `export_v4.py`).

## Inventory

All weights live in `models/` — full per-mode detector/filter matrix in
[`models/modelREADME.md`](../models/modelREADME.md).

| File | Classes | Task | Used by |
|---|---|---|---|
| `models/truck-detector.{pt,engine}` | `{0: truck}` | bbox | Dedicated truck specialist; `src/config.py` default truck model |
| `models/model_karung_truk.{pt,onnx,engine}` | `{0: sack, 1: truck}` | bbox | Legacy combined alias (auto-pick fallback in `predict.py`) |
| `models/v4-best.{pt,onnx,engine}` (`v4-best (1).pt` = duplicate copy) | `{0: sack, 1: truck}` | bbox | Combined model (Modes A/B/C/D truck; Modes A/C sack) |
| `models/karung-dimuat-detection-di-feedmill-yolo26n-seg-200e.{pt,onnx,engine}` | `{0: person, 1: sack}` | **seg** | Person-exclusion seg model (legacy `predict_new.py`) |
| `models/yolo11n-bbox-100ep-sack+box-20260909-best.{pt,onnx,engine}` | `{0: sack, 1: box}` | bbox | Unified sack+box (Modes B/C/D) |
| `models/best.{pt,onnx,engine}` | `{0: sack}` | seg | Sack-only specialist (Mode D sack; `src/config.py` default) |

Model registry for the `rpo_iki` engine: `rpo_iki/configs/model_registry.json`
(currently pins `karung-dimuat-seg-200e`, mAP50-mask 0.899, val MAE 0.67).

## Support matrix

### 1. Multiple specialized models — YES (current design)
Two dedicated models run in parallel on the same frames:
- **Truck model** (`truck-detector.pt`) → presence, ROI, counting-line placement,
  batch lifecycle. Runs every 15th frame in `src/main.py:130-145`.
- **Sack model** (seg or combined) → per-frame track + count (`src/main.py:163-169`).
- `predict_new.py:184-185` hardcodes the same duo (`TRUCK_MODEL_PATH`, `SACK_MODEL_PATH`);
  `rpo_iki/count.py:1136-1143` prefers a dedicated `truck-detector.pt` for dynamic
  truck calibration.

### 2. Multiple classes within a single model — YES (filter-then-count)
- Combined models expose 2 classes (`sack`+`truck`, `person`+`sack`, `sack`+`box`).
- Consumers select what they need and ignore the rest:
  - `SackDetector._parse` (`src/detection.py:34`): keeps `name == "sack"` only.
  - `ByteTrackTracker._parse` (`src/tracking.py:62`): keeps `("sack", "truck")`.
  - `predict_new.py:379-389,571-579`: auto-detects karung/person class IDs by name
    substring, tracks `classes=[person, sack]`, draws persons in red and skips them
    in counting.
  - `rpo_iki/count.py` (`SACK_CLASS_ID = 1`): counts one class; falls back to the same
    model's `truck_class_id=2` when no dedicated truck model exists.
- Rule of thumb: **only the sack/karung class is ever counted**; other classes are
  auxiliary (ROI, visualization, exclusion).

### 3. Hybrid multi-model — YES (modes A/B/C/D, default C)
- `predict.py --model-mode` (or `MODEL_MODE` env / dashboard `/api/batch/mode`):

  | Mode | Truck | Sack | Box |
  |---|---|---|---|
  | A | v4 (sack+truck) | v4 | — |
  | B | v4 (truck-only) | yolo11n | yolo11n |
  | C (default) | v4 (sack+truck) | v4 | yolo11n (box-only) |  | D | v4 (truck-only) | best (sack-only) | yolo11n (box-only) |

- All weights load as `.engine` (verified coexist: 2 engines ~16 MB, 3 engines
  ~24 MB peak of 7.6 GB). Dashboard switches persist to `batch_mode.json` and
  apply on next service restart (models load once at startup).
- Counting: `MultiClassLineCounter` = dual `LineCrossCounter`s on one shared line;
  events tagged with `class_name`; sack and box track IDs live in separate spaces.

## Choosing / swapping a model
- `src/` pipeline: `MODEL_SACK_PATH` / `MODEL_TRUCK_PATH` env vars (defaults:
  `./models/best.engine` / `./models/truck-detector.engine`; see
  [`configuration.md`](configuration.md)) or `--source` for files.
- `predict.py`: `config.yaml` `models.paths` is canonical (per-mode presets in
  `models.modes`, per-class conf/iou/min_bbox in `models.detection_params`).
  Legacy overrides still work: `MODEL_PATH` env or `--model` (single v4 file),
  `--box-model` (yolo11n weights), `--model-mode` / deprecated `MODEL_MODE` env
  for the preset, `--sack-conf` / `--truck-conf` / `--box-conf` for thresholds.
- TensorRT: `python export_model.py models/<name>.pt` (FP16 `.engine`) on the Jetson;
  production loads `.engine` only (missing `.engine` falls back to the `.pt`
  sibling with a warning). `deploy_to_jetson.py` syncs `config.yaml` + the `.engine` files.