README.md

---
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

```text
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:

```text
dataset/
runs/
model/
photos/
```

## Install

```bash
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>

```bash
python prepare_data.py
```

This creates:

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

## Train

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

Final local weights are saved here:

```text
model/jankentron.pt
```

## Run Locally

```bash
python app.py
```

Then open the local Gradio URL. Use **Live Webcam** for continuous recognition or **Upload Image** for single-frame testing.

## CLI Prediction

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

Outputs are saved to:

```text
runs/predict
```

## Speed And Accuracy Tips

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

```text
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:

```text
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:

```text
jankentron.pt
```

Optional but useful:

```text
README.md
```

### Files For Hugging Face Spaces

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

```text
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:

```text
JANKENTRON_MODEL=your-username/your-model-repo
```

## Hugging Face Commands

Login first:

```bash
hf auth login
```

Create and upload the model repository:

```bash
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:

```bash
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:

```bash
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.