Upload README.md

README.md

@@ -1,3 +1,179 @@
----
-license: mit
----
+# 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
+
+```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 /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>
+
+```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 and use webcam/upload.
+
+## CLI Prediction
+
+```bash
+python predict.py path/to/image_or_folder --model model/jankentron.pt
+```
+
+Outputs are saved to:
+
+```text
+runs/predict
+```
+
+## 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.