# 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 venv/bin/pip install -e . ``` > **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, kandang-atas) │ │ ├── K1-L1.yaml .. K5-L2.yaml ← Extends cycle7_batch_optimized.yaml │ │ └── kandang-atas.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 & floors dynamically for a specific date ./run_all_coops.sh 2026-06-18 # Run a specific floor using its config file PYTHONPATH=src venv/bin/python -m chicken_counter.cli batch \ --config configs/floor_config/K1-L1.yaml \ --date 2026-06-18 # Run directly on ANY discovered floor (virtual config — zero YAML required!) PYTHONPATH=src venv/bin/python -m chicken_counter.cli batch \ --floor K6-L1 \ --date 2026-06-18 # Automatically scan VIDEOS and generate boilerplate YAMLs for any newly added floors PYTHONPATH=src venv/bin/python -m chicken_counter.cli sync-configs ``` Output is saved in `../VIDEOS/cycle7////output/`. --- ### B — Mortality Detection (Per-Coop Carcass Photo Scanning) #### Method 1: Stationary Inspection Camera Capture (Recommended for Farm Workers) Each coop (or central mortality table) is equipped with a dedicated stationary camera (RTSP stream or USB camera) mounted above the inspection area: 1. **Open the Webapp**: From any phone, tablet, or terminal on the farm local network, navigate to `http://:8080`. 2. **Open Mortality Inspector**: Under the sidebar **💀 Mortality Scans**, tap **`📷 Upload / Capture`**. 3. **Select Coop & Inspect View**: - Choose the coop (e.g. `K1`). - The live preview from that coop's stationary camera displays on screen so the worker can verify the chickens are spread out properly on the table. 4. **Capture Batch 1**: - Tap **`📸 Snap & Count Batch from Camera`**. - The system grabs the frame from the camera, runs YOLO carcass detection, and shows the count (e.g. *"Batch 1: 18 carcasses detected"*). 5. **Capture Subsequent Batches (if needed)**: - Clear the table and place the next batch of chickens. - Tap **`📸 Snap & Count Next Batch`**. - The system automatically captures `capture_02_...jpg`, runs detection, and increments the daily total: *"Total for K1 Today: 30 carcasses across 2 batches"*. 6. All high-res captures and output detection overlays are saved permanently in `VIDEOS/cycle7//mortality//`. #### Camera Configuration (`configs/mortality_config.yaml`) Map each coop to its RTSP stream URL, HTTP snapshot URL, or USB device index: ```yaml mortality: cameras: K1: "rtsp://admin:admin@192.168.1.101:554/live" K2: "rtsp://admin:admin@192.168.1.102:554/live" K3: "rtsp://admin:admin@192.168.1.103:554/live" K4: "rtsp://admin:admin@192.168.1.104:554/live" K5: "rtsp://admin:admin@192.168.1.105:554/live" ``` #### Method 2: Command Line Batch Run Place input photos inside each coop's mortality directory (e.g. `../VIDEOS/cycle7/K1/mortality/`, `../VIDEOS/cycle7/K2/mortality/`, etc.). ```bash # Run mortality detection across ALL discovered coops (K1..K5, etc.) ./run_mortality_all.sh # Run for a specific coop ./run_mortality_all.sh K1 # or via CLI: PYTHONPATH=src venv/bin/python -m chicken_counter.cli mortality --coop K1 # Run across all coops for a specific date ./run_mortality_all.sh 2026-06-18 # Run directly on a specific image file PYTHONPATH=src venv/bin/python -m chicken_counter.cli mortality -i /path/to/photo.jpg ``` Output annotated images are saved as `output_.jpg` in each coop's mortality directory. A `mortality_report.json` is generated for each coop, tagging the coop name and all covered floors (e.g., `["K1-L1", "K1-L2", "K1-L3"]`). #### 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.