karung-counting-feedmill-semarang/docs/configuration.md

Configuration

Canonical source: config.yaml (repo root) — stream, models, counting knobs, batch, output paths, camera. Loaded once at startup via src/config_loader.py (stdlib dataclasses + pyyaml, no heavy deps). Secrets & deployment-only values stay in .env. Zone polygons stay in zones.json. Tracker hyperparams stay in cfg/tracker.yaml.

config.yaml          canonical: stream/models/counting/batch/output/camera
.env                 secrets + deployment: RTSP_URL, dashboard host/ports/secret/site
zones.json           geometry: palet/truck/counting polygons + left/right limits
cfg/tracker.yaml     tracker hyperparams (FastTrack/ByteTrack tuning)

Model modes are data (config.yaml → models.modes): each preset declares only engines (path key + contributed classes) and class_filters. Per-class conf/iou/min_bbox_area live in models.detection_params and apply to ALL modes. Adding mode E/F/... is a YAML-only change — predict.py derives tracker roles structurally, and the dashboard /api/model-modes endpoint lists them automatically.

Mode switch: dashboard POST /api/batch/mode {"model_mode": "X"} validates against config.yaml and persists atomically (tmp+replace, comments preserved) to models.active_mode. Manual karung-counter restart still required (models load once at startup). batch_mode.json keeps only the manual/auto batch mode; its legacy model_mode key is ignored (warned). MODEL_MODE env var still overrides for one run but is deprecated (warned).

Template: .env.example. Production values live in .env (git-ignored). Missing config.yaml falls back to .env + built-in defaults with a warning (see src/config_loader.py); explicit legacy path env vars below still override when set.

1. .env (secrets & deployment — predict.py / counter_dashboard.py)

Key	Default	Meaning
OUTPUT_DIR	/opt/jetson-counter	Legacy override of output.dir when set
DB_PATH	$OUTPUT_DIR/jetson_counter.db	Legacy override of the SQLite path when set
STATE_FILE	$OUTPUT_DIR/current_batch.json	Legacy override of the live batch state path when set
BATCH_MODE_FILE	$OUTPUT_DIR/batch_mode.json	Legacy override (file keeps only manual/auto batch mode now)
LIVE_STREAM_FRAME_PATH	/dev/shm/jetson-counter/live_frame.jpg	Legacy override of the annotated frame path when set
CAMERA_NAME	CC1	Camera tag stored per batch
OBJECT_LABEL	karung-pakan	Object tag stored per batch
DAILY_CUTOFF_TIME	06:00	Counting-day boundary (get_counting_date)
SECRET_KEY	—	Flask session key (change in production)
DASHBOARD_HOST / DASHBOARD_PORT	0.0.0.0 / 5000	Dashboard bind
OFFICE_PORT	5721	Second dashboard port
FLASK_DEBUG	false	Flask debug
RTSP_URL	—	Camera stream URL (env-only, never in YAML)
MODEL_PATH	— (deprecated)	Single-file v4 override, folded into models.paths
MODEL_MODE	— (deprecated)	One-run override of models.active_mode (warned)
BATCH_MERGE_THRESHOLD_SECONDS	300	Merge window for adjacent batches

On Windows dev machines these resolve to d:/Belajar/menghitung karung/....

2. src/config.py keys (deprecated v3 src/main.py --env)

⚠️ Deprecated — the v3 loop is retired; production uses config.yaml via src/config_loader.py. Documented here only because the old keys still exist in code. Do not add new keys here.

⚠️ Different names from the table above — the v3 loader uses its own keys:

Key	Default
LOCAL_RTSP / JETSON_RTSP	""
MODEL_SACK_PATH / MODEL_TRUCK_PATH	./models/best.engine, ./models/truck-detector.engine
COUNTING_LINE_Y / _X_START / _X_END	0.60 / 0.38 / 0.72 (fractions; initial line before ROI sync)
SACK_CONF_THRESHOLD / TRUCK_CONF_THRESHOLD	0.40 / 0.50
BATCH_TIMEOUT_SECONDS	30
CSV_OUTPUT_DIR	./output
DATA_SEED	42

CLI: python -m src.main --source video.mp4 --env .env.

3. zones.json (calibrated geometry, 1920×1080 reference)

• palet / truck / counting — zone polygons; scaled to actual resolution at startup.
• left_limit / right_limit (0.27578 / 0.72578) — counting X band.
• external_stream_url — MediaMTX restream endpoint.
• Legacy knob keys (duplicate_circle_radius, min_valid_area, jarak_toleransi_duplikat, max_reid_transit_distance, circle_stay_timeout_sec, inference_stride, confirm_delay_sec, exit_confirm_delay_sec) are ignored with a warning — they moved to config.yaml counting.* / stream.inference_stride. Keep only geometry here.

Recalibrate with archive/get_coordinates.py / archive/get_calib_frame.py (calib_frame.jpg).

4. cfg/tracker.yaml (FastTrack/ByteTrack tuning)

track_buffer=60 (~2.4 s lost-track hold for worker occlusion), new_track_thresh=0.30 (anti-duplicate IDs), track_high/low_thresh=0.20/0.05, match_thresh=0.85, active_occ_to_lost_thresh=15, occ_reappear_window=60, enlarge_bbox_occ=1.15, occ_cover_thresh=0.6, Kalman offsets + init_iou_suppress=0.65. Falls back to stock bytetrack.yaml if the file is missing (src/tracking.py:39).

5. archive/rpo_iki/configs/ (retired alternate engine, not imported)

area_truk*.json (per-camera truck areas), cameras.json (cam1/cam2 RTSP), counting_params.json (+ counting_params_last_truck.json, hot-reloaded by count.py), model_registry.json (pinned model + metrics), telegram.json (notification settings).