# Green-on-Green Detection

Green-on-Green (GoG) detection enables the OWL to identify weeds growing within crops, where traditional colour-based detection cannot distinguish weed from crop.

## Overview

GoG uses YOLO object detection models to identify weeds directly, regardless of background. Two inference backends are supported:

| Backend | Format | Best for |
|---------|--------|----------|
| **NCNN** (recommended) | Directory with `.param` + `.bin` files | Production on Raspberry Pi — fast, no GPU needed |
| **PyTorch** | Single `.pt` file | Development and training |

Models are loaded automatically from the `models/` directory. The OWL auto-detects the model format.

## Hardware Requirements

The OWL runs YOLO inference natively on the Raspberry Pi via NCNN. The Google Coral USB Accelerator that earlier
documentation referenced is no longer recommended — it has been superseded by the Raspberry Pi AI Hat+, which is the
current recommended accelerator for in-field Green-on-Green deployments.

**Recommended:** Raspberry Pi AI Hat+. The Waveshare variant is widely available — [Waveshare AI Hat+](https://www.waveshare.com/raspberry-pi-ai-hat-plus.htm?sku=29050) — and other Hailo-based AI Hat+ variants from different vendors work the same way. Higher-compute variants cost more but let you run larger inference image sizes, which is worth it if you need higher accuracy on smaller targets.

**Without an accelerator:** the Pi can run smaller NCNN models on CPU only. That works for testing and low-resolution
inference, but the AI Hat+ is what unlocks larger image sizes and the frame rates needed for boom-speed operation.

## Installing AI

AI detection needs `ultralytics` (with PyTorch and NCNN) in the OWL's virtual environment. Units set up with
`owl_setup.sh --factory` ship without it, so a fresh factory unit can only run colour detection until AI is installed.

Every OWL reports what AI it can run in its state and in the standalone `/api/system_stats`:

```json
"ai": {
  "cpu": {"installed": true},
  "hailo": {"present": false, "chip": null, "runtime": false},
  "accelerator": "cpu"
}
```

`accelerator` is `hailo8` when a Hailo-8 card and its runtime are both present, `cpu` when only ultralytics is
installed, and `null` when the unit has no AI. While it is `null`, the dashboards refuse the AI and Hybrid modes
with a plain reason instead of selecting a mode the OWL cannot run.

**Install AI from the dashboard or phone app.** `POST /api/ai/install` runs a normal software update at the
branch the OWL is on and also installs `requirements-gog.txt`. It needs an internet connection (a phone hotspot
works) and about 3 GB of free space, and can take 20 minutes or more on a Pi. Progress is the ordinary update
progress (`GET /api/settings/update/status` on a standalone OWL, `GET /api/update/status` on the networked
controller). On the networked controller the same route takes `{"device_ids": ["owl-1"]}` or `"all"`. If the
install fails, or runs past the update's 30 minute limit, the update rolls back like any other.

**Install AI over SSH:**

```bash
bash ~/owl/owl_update.sh --with-ai
```

### If AI cannot load

Choosing AI is only saved once the OWL reports the model running. If it cannot load (no AI installed, no model,
a damaged model), the OWL keeps detecting with its previous mode, and `algorithm_error` in the state says why.
An OWL that starts up with `algorithm = gog` or `gog-hybrid` in its config and cannot load the model falls back
to `exhsv` colour detection, so a unit is never left without detection after a restart. The config file is not
changed, so the unit runs AI again once the problem is fixed.

## Detection Modes

OWL supports two GoG detection strategies, selected by the `algorithm` config key:

**`gog` — Direct detection**
: The YOLO model detects weeds directly. Each detection bounding box is mapped to a relay lane for actuation. Use this when your model is trained specifically on weeds.

**`gog-hybrid` — Crop masking + colour detection**
: The YOLO model identifies and masks crop regions. The remaining (non-crop) areas are then processed with the ExHSV colour algorithm to find weeds. Use this when you have a crop model but not a weed-specific model.

## Actuation Modes

How YOLO detections are mapped to relay lanes:

**`centre` (default)**
: The horizontal centre of each bounding box determines which relay lane fires. Works with both detection and segmentation models.

**`zone`**
: Uses the segmentation mask to count pixels in each relay lane. Only fires if the pixel count exceeds `min_detection_pixels`. Requires a segmentation model (trained with `-seg` suffix).

Set the mode with the `actuation_mode` key in `[GreenOnGreen]`.

## Model Management

### Placing models manually

Copy model files to `~/owl/models/` on the Raspberry Pi:

- **NCNN**: A directory containing a `.param` and `.bin` file pair
- **PyTorch**: A single `.pt` file

```bash
# Example: copy an NCNN model
scp -r my_model_ncnn/ owl@owl.local:~/owl/models/
```

### Upload and deploy via dashboard

The networked controller includes a model management page for uploading and deploying models wirelessly:

1. Open the controller's `/models` page from a laptop browser
2. Upload a `.pt` file or `.zip` containing NCNN `.param` + `.bin` files
3. Select target OWL devices
4. Click Deploy — the model is transferred to each OWL over the network

Each OWL checks the download's SHA-256 before it touches the model it already has. For an NCNN zip it checks
the zip file first (the hash Noktura sends), then the extracted files (the hash the controller sends). A zip
whose files sit in one top-level folder is unpacked without that folder. If the check or the unpacking fails,
the previous model stays in place and `model_download` in the state reports the error.

### Hot-swap via AI tab

The dashboard AI tab lets you switch between models without restarting:

1. Open the **AI** tab in the dashboard
2. Select a model from the dropdown — shows model type (detection/segmentation), format, and size
3. Filter which classes to detect using the class button grid
4. Click **Apply** to hot-swap the model

## Weed Tracking

When `tracking_enabled = True` in the `[Tracking]` config section, OWL uses ByteTrack to assign persistent IDs to detected weeds across frames. This provides:

- **Class smoothing**: Predictions are averaged over a sliding window (`track_class_window` frames) to reduce class flickering
- **Crop mask stabilisation**: In `gog-hybrid` mode, crop mask regions persist for `track_crop_persist` frames after a crop detection leaves the frame, preventing false positives at crop edges

Tracking adds minimal overhead and is recommended for GoG deployments.

## Training Your Own Model

1. **Collect images** of weeds in your specific field conditions — lighting, soil type, growth stage, and crop all matter
2. **Annotate images** using [Roboflow](https://roboflow.com/) or [Label Studio](https://labelstud.io/) to draw bounding boxes (or polygons for segmentation) around weeds
3. **Train with Ultralytics YOLO**:
   ```bash
   pip install ultralytics
   yolo detect train data=your_dataset.yaml model=yolov8n.pt epochs=100 imgsz=320
   ```
4. **Export to NCNN** for deployment on Raspberry Pi:
   ```bash
   yolo export model=best.pt format=ncnn imgsz=320
   ```
   This creates a directory with `.param` and `.bin` files ready to copy to `~/owl/models/`.

Check [Weed-AI](https://weed-ai.sydney.edu.au/explore?is_head_filter=%5B%22latest+version%22%5D) for existing annotated weed image datasets that may be relevant for your conditions.

## Configuration

### GreenOnGreen parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `model_path` | `models` | Directory containing YOLO model files. |
| `confidence` | `0.5` | Minimum confidence threshold (0.0-1.0). |
| `detect_classes` | *(empty)* | Comma-separated class IDs to detect. Empty = all classes. |
| `actuation_mode` | `centre` | Relay mapping: `centre` (box centre) or `zone` (mask pixel count). |
| `min_detection_pixels` | `50` | Minimum mask pixels for zone mode actuation. |
| `inference_resolution` | `320` | YOLO input image size. Smaller = faster, larger = more accurate. |
| `crop_buffer_px` | `20` | Pixel buffer around crop mask regions (gog-hybrid). |

### Tracking parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `tracking_enabled` | `False` | Enable ByteTrack multi-object tracking. |
| `track_class_window` | `5` | Frames to smooth class predictions over. |
| `track_crop_persist` | `3` | Frames a crop mask persists after detection leaves. |

---

## Next Steps

- [Configuration Guide](../configuration/index.md) - Full parameter reference
- [AI Assistant](../agent/index.md) - Control detection settings through natural language
- [Weed-AI](https://weed-ai.sydney.edu.au/) - Access training datasets