README.md

metadata

title: JankenTron
emoji: ✊
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.43.1
app_file: app.py
pinned: false

JankenTron

JankenTron is a live Rock-Paper-Scissors computer vision model. It connects to a webcam, continuously detects hand gestures, recognizes one visible hand, and highlights the winner when exactly two hands are visible. It also supports uploaded images for single-frame testing.

Built by Amin / BreakRules.

What It Does

• Detects rock, paper, and scissors hand gestures.
• Supports one hand for gesture recognition and two hands for a full game.
• Applies Rock-Paper-Scissors rules when exactly two hands are detected.
• Highlights winner, loser, or tie directly on the image.
• Runs live in 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 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. Use Live Webcam for continuous recognition or Upload Image for single-frame testing.

CLI Prediction

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

Outputs are saved to:

runs/predict

Speed And Accuracy Tips

Hugging Face free CPU Spaces are slower than a local GPU. The Space uses faster live defaults:

Confidence Threshold: 0.45
Inference Image Size: 416
Live Stream Interval: 0.8s
Max Box Area Filter: 0.45

For more speed:

• Use image size 320 or 416.
• Keep confidence at 0.45 or higher.
• Keep the camera background clean.
• Show the hand close enough, but do not fill the full frame.
• Upgrade the Space hardware to T4 GPU if true smooth live inference is needed.

If the model detects a face as paper:

• Increase Confidence Threshold to 0.55 or 0.60.
• Lower Max Box Area Filter to 0.30 or 0.35.
• Keep faces out of the center of the frame when testing.
• Improve the dataset later with negative examples: faces, empty frames, normal people without hand gestures.

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.