Poker Card Detection (Ultralytics YOLO)

Real-time poker card detection using Ultralytics YOLO. This repository includes:

• Training script to fine-tune YOLO on a custom dataset
• Webcam inference script for real-time detection with FPS overlay
• Dataset in YOLO format (train/valid/test splits)

---

Project Structure

├─ dataset/
│  ├─ data.yaml
│  ├─ kaggle_data.yaml
│  ├─ train/{images,labels}
│  ├─ valid/{images,labels}
│  └─ test/{images,labels}
├─ runs/
│  └─ detect/trainX/... (Ultralytics training outputs)
├─ main.py          # Train YOLO on the dataset
├─ evaluate.py      # Real-time webcam inference with FPS
├─ test.py          # Print CUDA & Torch versions and GPU name
├─ requirements.txt # Pinned dependencies
├─ yolov8n.pt       # Example base weights
├─ yolo11n.pt       # Optional base weights
└─ README.md

---

Prerequisites

• Windows 10/11 with PowerShell
• Python 3.10–3.12 recommended
• Optional but recommended: NVIDIA GPU with recent driver (CUDA 12.x compatible) for fast training/inference

This repo includes two virtual environments (poker_env/ and venv_win/). To avoid conflicts, use only one. The steps below assume venv_win.

---

Quickstart

1. Activate the virtual environment

./venv_win/Scripts/Activate.ps1

2. Install dependencies

pip install -r requirements.txt

3. Verify Torch/CUDA and GPU availability (optional)

python ./test.py

You should see the CUDA version, Torch version, and your GPU name. If you do not have a compatible GPU/driver, see CPU-only setup below.

---

Dataset

The dataset is already provided in YOLO format under dataset/ with train/, valid/, and test/ splits.

• Update the YAML path used for training in main.py if needed (currently: ./dataset/kaggle_data.yaml).
• Ensure the YAML files point to the correct relative paths for images and labels.

Example YAML (conceptual):

path: ./dataset
train: train/images
val: valid/images
test: test/images
names:
  0: card
  # ... more classes if applicable

---

Training

main.py fine-tunes YOLOv8n on your dataset for 50 epochs, 640 image size, batch 16.

python ./main.py

Outputs are saved under runs/detect/train*. The best weights typically live at runs/detect/trainX/weights/best.pt.

To change hyperparameters, edit main.py (e.g., epochs, imgsz, batch, YAML path).

---

Real-Time Inference (Webcam)

evaluate.py opens your default camera, runs inference, and displays annotated frames with FPS.

python ./evaluate.py

Notes:

• The script loads weights from runs/detect/train5/weights/best.pt by default. If your latest training run differs, update the path in evaluate.py.
• Press q to exit the preview window.

---

Single-Image Prediction

Use predict_image.py to run inference on a single image file and optionally save/show the annotated output.

# Basic usage (prints detections)
python ./predict_image.py path/to/image.jpg

# Specify custom weights and save annotated image
python ./predict_image.py path/to/image.jpg --weights runs/detect/train5/weights/best.pt --save

# Display annotated image in a window (press any key to close)
python ./predict_image.py path/to/image.jpg --show

# Choose output folder and run name
python ./predict_image.py path/to/image.jpg --save --project runs/predict_image --name exp1

Notes:

• Defaults to runs/detect/train5/weights/best.pt. Update --weights if your best model is elsewhere.
• The script prints class IDs by default; you can map them to names using the YAML names list in your dataset config.

---

CPU-Only Setup (if you do not have a compatible NVIDIA GPU)

The pinned requirements.txt targets CUDA 12.x GPU builds of PyTorch. For CPU-only:

1. Create/activate a fresh environment (recommended)

python -m venv venv_cpu
./venv_cpu/Scripts/Activate.ps1

2. Install CPU wheels

pip install --upgrade pip
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install ultralytics opencv-python pyyaml matplotlib

3. Run main.py and evaluate.py as usual. Training/inference will be slower on CPU.

---

Tips & Troubleshooting

• Single environment: Avoid mixing poker_env and venv_win. Ensure python -c "import sys; print(sys.executable)" points to the same environment where you installed packages.
• Camera busy or missing: Close apps using the webcam (Teams/Zoom/etc.). You can also try changing the camera index in cv2.VideoCapture(0) to 1 or 2.
• Weight path mismatch: After training, confirm the path in evaluate.py matches the latest run directory.
• Driver/CUDA mismatch: If Torch cannot find CUDA or imports fail due to nvidia-* packages, either update your NVIDIA driver to match CUDA 12.x or use the CPU-only instructions above.
• Batch size and memory: If you hit out-of-memory during training, lower batch in main.py and/or reduce imgsz.

---

Useful Commands

# Activate env
./venv_win/Scripts/Activate.ps1

# Install deps
pip install -r requirements.txt

# Verify CUDA/Torch/GPU
python ./test.py

# Train
python ./main.py

# Real-time webcam inference (press 'q' to quit)
python ./evaluate.py

---

References

• Ultralytics YOLO docs: https://docs.ultralytics.com
• OpenCV docs: https://docs.opencv.org