Initial commit: Wood knot detection model and GUI

README.md

@@ -0,0 +1,153 @@
+# Saw Mill Knot Detection (RF-DETR)
+
+This repo contains a minimal training pipeline to fine-tune **RF-DETR** to detect knots in wood.
+
+**Dataset Source**: The wood defect images and annotations used in this project come from [Kaggle Wood Surface Defects Dataset](https://www.kaggle.com/datasets/kirs0816/wood-surface-defects?resource=download).
+
+## 1) Dataset format (required)
+RF-DETR expects **COCO format**, split into `train/`, `valid/`, `test/`, each with its own `_annotations.coco.json`.
+
+Example:
+
+```
+dataset/
+├── train/
+│   ├── _annotations.coco.json
+│   ├── 0001.jpg
+│   └── ...
+├── valid/
+│   ├── _annotations.coco.json
+│   ├── 0101.jpg
+│   └── ...
+└── test/
+    ├── _annotations.coco.json
+    ├── 0201.jpg
+    └── ...
+```
+
+Your COCO JSON should include a `categories` entry for your class(es), e.g. `knot`.
+
+## 2) Setup
+
+Create venv (already created if you used the VS Code prompt) and install deps:
+
+```bash
+/home/dillon/_code/saw_mill_knot_detection/.venv/bin/python -m pip install -U pip
+/home/dillon/_code/saw_mill_knot_detection/.venv/bin/python -m pip install -r requirements.txt
+```
+
+## 3) Validate dataset
+
+```bash
+/home/dillon/_code/saw_mill_knot_detection/.venv/bin/python validate_coco_dataset.py --dataset-dir /path/to/dataset
+```
+
+## 4) Train
+
+```bash
+/home/dillon/_code/saw_mill_knot_detection/.venv/bin/python train_rfdetr.py \
+  --dataset-dir /path/to/dataset \
+  --output-dir runs/knot_rfdetr_medium \
+  --model medium \
+  --epochs 50 \
+  --batch-size 4 \
+  --grad-accum-steps 4 \
+  --lr 1e-4
+```
+
+Notes:
+- Keep **effective batch size** near 16: `batch_size * grad_accum_steps * num_gpus ≈ 16`.
+- Checkpoints are written into `--output-dir` (including `checkpoint_best_total.pth`).
+
+## 5) Auto-label new images (automatic)
+
+Use your trained model to generate annotations on unlabeled images:
+
+```bash
+/home/dillon/_code/saw_mill_knot_detection/.venv/bin/python auto_label_images.py \
+  --weights runs/knot_rfdetr_medium/checkpoint_best_total.pth \
+  --images-dir /path/to/new_images \
+  --output-json auto_labeled.json \
+  --threshold 0.4
+```
+
+This outputs a COCO JSON with predicted bounding boxes. You can then review/correct them manually.
+
+## 6) Manual labeling (recommended tools)
+
+**Don't build your own GUI** - use these proven open-source tools instead:
+
+### Option A: Label Studio (Recommended - Easiest)
+**Best for**: Quick setup, modern UI, ML-assisted labeling
+
+```bash
+# Install Label Studio
+pip install label-studio
+
+# Start the server
+label-studio start
+```
+
+Then open http://localhost:8080 in your browser:
+1. Create a new project for "Object Detection with Bounding Boxes"
+2. Import your images
+3. Start labeling manually OR:
+   - Use the auto-label script to generate initial annotations:
+     ```bash
+     /home/dillon/_code/saw_mill_knot_detection/.venv/bin/python auto_label_images.py \
+       --weights runs/knot_rfdetr_medium/checkpoint_best_total.pth \
+       --images-dir /path/to/images \
+       --output-json predictions.json \
+       --threshold 0.3
+     ```
+   - Import the predictions into Label Studio
+   - Review and correct them
+4. Export in COCO format when done
+
+### Option B: CVAT (Most Powerful)
+**Best for**: Large-scale projects, team collaboration
+
+```bash
+# Using Docker (easiest)
+git clone https://github.com/opencv/cvat
+cd cvat
+docker compose up -d
+```
+
+Open http://localhost:8080:
+- Create project → upload images → annotate
+- Supports keyboard shortcuts, interpolation, and advanced features
+- Export directly to COCO JSON
+
+[CVAT Documentation](https://opencv.github.io/cvat/docs/)
+
+### Option C: labelImg (Simplest Desktop App)
+**Best for**: Offline labeling, no server needed
+
+```bash
+pip install labelImg
+labelImg
+```
+
+- Simple desktop app with no web server
+- Exports to Pascal VOC (needs conversion to COCO)
+- Good for small datasets
+
+### Workflow with Model Assistance:
+1. **Initial batch**: Manually label 50-100 images
+2. **Train RF-DETR**: Use your training script
+3. **Auto-label**: Run `auto_label_images.py` on remaining images
+4. **Review**: Import predictions into Label Studio/CVAT
+5. **Correct**: Fix any mistakes (much faster than labeling from scratch)
+6. **Iterate**: Retrain with corrected labels, repeat
+
+This semi-supervised approach is **10-20x faster** than manual labeling alone.
+
+## 7) Quick inference sanity check
+
+```bash
+/home/dillon/_code/saw_mill_knot_detection/.venv/bin/python predict_rfdetr.py \
+  --weights runs/knot_rfdetr_medium/checkpoint_best_total.pth \
+  --image /path/to/example.jpg \
+  --threshold 0.4
+```