274 lines
10 KiB
Markdown
274 lines
10 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
|
||
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/<coop>/<floor>/<date>/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://<JETSON-IP>: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/<Coop>/mortality/<YYYY-MM-DD>/`.
|
||
|
||
#### 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_<original_name>.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/<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.
|