233 lines
8.0 KiB
Markdown
233 lines
8.0 KiB
Markdown
# 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_<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
|
||
|
||
```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/<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)
|
||
|
||
```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.
|