85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# Cold Display Guard Project Documentation
|
|
|
|
## Goal
|
|
|
|
`cold-display-guard` monitors refrigerated display food batches by camera region. It tracks how long each configured food region remains occupied, raises a configurable time alarm, and escalates alarmed food to a warning if it is removed without a matching trash-bin deposit.
|
|
|
|
The `v1.1 优化改造` batch upgrades the product from a fixed 8-zone layout to a configurable 1-10 zone workflow with numeric region labels and editable trash ROI calibration. All v1.1 items are part of one batch; backend, API, frontend, and documentation are implementation workstreams inside that same batch.
|
|
|
|
## Architecture
|
|
|
|
- Backend package: `src/cold_display_guard/`
|
|
- `models.py`: settings, observations, and batch dataclasses.
|
|
- `engine.py`: deterministic batch state machine.
|
|
- `config.py`: TOML config load/save, calibration merge, and project path resolution.
|
|
- `manage_api.py`: standard-library HTTP management API.
|
|
- `main.py`: RTSP runtime loop connecting frame capture, vision, state engine, and JSONL sinks.
|
|
- `vision.py`: heuristic ROI occupancy and trash-motion detection.
|
|
- Frontend package: `web/`
|
|
- Vite + vanilla JavaScript management console.
|
|
- Default web port `23000`.
|
|
- API proxy target `http://127.0.0.1:19080`.
|
|
- Runtime home view falls back to clearly marked demo data when no real events exist, so the operational layout still shows summary cards, dwell timers, and event rows.
|
|
- Runtime data:
|
|
- Events JSONL default path `logs/events.jsonl`.
|
|
- Diagnostics JSONL default path `logs/runtime_diagnostics.jsonl`.
|
|
- Deployment:
|
|
- Root Python Docker image for API/runtime.
|
|
- `web/Dockerfile` for static web console.
|
|
- `deploy/docker-compose.yml` wires API, runtime, and web services.
|
|
|
|
## Configuration
|
|
|
|
- Main config path: `config/example.toml`.
|
|
- Camera identity: `camera_id`.
|
|
- Timezone default: `Asia/Shanghai`.
|
|
- RTSP input: `[stream] rtsp_url`.
|
|
- Thresholds:
|
|
- `max_dwell_seconds`: v1.1 time-alarm threshold. Default can remain 10800 seconds; users can set values such as 1200 seconds for 20 minutes.
|
|
- `trash_confirmation_seconds`: window after an alarmed batch is removed where a trash deposit must be observed before warning escalation.
|
|
- Food zones:
|
|
- v1.1 food zone IDs are numeric strings from `"1"` through `"10"`.
|
|
- The configured zone count must be between 1 and 10.
|
|
- If both `zone_count` and numeric `zone_ids` are present, they must agree.
|
|
- Each `[[zones]]` polygon must have at least 3 normalized points.
|
|
- Trash ROI:
|
|
- Stored under `[trash] roi`.
|
|
- Does not use a food zone number.
|
|
|
|
## Event Model
|
|
|
|
- `batch_started`: a food region changes from empty to occupied.
|
|
- `time_alarm`: an active batch reaches `max_dwell_seconds` while still in the display region.
|
|
- `batch_count_changed`: count decreases while the region remains occupied.
|
|
- `mixed_batch_violation`: count increases before the region clears.
|
|
- `batch_consumed`: a non-alarmed batch clears before the threshold.
|
|
- `batch_pending_disposal`: an alarmed batch clears and waits for trash confirmation.
|
|
- `batch_discarded`: a pending alarmed batch is matched to a trash deposit.
|
|
- `warning_escalated`: a pending alarmed batch is not matched to a trash deposit before the confirmation deadline.
|
|
|
|
Events should include `zone_id`, `zone_index`, `zone_label`, `started_at`, `dwell_seconds`, and relevant alarm/removal/deadline timestamps when available.
|
|
|
|
## Runbook
|
|
|
|
- Python tests:
|
|
- `PYTHONPATH=src python3 -m unittest discover -s tests -v`
|
|
- Management API:
|
|
- `scripts/run_manage_api.sh`
|
|
- Health: `curl http://127.0.0.1:19080/api/manage/health`
|
|
- Web console:
|
|
- `scripts/run_web.sh`
|
|
- Build: `cd web && pnpm build`
|
|
- Frontend logic tests: `node --test web/test/zone-state.test.js`
|
|
- Docker web URL: `http://127.0.0.1:23000`
|
|
- Runtime monitor:
|
|
- `scripts/run_runtime.sh`
|
|
- One-frame smoke test when camera and `ffmpeg` are available:
|
|
- `PYTHONPATH=src python3 -m cold_display_guard.main --config config/example.toml --once`
|
|
|
|
## Known Risks
|
|
|
|
- The current vision detector is heuristic and reports binary occupancy, not item counts.
|
|
- If food is already present during baseline collection, those regions may be treated as empty baseline until visual changes occur.
|
|
- Changing calibration while the runtime process has active batches can create operational ambiguity; v1.1 should document or enforce a pause/restart expectation.
|
|
- Historical events must keep the zone index at the time of emission so later region reordering does not reinterpret old logs.
|