Everything you need to get running

Install

Gesto Labeller — download the release, unzip it anywhere, and run GestoLabeller.exe. No Python required.

The gesto package — install from PyPI into a fresh virtual environment:

# a clean environment avoids dependency clashes
python -m venv gesto_env
# Windows
gesto_env\Scripts\activate
# macOS / Linux
source gesto_env/bin/activate

pip install gesto

Quickstart

The whole loop — capture, train, detect — in four moves:

1. In Gesto Labeller, create a project, pick a region and mode, and capture ~20–30 samples per class.
2. Note the project folder (use the Copy path button).
3. Train and detect:

gesto train static hands_one "C:\...\gesto_projects\my-signs"
gesto detect static hands_one

A window opens with your webcam, the detected skeleton, and a live probability bar for every class.

Capturing data

In the Annotate tab, add a class name, choose Static or Sequence, pick the region, and press Start. Hold or perform the gesture and press Capture (or the space bar).

Tips for good data

• Balance your classes — a similar number of samples each.
• ~20–30 samples per class is plenty to start.
• Keep Normalise on (the default) — it makes recognition position- and scale-independent.
• For sequences, keep clip length consistent with Max frames.

Static vs sequence

The single most important choice — pick the one that matches your gesture.

Static — a held shape

One frame per sample. Use it when the gesture is the pose: hand signs, letters, a thumbs-up, a stance. Needs little data, detects instantly.

Sequence — a motion

A window of frames. Use it when the gesture is defined by movement: waving, clapping, a swipe. Needs more data and captures change over time.

Regions

A region decides which landmarks are tracked. Match it to your project when training.

Training

Point gesto train at a Labeller project. The form is gesto train <mode> <region> <project>:

gesto train static hands_one ./gesto_projects/signs
gesto train sequence pose ./gesto_projects/jog --epochs 400 --seq-len 30

Epochs, batch size, and validation split are all adjustable. Small datasets automatically use a lighter model, avoiding the classic failure where an oversized network collapses to always predicting one class.

Prefer one command per combination? Those exist too:

gesto train-static-legs ./gesto_projects/stances --epochs 250

Detection

Run the newest model for a region. --source takes a webcam index or a video path:

gesto detect static hands_one                 # default webcam
gesto detect sequence pose --source clip.mp4  # a video file
gesto detect static hands_one --no-draw       # hide the skeleton

Classify a single image with a static model:

gesto image hands_one photo.jpg

Useful flags: --threshold, --smooth, --width, --version.

Model storage

Every trained model lands under one artifacts/ folder, split by mode then region. Training never overwrites — it versions:

artifacts/
  static/
    hands_one/      # first run
    hands_one_2/    # next run, kept separately
  sequence/
    pose/

gesto detect static pose uses the newest version by default; --version 1 selects a specific one. See everything with gesto list.

Troubleshooting

Everything maps to one class

Almost always a data issue. Run gesto inspect <project> to check class balance, sample counts, and feature dimension. Usually too few samples or a heavy imbalance.

Detection is wrong even though training looked fine

Make sure the region matches the project, and that Normalise was on for both capture and detection (on by default in each).

"No module named 'mediapipe'" or a solutions error

Install the pinned MediaPipe: pip install "mediapipe>=0.10,<0.10.30". Versions 0.10.31+ removed the API Gesto uses.