chicken-counting-sukawarna-det/RUN.md

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

# 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

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:

../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:

# 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/.

# 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_<original_name>.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

# 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/<YYYY-MM-DD>	Per-camera breakdown for a specific date
GET /api/db/camera/<id>	History for a specific camera (CC1, CC2...)
GET /api/db/location/<name>	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/<filename>	Serve annotated output JPEG by filename
GET /shm/<cam>/stats.json	Live pipeline stats for a running camera
GET /shm/<cam>/frame.jpg	Live frame snapshot from a running camera

See API.md for full response schemas.

---

D — Install as a System Service (Auto-Start)

# 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:

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:

PYTHONPATH=src venv/bin/python export_excel_report.py

---

7. Moving the Project to Another Machine

1. Delete the venv/ folder before copying:

   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:

   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.