JankenTron

JankenTron is a Rock-Paper-Scissors computer vision model. It opens a webcam or accepts an uploaded image, detects hand gestures in real time-style inference, and highlights the winner when exactly two hands are visible.

Built by Amin / BreakRules.

What It Does

• Detects rock, paper, and scissors hand gestures.
• Supports one or two hands in an image.
• Applies Rock-Paper-Scissors rules when exactly two hands are detected.
• Highlights winner, loser, or tie directly on the image.
• Runs locally with Gradio and can be deployed to Hugging Face Spaces.

Project Structure

jankentron/
  app.py                 # Gradio web app for Hugging Face Spaces/local UI
  jankentron_model.py    # YOLO loading, prediction, game rules, drawing
  prepare_data.py        # Downloads Kaggle dataset and converts labels to YOLO format
  train.py               # Trains YOLO and saves model/jankentron.pt
  predict.py             # CLI inference for local images
  deploy.py              # Optional Hugging Face upload helper
  requirements.txt       # Python dependencies

Generated folders are intentionally ignored by Git:

dataset/
runs/
model/
photos/

Install

cd /Users/aminmammadov/aiwork/models/jankentron
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Prepare Dataset

Dataset: https://www.kaggle.com/datasets/adilshamim8/rock-paper-scissors

python prepare_data.py

This creates:

dataset/data.yaml
dataset/images/train
dataset/images/test
dataset/labels/train
dataset/labels/test

Train

python train.py --model yolo11n.pt --epochs 30 --batch 16 --imgsz 640

Final local weights are saved here:

model/jankentron.pt

Run Locally

python app.py

Then open the local Gradio URL and use webcam/upload.

CLI Prediction

python predict.py path/to/image_or_folder --model model/jankentron.pt

Outputs are saved to:

runs/predict

Hugging Face Layout

Use two Hugging Face repositories:

HF Model repo:  sdhaos/Jankentron
HF Space repo:  sdhaos/Jankentron

Model repositories and Space repositories are different repo types, so they can use the same slug.

Files For Hugging Face Models

Upload only the trained model artifact:

jankentron.pt

Optional but useful:

README.md

Files For Hugging Face Spaces

Upload the app code, not the dataset or training runs:

app.py
jankentron_model.py
requirements.txt
README.md

The Space loads the model from the HF model repo by default: sdhaos/Jankentron.

To use another model repo, set this Space environment variable:

JANKENTRON_MODEL=your-username/your-model-repo

Hugging Face Commands

Login first:

hf auth login

Create and upload the model repository:

cd /Users/aminmammadov/aiwork/models/jankentron
hf repos create sdhaos/Jankentron --type model --exist-ok
hf upload sdhaos/Jankentron model/jankentron.pt jankentron.pt --repo-type model --commit-message "Upload JankenTron weights"

Create and upload the Space:

cd /Users/aminmammadov/aiwork/models/jankentron
hf repos create sdhaos/Jankentron --type space --space-sdk gradio --exist-ok --env JANKENTRON_MODEL=sdhaos/Jankentron
hf upload sdhaos/Jankentron app.py app.py --repo-type space --commit-message "Deploy JankenTron app"
hf upload sdhaos/Jankentron jankentron_model.py jankentron_model.py --repo-type space --commit-message "Add inference logic"
hf upload sdhaos/Jankentron requirements.txt requirements.txt --repo-type space --commit-message "Add Space dependencies"
hf upload sdhaos/Jankentron README.md README.md --repo-type space --commit-message "Add Space README"

Alternative using the helper script:

cd /Users/aminmammadov/aiwork/models/jankentron
python3 deploy.py model --repo-id sdhaos/Jankentron
python3 deploy.py space --repo-id sdhaos/Jankentron

Notes

• Do not push dataset/, runs/, or model/ to GitHub.
• Store large trained weights in Hugging Face Models.
• Store only app files in Hugging Face Spaces.