commit 099ac2b4399100b8d765a1229f6d8c93a9483746
Author: Hamza <hadjammar.hamza.zakaria@gmail.com>
Date:   Sun Apr 26 15:00:12 2026 +0200

    Add README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6547d01
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# 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 torch
+```
+
+---
+
+## 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`
+
+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.
\ No newline at end of file