YOLO-Coffee-Object-Detection/README.md

# Famico Product Detection — YOLOv8 Pipeline

**4 images/class → trained detector in ~2 hours (CPU) or ~15 min (GPU)**

---

## Quick start

```bash
pip install ultralytics albumentations opencv-python tqdm pyyaml
```

or using conda

```bash
conda env create -f enviroment.yml
```

---

## Step-by-step

### Step 1 — Set up folders

```bash
python 1_prepare_dataset.py
```

Edit `CLASS_NAMES` in the script first to list all 13 of your product classes.

---

### Step 2 — Label your images

Put your raw product photos into `dataset/images/train/`.

Use **Roboflow** (recommended) or **LabelImg** to draw bounding boxes and export in YOLO format:

- [Roboflow](https://roboflow.com) — free, web-based, exports directly to YOLO format
- LabelImg: `pip install labelImg && labelImg` or download it from [here](https://github.com/tzutalin/labelImg/files/2638199/windows_v1.8.1.zip)

Each image needs a matching `.txt` in `dataset/labels/train/`:

```
# famico_veloute_01.txt
0 0.512 0.483 0.320 0.541
```

Format: `class_id  cx  cy  width  height`  (all normalised 0–1)

---

### Step 3 — Augment

```bash
python 2_augment.py
```

Expands 4 images → ~200 augmented training images per original photo.
Takes 2–5 minutes.

Augmentations applied:
- Perspective warp, rotation, scale shift
- Brightness / contrast / hue jitter
- Blur, noise, JPEG compression
- Random cutout (occlusion simulation)
- Horizontal flip

---

### Step 4 — Train

```bash
python 3_train.py
```

| Hardware | Expected time |
|---|---|
| Laptop CPU | 60–90 min |
| GPU (any) | 5–15 min |
| Google Colab (free) | ~10 min |

Output: `runs/detect/famico_v1/weights/best.pt`

#### Training on Google Colab (recommended if no GPU)

```python
# Paste into a Colab cell:
!pip install ultralytics albumentations

# Upload your dataset folder to Colab, then:
!python 3_train.py
```

Or use Roboflow's free training pipeline which runs YOLOv8 on their GPU.

---

### Step 5 — Detect

```bash
# Single image
python 4_detect.py --source scene.jpg

# Folder of images
python 4_detect.py --source my_scenes/

# Webcam (live)
python 4_detect.py --source 0

# Custom confidence threshold
python 4_detect.py --source scene.jpg --conf 0.4
```

Results saved to `detections/`.

---

## Tuning tips

| Problem | Fix |
|---|---|
| Too many false positives | Raise `--conf` to 0.45–0.55 |
| Missing detections | Lower `--conf` to 0.25 |
| Boxes overlap too much | Lower `--iou` in detect.py |
| mAP < 0.5 after training | Add 5–10 more labeled images per class |
| Training loss doesn't converge | Lower `LR0` to 0.002 in train.py |

## Expected results

With 4 original images + augmentation and 13 classes:

- **mAP50 ≈ 0.65–0.80** (good for production)
- **Inference speed** ≈ 15–30ms/image on CPU, <5ms on GPU

Adding even 2–3 more labeled images per class typically pushes mAP above 0.85.