gesto 0.1.0__tar.gz

gesto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sundar Balamurugan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gesto-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include tests *.py

gesto-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: gesto
+Version: 0.1.0
+Summary: Train and run gesture recognition models from Gesto Labeller datasets
+Author: Sundar Balamurugan
+License: MIT
+Project-URL: Homepage, https://github.com/TheMadrasTechie/gesto
+Project-URL: Issues, https://github.com/TheMadrasTechie/gesto/issues
+Keywords: gesture-recognition,mediapipe,pose-estimation,computer-vision,lstm,sign-language
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: tensorflow>=2.15
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: mediapipe>=0.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# gesto
+
+Train and run gesture recognition models from [Gesto Labeller](https://github.com/TheMadrasTechie) datasets.
+
+Point it at a project folder, pick a mode and a region, and it handles the rest —
+loading, training, versioned model storage, and live detection that matches how
+the data was captured.
+
+```bash
+pip install gesto
+```
+
+## Two modes
+
+| mode | the gesture is… | model | example |
+|---|---|---|---|
+| `static` | a held shape or posture | Dense network | thumbs up, alphabet letters, a stance |
+| `sequence` | a motion over time | stacked LSTM | waving, clapping, jogging |
+
+Static needs far less data (every captured frame is a training sample) and
+predicts instantly with no warm-up. Reach for `sequence` only when two gestures
+share the same shape and differ by movement.
+
+## Five regions
+
+| region | dim | tracks |
+|---|---|---|
+| `hands_one` | 63 | one hand, 21 joints |
+| `hands_two` | 126 | both hands |
+| `pose` | 132 | full body, 33 points |
+| `legs` | 32 | lower body, 8 points |
+| `full` | 258 | body + both hands |
+
+The region must match how the project was captured — `gesto` checks the feature
+dimension and tells you if it doesn't.
+
+## Command line
+
+```bash
+# what's in this dataset?
+gesto inspect ./gesto_projects/signs
+
+# train
+gesto train static hands_one ./gesto_projects/signs
+gesto train sequence pose ./gesto_projects/jogging --seq-len 30
+
+# detect (newest model by default)
+gesto detect static hands_one
+gesto detect sequence pose --source clip.mp4
+gesto detect static hands_one --version 2
+
+# what have I trained?
+gesto list
+```
+
+## Python
+
+```python
+import gesto
+
+run = gesto.train("./gesto_projects/signs", region="hands_one", mode="static")
+gesto.detect("static", "hands_one")
+```
+
+Or drive a model yourself:
+
+```python
+from gesto.detect import Predictor
+
+predictor = Predictor.load("static", "hands_one")
+vector = predictor.features(holistic_result)   # extract + normalize
+probs = predictor.predict(vector)
+```
+
+## Where models go
+
+Everything lands under one `artifacts/` folder, split by mode then region.
+Training never overwrites an earlier run — it versions:
+
+```
+artifacts/
+    static/
+        hands_one/          model.keras, labels.json
+        hands_one_2/        the next run
+        pose/
+    sequence/
+        pose/
+        pose_2/
+```
+
+`gesto detect static pose` picks the newest version; `--version 1` picks a
+specific one.
+
+## Matching your capture
+
+Predictions are only correct when detection feeds the model the same kind of
+vector it trained on. `gesto` mirrors Gesto Labeller exactly:
+
+- **the same engine** — MediaPipe Holistic, same confidence settings
+- **the same landmark order** — including one-hand mode preferring the right
+  hand and falling back to the left
+- **the same normalization** — translation/scale-invariant, verified identical
+- **the same mirroring** — webcam frames are flipped, video files are not
+
+If you captured with Gesto's **Normalise** unchecked, pass `--raw` when training
+so detection knows to skip it.
+
+## Getting good results
+
+- **Balance your classes.** Similar sample counts per class; `gesto` applies
+  class weights but balanced data is better.
+- **Enough samples.** ~20–30 static frames per class, or ~15–30 sequences.
+  Small datasets automatically get a lighter model, since an oversized network
+  on little data overfits and collapses to predicting one class.
+- **Consistent clip length** for sequence mode — set "Max frames" in Gesto
+  Labeller so every capture is the same length.
+
+Run `gesto inspect <project>` to check all of this before training.
+
+## Requirements
+
+Python 3.9+, TensorFlow, OpenCV, MediaPipe, NumPy — all installed with the
+package.
+
+## License
+
+MIT

gesto-0.1.0/README.md

@@ -0,0 +1,127 @@
+# gesto
+
+Train and run gesture recognition models from [Gesto Labeller](https://github.com/TheMadrasTechie) datasets.
+
+Point it at a project folder, pick a mode and a region, and it handles the rest —
+loading, training, versioned model storage, and live detection that matches how
+the data was captured.
+
+```bash
+pip install gesto
+```
+
+## Two modes
+
+| mode | the gesture is… | model | example |
+|---|---|---|---|
+| `static` | a held shape or posture | Dense network | thumbs up, alphabet letters, a stance |
+| `sequence` | a motion over time | stacked LSTM | waving, clapping, jogging |
+
+Static needs far less data (every captured frame is a training sample) and
+predicts instantly with no warm-up. Reach for `sequence` only when two gestures
+share the same shape and differ by movement.
+
+## Five regions
+
+| region | dim | tracks |
+|---|---|---|
+| `hands_one` | 63 | one hand, 21 joints |
+| `hands_two` | 126 | both hands |
+| `pose` | 132 | full body, 33 points |
+| `legs` | 32 | lower body, 8 points |
+| `full` | 258 | body + both hands |
+
+The region must match how the project was captured — `gesto` checks the feature
+dimension and tells you if it doesn't.
+
+## Command line
+
+```bash
+# what's in this dataset?
+gesto inspect ./gesto_projects/signs
+
+# train
+gesto train static hands_one ./gesto_projects/signs
+gesto train sequence pose ./gesto_projects/jogging --seq-len 30
+
+# detect (newest model by default)
+gesto detect static hands_one
+gesto detect sequence pose --source clip.mp4
+gesto detect static hands_one --version 2
+
+# what have I trained?
+gesto list
+```
+
+## Python
+
+```python
+import gesto
+
+run = gesto.train("./gesto_projects/signs", region="hands_one", mode="static")
+gesto.detect("static", "hands_one")
+```
+
+Or drive a model yourself:
+
+```python
+from gesto.detect import Predictor
+
+predictor = Predictor.load("static", "hands_one")
+vector = predictor.features(holistic_result)   # extract + normalize
+probs = predictor.predict(vector)
+```
+
+## Where models go
+
+Everything lands under one `artifacts/` folder, split by mode then region.
+Training never overwrites an earlier run — it versions:
+
+```
+artifacts/
+    static/
+        hands_one/          model.keras, labels.json
+        hands_one_2/        the next run
+        pose/
+    sequence/
+        pose/
+        pose_2/
+```
+
+`gesto detect static pose` picks the newest version; `--version 1` picks a
+specific one.
+
+## Matching your capture
+
+Predictions are only correct when detection feeds the model the same kind of
+vector it trained on. `gesto` mirrors Gesto Labeller exactly:
+
+- **the same engine** — MediaPipe Holistic, same confidence settings
+- **the same landmark order** — including one-hand mode preferring the right
+  hand and falling back to the left
+- **the same normalization** — translation/scale-invariant, verified identical
+- **the same mirroring** — webcam frames are flipped, video files are not
+
+If you captured with Gesto's **Normalise** unchecked, pass `--raw` when training
+so detection knows to skip it.
+
+## Getting good results
+
+- **Balance your classes.** Similar sample counts per class; `gesto` applies
+  class weights but balanced data is better.
+- **Enough samples.** ~20–30 static frames per class, or ~15–30 sequences.
+  Small datasets automatically get a lighter model, since an oversized network
+  on little data overfits and collapses to predicting one class.
+- **Consistent clip length** for sequence mode — set "Max frames" in Gesto
+  Labeller so every capture is the same length.
+
+Run `gesto inspect <project>` to check all of this before training.
+
+## Requirements
+
+Python 3.9+, TensorFlow, OpenCV, MediaPipe, NumPy — all installed with the
+package.
+
+## License
+
+MIT

gesto-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gesto"
+version = "0.1.0"
+description = "Train and run gesture recognition models from Gesto Labeller datasets"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Sundar Balamurugan" }]
+keywords = [
+    "gesture-recognition",
+    "mediapipe",
+    "pose-estimation",
+    "computer-vision",
+    "lstm",
+    "sign-language",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "numpy>=1.23",
+    "tensorflow>=2.15",
+    "opencv-python>=4.8",
+    "mediapipe>=0.10",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/TheMadrasTechie/gesto"
+Issues = "https://github.com/TheMadrasTechie/gesto/issues"
+
+[project.scripts]
+gesto = "gesto.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gesto-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gesto-0.1.0/src/gesto/__init__.py

@@ -0,0 +1,71 @@
+"""
+gesto — train and run gesture recognition models from Gesto Labeller datasets.
+
+Two model types:
+    static    single frame; the gesture is a held shape or posture
+    sequence  a window of frames; the gesture is a motion
+
+Five regions: hands_one, hands_two, pose, legs, full.
+
+Quick start (Python):
+
+    import gesto
+
+    run = gesto.train("./gesto_projects/signs", region="hands_one",
+                      mode="static")
+    gesto.detect("static", "hands_one")
+
+Quick start (command line):
+
+    gesto train static hands_one ./gesto_projects/signs
+    gesto detect static hands_one
+
+Models are saved under artifacts/<mode>/<region>/, versioned so a new run never
+overwrites an old one (pose, pose_2, pose_3, ...).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .regions import REGION_KEYS, REGION_INFO, feature_dim, extract, normalize
+
+__all__ = [
+    "__version__",
+    "REGION_KEYS",
+    "REGION_INFO",
+    "feature_dim",
+    "extract",
+    "normalize",
+    "train",
+    "detect",
+    "Predictor",
+    "artifacts",
+    "data",
+]
+
+
+def train(project_dir, region: str, mode: str = "static", **kwargs):
+    """Train a model. See gesto.train.train for the full signature."""
+    from .train import train as _train
+    return _train(project_dir, region, mode, **kwargs)
+
+
+def detect(mode: str, region: str, **kwargs):
+    """Run live detection. See gesto.detect.run for the full signature."""
+    from .detect import run as _run
+    return _run(mode, region, **kwargs)
+
+
+def Predictor(*args, **kwargs):  # noqa: N802 - re-exported class-like helper
+    """Load a trained model for programmatic use."""
+    from .detect import Predictor as _Predictor
+    return _Predictor(*args, **kwargs)
+
+
+def __getattr__(name: str):
+    # lazy submodule access: gesto.artifacts / gesto.data without import cost
+    if name in ("artifacts", "data"):
+        import importlib
+        return importlib.import_module(f".{name}", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

gesto-0.1.0/src/gesto/artifacts.py

@@ -0,0 +1,132 @@
+"""
+Artifact storage.
+
+Everything a training run produces lives under one root folder, split by mode
+and then region:
+
+    artifacts/
+        static/
+            pose/            <- first static pose model
+                model.keras
+                labels.json
+            pose_2/          <- next one doesn't overwrite; it's versioned
+            hands_one/
+        sequence/
+            pose/
+            legs/
+
+`new_run()` never overwrites: if `artifacts/static/pose` exists it returns
+`pose_2`, then `pose_3`, and so on. `resolve()` finds the newest version when
+you don't name one explicitly, so `gesto detect static pose` picks up the model
+you just trained.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+MODES = ("static", "sequence")
+DEFAULT_ROOT = "artifacts"
+
+_VERSION_RE = re.compile(r"^(?P<base>.+?)(?:_(?P<n>\d+))?$")
+
+
+def _check_mode(mode: str) -> None:
+    if mode not in MODES:
+        raise ValueError(f"mode must be one of {MODES}, got {mode!r}")
+
+
+def mode_dir(root: str | Path, mode: str) -> Path:
+    _check_mode(mode)
+    return Path(root) / mode
+
+
+def _version_of(name: str, base: str) -> int:
+    """Return the version number a folder name represents for `base`.
+
+    "pose" -> 1, "pose_2" -> 2, anything else -> 0 (not a version of base).
+    """
+    m = _VERSION_RE.match(name)
+    if not m or m.group("base") != base:
+        return 0
+    n = m.group("n")
+    return int(n) if n else 1
+
+
+def list_runs(root: str | Path, mode: str, region: str) -> list[Path]:
+    """Every run folder for this mode+region, oldest version first."""
+    d = mode_dir(root, mode)
+    if not d.exists():
+        return []
+    runs = [(p, _version_of(p.name, region)) for p in d.iterdir() if p.is_dir()]
+    runs = [(p, v) for p, v in runs if v > 0]
+    runs.sort(key=lambda t: t[1])
+    return [p for p, _ in runs]
+
+
+def new_run(root: str | Path, mode: str, region: str) -> Path:
+    """Create and return a fresh run folder, versioning instead of overwriting.
+
+    First call -> artifacts/<mode>/<region>
+    Later calls -> artifacts/<mode>/<region>_2, _3, ...
+    """
+    d = mode_dir(root, mode)
+    d.mkdir(parents=True, exist_ok=True)
+    existing = list_runs(root, mode, region)
+    if not existing:
+        run = d / region
+    else:
+        highest = max(_version_of(p.name, region) for p in existing)
+        run = d / f"{region}_{highest + 1}"
+    run.mkdir(parents=True, exist_ok=False)
+    return run
+
+
+def resolve(root: str | Path, mode: str, region: str,
+            version: int | str | None = None) -> Path:
+    """Locate an existing run folder.
+
+    version=None  -> newest version
+    version=2     -> artifacts/<mode>/<region>_2
+    version="pose_2" (a folder name) -> that exact folder
+    """
+    d = mode_dir(root, mode)
+    if isinstance(version, str) and not version.isdigit():
+        run = d / version
+        if not run.exists():
+            raise FileNotFoundError(f"No such run: {run}")
+        return run
+
+    runs = list_runs(root, mode, region)
+    if not runs:
+        raise FileNotFoundError(
+            f"No {mode} model for region {region!r} under {d}. "
+            f"Train one first: gesto train {mode} {region} <project_dir>")
+    if version is None:
+        return runs[-1]                      # newest
+    want = int(version)
+    for p in runs:
+        if _version_of(p.name, region) == want:
+            return p
+    have = ", ".join(p.name for p in runs)
+    raise FileNotFoundError(
+        f"No version {want} for {mode}/{region}. Available: {have}")
+
+
+def save_meta(run: Path, meta: dict) -> Path:
+    path = Path(run) / "labels.json"
+    path.write_text(json.dumps(meta, indent=2), encoding="utf-8")
+    return path
+
+
+def load_meta(run: Path) -> dict:
+    path = Path(run) / "labels.json"
+    if not path.exists():
+        raise FileNotFoundError(f"No labels.json in {run}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def model_path(run: Path) -> Path:
+    return Path(run) / "model.keras"