zoncoen/tic-tac-toe-cell-detector

Tic-tac-toe Cell Detector (YOLOv8n)

Overview

• YOLOv8n model that detects occupancy per 3x3 cell (empty / white_circle / black_cross).
• Output: bounding boxes and classes for 9 cells. The included script can overlay cell indices and labels on the image.
• Intended input: top-down tic-tac-toe board images (matching this repo's synthetic/real data distribution).

License

• Model weights: CC-BY-4.0
• Code: AGPL-3.0 (per Ultralytics dependency)
• Source code for data generation/training/inference: https://github.com/guren-kaina/AMD_Robotics_Hackathon_2025_ProjectTemplate/tree/main/mission2/code/tic_tac_toe_overlay

Usage

pip install ultralytics
python - <<'PY'
from ultralytics import YOLO
model = YOLO("models/train/weights/best.pt")  # weights from this repo
res = model("your_input.jpg", imgsz=640, conf=0.25)
print(res[0].boxes.cls, res[0].boxes.xyxy)
res[0].save(filename="overlay.jpg")  # visualization
PY

• Class IDs: 0=empty_cell, 1=white_circle_cell, 2=black_cross_cell
• The included main.py runs preprocessing, cell index drawing, and JSON export.

Training data

• Synthetic: gray background + white grid, includes low contrast/blur/noise and O/X distractors. Default generation train 1000 / val 200.
• Real: real/images and YOLO-format labels real/labels (no PII).

Training setup

• Base: Ultralytics YOLOv8n
• Image size: default 640
• Epochs: default 20
• Options: --preprocess-train for contrast augmentation, --real-data to mix real data into training
• Weights saved to models/train/weights/best.pt

Limitations and notes

• Accuracy may drop with oblique views or extreme lighting.
• Only 3 classes; out-of-board objects or different token shapes are unsupported.
• For new domains, re-label and retrain.