# Quick Start Guide This guide gets a new developer up and running from scratch. --- ## 1. Prerequisites - Python 3.10+ - `ffmpeg` on PATH (for video compression) - NVIDIA GPU + CUDA drivers (optional but recommended for inference speed) --- ## 2. First-Time Setup ```bash # Clone / copy the project folder, then enter it cd chicken-counting-sukawarna-det # Create a virtual environment and install all dependencies python3 -m venv venv venv/bin/pip install --upgrade pip venv/bin/pip install -r requirements.txt ``` > **Note**: If moving the project from another machine, always recreate the venv. > Do NOT copy the `venv/` folder — it contains absolute paths baked in from the source machine. --- ## 3. Project Layout ```text chicken-counting-sukawarna-det/ ├── configs/ │ ├── floor_config/ ← Lightweight floor configs (K1-L1 to K5-L2) │ │ ├── K1-L1.yaml .. K5-L2.yaml ← Extends cycle7_batch_optimized.yaml │ ├── cycle7_batch_optimized.yaml ← Main base batch processing config │ ├── cycle7_batch.yaml ← Alternate batch config │ ├── mortality_config.yaml ← Mortality (carcass) detection config │ ├── cameras/example_camera.yaml ← Single-camera run config template │ └── trackers/botsort_chicken.yaml ← BoT-SORT tracker settings ├── db/ │ └── chicken_counts.db ← SQLite database (auto-created) ├── models/ ← Place your .pt / .onnx / .engine files here │ ├── chicken-detection-model-v26n-300e-best-2026-05-02-NEW.pt ← Source PyTorch model │ ├── chicken-detection-model-v26n-300e-best-2026-05-02-NEW.engine ← Hardware-tuned TensorRT │ └── chicken-detection-model-v26n-seg-300e-best-2026-04-18.pt ← Used by mortality ├── src/chicken_counter/ ← Main Python package (counting, tracking, motion, engine_utils) ├── templates/ ← Dashboard HTML ├── dashboard.py ← Live API + Dashboard server ├── export_engine.py ← Manual TensorRT export utility ├── export_excel_report.py ← Excel reporting & analytics generator ├── run_all_coops.sh ← Master multi-coop batch runner (K1-L1 to K5-L2) ├── start_dashboard.sh ← Portable dashboard launcher ← USE THIS ├── test_run_folder/ ← Archive of test run scripts and logs └── requirements.txt ``` --- ## 4. Model Setup & Auto-Recompilation Put your model files in the `models/` directory. | Purpose | File | Notes | | :--- | :--- | :--- | | Batch video counting (TensorRT) | `models/chicken-detection-model-v26n-300e-best-2026-05-02-NEW.engine` | Maximum GPU throughput | | Base PyTorch weights | `models/chicken-detection-model-v26n-300e-best-2026-05-02-NEW.pt` | Used for portable runs and auto-recompiling engines | | Mortality detection | `models/chicken-detection-model-v26n-seg-300e-best-2026-04-18.pt` | Direct segmentation model (2-pass disabled by default for accuracy) | > **Self-Healing Recompilation on New Machines**: If you move the project to a new machine with a different GPU or OS, the pipeline will detect any incompatible `.engine`, automatically locate the matching `.pt` model, recompile a new `.engine` for the host machine, and update `configs/cycle7_batch_optimized.yaml` automatically. --- ## 5. Running the Systems ### A — Batch Video Processing (Daily Chicken Count) Place input videos under the `VIDEOS` folder adjacent to the project following the `K{coop}-L{floor}` format: ```text ../VIDEOS/cycle7/ K1-L1/ 2026-06-18/ K1-L1_cam1_2026-06-18_120056.mp4 K1-L1_cam2_2026-06-18_120456.mp4 K1-L1_cam3_2026-06-18_121012.mp4 K1-L1_cam4_2026-06-18_121530.mp4 ``` Then run: ```bash # Run all coops (10 floors: K1-L1 to K5-L2) for a specific date ./run_all_coops.sh 2026-06-18 # Run a specific floor (e.g. Kandang 1 Lantai 1) PYTHONPATH=src venv/bin/python -m chicken_counter.cli batch \ --config configs/floor_config/K1-L1.yaml \ --date 2026-06-18 # Run archive scripts in test_run_folder ./test_run_folder/test_run.sh ./test_run_folder/test_run_tensor_batch.sh ./test_run_folder/test_run_hybrid.sh ``` Output is saved in `../VIDEOS/cycle7/kandang-atas/2026-06-18/output/`. --- ### B — Mortality Detection (Carcass Photo Scanning) Place input photos in `../VIDEOS/cycle7/kandang-atas/mortality/`. ```bash # Run with default config ./test_run_mortality.sh # Override confidence threshold CONF=0.65 ./test_run_mortality.sh # Run on a specific image ./test_run_mortality.sh /path/to/photo.jpg ``` Output annotated images are saved as `output_.jpg` in the same directory. A `mortality_report.json` is also saved there with full detection data. #### Key config options in `configs/mortality_config.yaml` | Setting | Description | | :--- | :--- | | `conf` | Detection confidence threshold (0.0–1.0) | | `iou` | IoU NMS threshold | | `min_box_area_px` | Minimum bounding box area in pixels | | `dedupe_radius_px` | Centroid deduplication radius in pixels | | `two_pass` | 2x Detect & Refine pipeline (`false` by default; single-pass direct achieves higher accuracy on farm footage) | | `classes` | `[0]` = chicken only; ignores background/text/equipment | --- ### C — Dashboard & API Server ```bash # Start the dashboard (auto-discovers mortality directory) ./start_dashboard.sh # Custom port and directories PORT=9090 ./start_dashboard.sh # Multiple mortality directories MORTALITY_DIRS="/path/to/mortality1,/path/to/mortality2" ./start_dashboard.sh ``` Open in browser: **http://localhost:8080** Available API endpoints: | Endpoint | Description | | :--- | :--- | | `GET /api/status` | Live system status, active counting cameras & latest date | | `GET /api/cameras` | Live camera list from `/dev/shm` | | `GET /api/db/summary` | Total chickens, days, hours across all dates | | `GET /api/db/history` | Per-date summary, newest first | | `GET /api/db/date/` | Per-camera breakdown for a specific date | | `GET /api/db/camera/` | History for a specific camera (CC1, CC2...) | | `GET /api/db/location/` | Summary and history for a location | | `GET /api/mortality/latest` | Latest mortality detection report (JSON) | | `GET /api/mortality/history` | All mortality reports, newest first | | `GET /api/mortality/image/` | Serve annotated output JPEG by filename | | `GET /shm//stats.json` | Live pipeline stats for a running camera | | `GET /shm//frame.jpg` | Live frame snapshot from a running camera | See `API.md` for full response schemas. --- ### D — Install as a System Service (Auto-Start) ```bash # Copy the service file and adjust WorkingDirectory / User if needed sudo cp chicken-dashboard.service /etc/systemd/system/ # Enable and start sudo systemctl daemon-reload sudo systemctl enable chicken-dashboard sudo systemctl start chicken-dashboard # Check status sudo systemctl status chicken-dashboard ``` The service reads `start_dashboard.sh`, so it also auto-discovers the mortality directory. --- ## 6. Database Results are automatically written to `db/chicken_counts.db` when `db_path` is set in the batch YAML. To store results manually from a JSON report: ```bash PYTHONPATH=src venv/bin/python store_results.py \ ../VIDEOS/cycle7/kandang-atas/2026-06-18/output/counts_2026-06-18.json \ --location kandang-atas \ --db db/chicken_counts.db ``` Export to Excel: ```bash PYTHONPATH=src venv/bin/python export_excel_report.py ``` --- ## 7. Moving the Project to Another Machine 1. Delete the `venv/` folder before copying: ```bash rm -rf venv/ ``` 2. Copy the entire project folder to the new machine. 3. Update the `WorkingDirectory` and `ExecStart` in `chicken-dashboard.service` to the new path. 4. Recreate the venv on the new machine: ```bash python3 -m venv venv venv/bin/pip install -r requirements.txt ``` 5. All configs and Python code use relative paths and will work without any other changes.