fasthands 0.1.0__tar.gz

fasthands-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.venv*/
+models/extracted/
+output_*
+dist/

fasthands-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Vimal Mollyn
+
+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.
+
+---
+
+The bundled hand detection and hand landmark model weights are derived from
+Google's MediaPipe hand_landmarker.task models, licensed under the Apache
+License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0).
+Copyright Google LLC.

fasthands-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: fasthands
+Version: 0.1.0
+Summary: Fastest MediaPipe-compatible hand tracker: hand landmarks on the Apple Neural Engine at 0.7 ms/frame
+Project-URL: Repository, https://github.com/VimalMollyn/fasthands
+Author-email: Vimal Mollyn <vmollyn@andrew.cmu.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coreml,hand-landmarks,hand-tracking,mediapipe,neural-engine
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Requires-Dist: coremltools>=8.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python>=4.8
+Description-Content-Type: text/markdown
+
+# fasthands
+
+**The fastest MediaPipe-compatible hand tracker.** MediaPipe Hands' official
+models running on the Apple Neural Engine via CoreML — **0.7 ms per tracked
+frame** on Apple Silicon, ~5× faster than MediaPipe itself, with a faithful
+port of the full HandLandmarker pipeline (SSD anchors, weighted NMS, ROI
+tracking, landmark projection, deduplication).
+
+macOS / Apple Silicon only.
+
+## Install
+
+```sh
+pip install fasthands
+```
+
+## Use
+
+```python
+import cv2
+import fasthands
+
+tracker = fasthands.load(num_hands=1)
+
+image = cv2.cvtColor(cv2.imread("hand.jpg"), cv2.COLOR_BGR2RGB)
+hands = tracker(image)                 # single image
+# hands = tracker.detect_video(frame)  # video: tracks between frames, ~0.7 ms
+
+for hand in hands:
+    print(hand["handedness"], hand["score"])
+    print(hand["landmarks"])        # 21 x (x, y, z), normalized image coords
+    print(hand["world_landmarks"])  # 21 x (x, y, z), meters, hand-centered
+```
+
+Or from the command line:
+
+```sh
+fasthands photo.jpg --out annotated.jpg
+fasthands-webcam --mirror     # live demo with FPS overlay
+```
+
+## Speed (Apple M4, 540×720 frame, one hand)
+
+| | tracking | detect + track |
+|---|---|---|
+| **fasthands (ANE)** | **0.7 ms** | **1.9 ms** |
+| mediapipe (XNNPACK CPU) | 3.3 ms | 8.7 ms |
+
+Landmarks agree with MediaPipe to ~1e-3 (Neural Engine fp16); the pipeline
+logic itself is verified to MediaPipe's own float32 reproducibility floor.
+
+## How
+
+The `hand_landmarker.task` models are converted to CoreML, and every MediaPipe
+calculator in the pipeline (anchors, decode, weighted NMS, rect transforms,
+rotated crops, projections, VIDEO-mode ROI tracking, dedup) is reimplemented
+in numpy with float32 op-order fidelity. Model weights © Google, Apache 2.0.
+
+Source, the PyTorch reference implementation, and the full verification
+harness: https://github.com/VimalMollyn/fasthands

fasthands-0.1.0/PYPI_README.md

@@ -0,0 +1,60 @@
+# fasthands
+
+**The fastest MediaPipe-compatible hand tracker.** MediaPipe Hands' official
+models running on the Apple Neural Engine via CoreML — **0.7 ms per tracked
+frame** on Apple Silicon, ~5× faster than MediaPipe itself, with a faithful
+port of the full HandLandmarker pipeline (SSD anchors, weighted NMS, ROI
+tracking, landmark projection, deduplication).
+
+macOS / Apple Silicon only.
+
+## Install
+
+```sh
+pip install fasthands
+```
+
+## Use
+
+```python
+import cv2
+import fasthands
+
+tracker = fasthands.load(num_hands=1)
+
+image = cv2.cvtColor(cv2.imread("hand.jpg"), cv2.COLOR_BGR2RGB)
+hands = tracker(image)                 # single image
+# hands = tracker.detect_video(frame)  # video: tracks between frames, ~0.7 ms
+
+for hand in hands:
+    print(hand["handedness"], hand["score"])
+    print(hand["landmarks"])        # 21 x (x, y, z), normalized image coords
+    print(hand["world_landmarks"])  # 21 x (x, y, z), meters, hand-centered
+```
+
+Or from the command line:
+
+```sh
+fasthands photo.jpg --out annotated.jpg
+fasthands-webcam --mirror     # live demo with FPS overlay
+```
+
+## Speed (Apple M4, 540×720 frame, one hand)
+
+| | tracking | detect + track |
+|---|---|---|
+| **fasthands (ANE)** | **0.7 ms** | **1.9 ms** |
+| mediapipe (XNNPACK CPU) | 3.3 ms | 8.7 ms |
+
+Landmarks agree with MediaPipe to ~1e-3 (Neural Engine fp16); the pipeline
+logic itself is verified to MediaPipe's own float32 reproducibility floor.
+
+## How
+
+The `hand_landmarker.task` models are converted to CoreML, and every MediaPipe
+calculator in the pipeline (anchors, decode, weighted NMS, rect transforms,
+rotated crops, projections, VIDEO-mode ROI tracking, dedup) is reimplemented
+in numpy with float32 op-order fidelity. Model weights © Google, Apache 2.0.
+
+Source, the PyTorch reference implementation, and the full verification
+harness: https://github.com/VimalMollyn/fasthands

fasthands-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "fasthands"
+version = "0.1.0"
+description = "Fastest MediaPipe-compatible hand tracker: hand landmarks on the Apple Neural Engine at 0.7 ms/frame"
+readme = "PYPI_README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Vimal Mollyn", email = "vmollyn@andrew.cmu.edu" }]
+keywords = ["hand-tracking", "mediapipe", "coreml", "neural-engine", "hand-landmarks"]
+classifiers = [
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "coremltools>=8.0",
+    "numpy>=1.24",
+    "opencv-python>=4.8",
+]
+
+[project.urls]
+Repository = "https://github.com/VimalMollyn/fasthands"
+
+[project.scripts]
+fasthands = "fasthands.cli:main"
+fasthands-webcam = "fasthands.cli:webcam"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fasthands"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "PYPI_README.md", "LICENSE"]
+
+[dependency-groups]
+# research / verification tooling for this repo, not shipped with the package
+dev = [
+    "mediapipe>=0.10.35",
+    "torch>=2.12.0",
+    "ai-edge-litert>=2.1.5",
+    "tflite>=2.18.0",
+    "pytest>=8",
+]

fasthands-0.1.0/src/fasthands/__init__.py

@@ -0,0 +1,17 @@
+"""fasthands — the fastest MediaPipe-compatible hand tracker.
+
+MediaPipe Hands' models running on the Apple Neural Engine via CoreML,
+with a faithful port of the HandLandmarker pipeline. ~0.7 ms per tracked
+frame on Apple Silicon (~5x faster than MediaPipe itself).
+
+    import fasthands
+    tracker = fasthands.load(num_hands=1)
+    hands = tracker.detect_video(rgb_frame)   # tracking (video) mode
+    hands = tracker(rgb_image)                # single-image mode
+"""
+
+from .coreml import load
+from .pipeline import HAND_CONNECTIONS, HandLandmarker, draw
+
+__version__ = "0.1.0"
+__all__ = ["load", "HandLandmarker", "HAND_CONNECTIONS", "draw", "__version__"]

fasthands-0.1.0/src/fasthands/cli.py

@@ -0,0 +1,131 @@
+"""Command-line entry points: `fasthands <image>` and `fasthands-webcam`."""
+
+import argparse
+import json
+import threading
+import time
+
+import cv2
+
+from . import load
+from .pipeline import draw
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="fasthands: hand landmarks on the Neural Engine")
+    parser.add_argument("image", help="path to input image")
+    parser.add_argument("--out", default=None, help="annotated output image path")
+    parser.add_argument("--json", dest="json_path", default=None,
+                        help="write landmarks as JSON")
+    parser.add_argument("--num-hands", type=int, default=2)
+    parser.add_argument("--compute-units", default="ALL",
+                        choices=["ALL", "CPU_AND_NE", "CPU_AND_GPU", "CPU_ONLY"])
+    args = parser.parse_args()
+
+    image_bgr = cv2.imread(args.image)
+    if image_bgr is None:
+        raise SystemExit(f"could not read image: {args.image}")
+    tracker = load(num_hands=args.num_hands, compute_units=args.compute_units)
+    hands = tracker(cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB))
+
+    print(f"detected {len(hands)} hand(s)")
+    for i, hand in enumerate(hands):
+        print(f"\nhand {i}: {hand['handedness']} (score {hand['score']:.4f})")
+        for j, (x, y, z) in enumerate(hand["landmarks"]):
+            print(f"  lm[{j:2d}] x={x:.6f} y={y:.6f} z={z:.6f}")
+
+    if args.json_path:
+        dump = [{
+            "handedness": h["handedness"], "score": h["score"],
+            "landmarks": [{"x": float(x), "y": float(y), "z": float(z)}
+                          for x, y, z in h["landmarks"]],
+            "world_landmarks": [{"x": float(x), "y": float(y), "z": float(z)}
+                                for x, y, z in h["world_landmarks"]],
+        } for h in hands]
+        with open(args.json_path, "w") as f:
+            json.dump(dump, f, indent=2)
+        print(f"\nlandmarks written to {args.json_path}")
+    if args.out:
+        cv2.imwrite(args.out, draw(image_bgr, hands))
+        print(f"annotated image written to {args.out}")
+
+
+class _Camera:
+    """Threaded capture: always serves the latest frame."""
+
+    def __init__(self, index):
+        self.cap = cv2.VideoCapture(index)
+        if not self.cap.isOpened():
+            raise SystemExit(f"could not open camera {index}")
+        self.frame = None
+        self.ok = True
+        self.lock = threading.Lock()
+        threading.Thread(target=self._loop, daemon=True).start()
+        while self.ok and self.frame is None:
+            time.sleep(0.01)
+
+    def _loop(self):
+        while self.ok:
+            ok, frame = self.cap.read()
+            if not ok:
+                self.ok = False
+                break
+            with self.lock:
+                self.frame = frame
+
+    def read(self):
+        with self.lock:
+            return self.ok, None if self.frame is None else self.frame.copy()
+
+    def release(self):
+        self.ok = False
+        self.cap.release()
+
+
+def webcam():
+    parser = argparse.ArgumentParser(description="fasthands live webcam demo")
+    parser.add_argument("--camera", type=int, default=0)
+    parser.add_argument("--mirror", action="store_true", help="selfie view")
+    parser.add_argument("--num-hands", type=int, default=1)
+    parser.add_argument("--compute-units", default="ALL",
+                        choices=["ALL", "CPU_AND_NE", "CPU_AND_GPU", "CPU_ONLY"])
+    args = parser.parse_args()
+
+    tracker = load(num_hands=args.num_hands, compute_units=args.compute_units)
+    cap = _Camera(args.camera)
+
+    fps, infer_ms = 0.0, 0.0
+    prev = time.perf_counter()
+    while True:
+        ok, frame = cap.read()
+        if not ok:
+            break
+        if args.mirror:
+            frame = cv2.flip(frame, 1)
+
+        t0 = time.perf_counter()
+        hands = tracker.detect_video(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
+        infer_ms = 0.9 * infer_ms + 0.1 * (time.perf_counter() - t0) * 1000
+        frame = draw(frame, hands)
+        for hand in hands:
+            x, y = hand["landmarks"][0][:2]
+            cv2.putText(frame, f"{hand['handedness']} {hand['score']:.2f}",
+                        (int(x * frame.shape[1]) - 30, int(y * frame.shape[0]) + 30),
+                        cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 0), 2)
+
+        now = time.perf_counter()
+        fps = 0.9 * fps + 0.1 / (now - prev) if fps else 1.0 / (now - prev)
+        prev = now
+        cv2.putText(frame, f"{fps:.1f} FPS  {infer_ms:.1f} ms", (10, 30),
+                    cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 255), 2)
+        cv2.imshow("fasthands", frame)
+        if cv2.waitKey(1) & 0xFF in (ord("q"), 27):
+            break
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    main()

fasthands-0.1.0/src/fasthands/coreml.py

@@ -0,0 +1,40 @@
+"""CoreML inference backend (Neural Engine capable) with bundled models."""
+
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from .pipeline import HandLandmarker
+
+MODELS_DIR = Path(__file__).parent / "models"
+
+
+class CoreMLBackend:
+    def __init__(self, path, compute_units="ALL"):
+        if sys.platform != "darwin":
+            raise RuntimeError("fasthands requires macOS (CoreML)")
+        import coremltools as ct
+        self.model = ct.models.MLModel(
+            str(path), compute_units=ct.ComputeUnit[compute_units])
+        spec = self.model.get_spec()
+        self.output_names = [o.name for o in spec.description.output]
+
+    def __call__(self, x: np.ndarray):
+        out = self.model.predict({"image": x})
+        return [out[n] for n in self.output_names]
+
+
+def load(num_hands: int = 2, compute_units: str = "ALL",
+         models_dir=MODELS_DIR) -> HandLandmarker:
+    """Create a HandLandmarker running on CoreML.
+
+    compute_units: ALL (Neural Engine + GPU + CPU), CPU_AND_NE, CPU_AND_GPU,
+    or CPU_ONLY.
+    """
+    models_dir = Path(models_dir)
+    return HandLandmarker(
+        CoreMLBackend(models_dir / "hand_detector.mlpackage", compute_units),
+        CoreMLBackend(models_dir / "hand_landmarks_detector.mlpackage", compute_units),
+        num_hands=num_hands,
+    )

fasthands-0.1.0/src/fasthands/models/hand_detector.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "7CBC671B-4858-4DC4-80A9-AA56D588F465": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        },
+        "95186DCA-2FC9-41F8-B09F-1A3EF04C9006": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        }
+    },
+    "rootModelIdentifier": "7CBC671B-4858-4DC4-80A9-AA56D588F465"
+}

fasthands-0.1.0/src/fasthands/models/hand_landmarks_detector.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "4B1E732F-140B-42D1-A2E5-4377545D8444": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        },
+        "DFF8F2DB-240E-491C-8B01-E606ED9B5740": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        }
+    },
+    "rootModelIdentifier": "4B1E732F-140B-42D1-A2E5-4377545D8444"
+}

fasthands-0.1.0/src/fasthands/pipeline.py

@@ -0,0 +1,457 @@
+"""MediaPipe HandLandmarker pipeline, faithfully ported (numpy + OpenCV only).
+
+Mirrors MediaPipe's calculators in float32 operation order: SSD anchors,
+detection decode, weighted NMS (in tensor space), detection projection,
+rect transformation, rotated-rect cropping, landmark projection, VIDEO-mode
+tracking (landmarks -> next-frame ROI) and hand deduplication.
+
+Inference backends are injected: any callable taking a float32 NHWC array
+[1, H, W, 3] in [0, 1] and returning the model's output arrays in order.
+"""
+
+import math
+
+import cv2
+import numpy as np
+
+F = np.float32
+
+# ----------------------------------------------------------------------------
+# Constants from mediapipe/tasks/cc/vision/hand_detector/hand_detector_graph.cc
+# and hand_landmarker/hand_landmarks_detector_graph.cc
+# ----------------------------------------------------------------------------
+DETECT_SIZE = 192
+LANDMARK_SIZE = 224
+NUM_KEYPOINTS = 7
+MIN_DETECTION_CONFIDENCE = F(0.5)
+MIN_HAND_PRESENCE_CONFIDENCE = F(0.5)
+NMS_THRESHOLD = F(0.3)
+SCORE_CLIPPING_THRESH = F(100.0)
+RECT_SCALE = F(2.6)          # RectTransformationCalculator scale_x/scale_y
+RECT_SHIFT_Y = F(-0.5)       # RectTransformationCalculator shift_y
+LANDMARKS_NORMALIZE_Z = 0.4  # TensorsToLandmarksCalculator normalize_z
+# NOTE: the tasks HandDetectorGraph sets rotation_vector_target_angle(90) on
+# DetectionsToRectsCalculator -- that proto field is in RADIANS (the _degrees
+# variant is a separate field), so the effective target angle really is
+# 90 rad (= 2.0354 rad mod 2pi), not pi/2. We reproduce that behavior.
+ROTATION_TARGET_ANGLE = 90.0
+
+HAND_CONNECTIONS = [
+    (0, 1), (1, 2), (2, 3), (3, 4),
+    (0, 5), (5, 6), (6, 7), (7, 8),
+    (5, 9), (9, 10), (10, 11), (11, 12),
+    (9, 13), (13, 14), (14, 15), (15, 16),
+    (13, 17), (17, 18), (18, 19), (19, 20),
+    (0, 17),
+]
+
+
+# ----------------------------------------------------------------------------
+# SSD anchors — mediapipe/calculators/tflite/ssd_anchors_calculator.cc with the
+# hand-detector config (num_layers=4, strides 8,16,16,16, scales .1484375-.75)
+# ----------------------------------------------------------------------------
+def generate_anchors() -> np.ndarray:
+    num_layers = 4
+    strides = [8, 16, 16, 16]
+    anchors = []
+    layer_id = 0
+    while layer_id < num_layers:
+        scales = []
+        last = layer_id
+        while last < num_layers and strides[last] == strides[layer_id]:
+            scales.append(0)  # aspect_ratio 1.0 anchor
+            scales.append(0)  # interpolated anchor (same center)
+            last += 1
+        fm = math.ceil(DETECT_SIZE / strides[layer_id])
+        for y in range(fm):
+            for x in range(fm):
+                for _ in scales:  # fixed_anchor_size: w = h = 1.0
+                    anchors.append((F(x + 0.5) / F(fm), F(y + 0.5) / F(fm), 1.0, 1.0))
+        layer_id = last
+    return np.array(anchors, dtype=np.float32)  # [2016, 4] cx, cy, w, h
+
+
+# ----------------------------------------------------------------------------
+# ImageToTensorCalculator (OpenCV converter): rotated sub-rect -> square crop.
+# Identical cv2 calls (boxPoints + getPerspectiveTransform + warpPerspective
+# on uint8, then *1/255f like cv::Mat::convertTo with a float scale).
+# ----------------------------------------------------------------------------
+def crop_rotated_rect(image_rgb, cx, cy, w, h, rotation_rad, dst_size, border):
+    angle_deg = F(np.float64(F(rotation_rad) * F(180.0)) / math.pi)
+    src = cv2.boxPoints(((float(cx), float(cy)), (float(w), float(h)), float(angle_deg)))
+    dst = np.array(
+        [[0, dst_size], [0, 0], [dst_size, 0], [dst_size, dst_size]], dtype=np.float32
+    )
+    m = cv2.getPerspectiveTransform(src.astype(np.float32), dst)
+    crop = cv2.warpPerspective(
+        image_rgb, m, (dst_size, dst_size), flags=cv2.INTER_LINEAR, borderMode=border
+    )
+    return crop.astype(np.float32) * F(1.0 / 255.0)
+
+
+def normalize_radians(angle: float) -> float:
+    return angle - 2 * math.pi * math.floor((angle + math.pi) / (2 * math.pi))
+
+
+def compute_rotation(x0, y0, x1, y1) -> F:
+    """DetectionsToRectsCalculator::ComputeRotation in float32, exactly as the
+    C++ does it: rot = NormalizeRadians(90.f - atan2f(-(y1-y0), x1-x0))."""
+    a = F(ROTATION_TARGET_ANGLE) - F(math.atan2(-(F(y1) - F(y0)), F(x1) - F(x0)))
+    return F(normalize_radians(float(a)))
+
+
+# ----------------------------------------------------------------------------
+# TensorsToDetectionsCalculator (decode + sigmoid scores), in tensor space
+# ----------------------------------------------------------------------------
+def decode_detections(raw_boxes, raw_scores, anchors):
+    """raw_boxes [2016,18], raw_scores [2016,1] float32 -> list of dicts
+    {xmin, ymin, w, h, kp[7][2], score} in the 192x192 tensor space."""
+    logits = np.clip(raw_scores.reshape(-1), -SCORE_CLIPPING_THRESH, SCORE_CLIPPING_THRESH)
+    # sigmoid in float64, rounded once to float32 (= correctly-rounded expf path)
+    scores = (1.0 / (1.0 + np.exp(-logits.astype(np.float64)))).astype(np.float32)
+    scale = F(DETECT_SIZE)
+    rb = raw_boxes
+    xc = rb[:, 0] / scale * anchors[:, 2] + anchors[:, 0]
+    yc = rb[:, 1] / scale * anchors[:, 3] + anchors[:, 1]
+    w = rb[:, 2] / scale * anchors[:, 2]
+    h = rb[:, 3] / scale * anchors[:, 3]
+    xmin = xc - w / F(2.0)
+    ymin = yc - h / F(2.0)
+    # detection proto stores xmin/ymin/width/height
+    width = (xc + w / F(2.0)) - xmin
+    height = (yc + h / F(2.0)) - ymin
+    kx = rb[:, 4:4 + NUM_KEYPOINTS * 2:2] / scale * anchors[:, 2:3] + anchors[:, 0:1]
+    ky = rb[:, 5:5 + NUM_KEYPOINTS * 2:2] / scale * anchors[:, 3:4] + anchors[:, 1:2]
+    dets = []
+    for i in np.nonzero(scores >= MIN_DETECTION_CONFIDENCE)[0]:
+        dets.append({
+            "xmin": xmin[i], "ymin": ymin[i], "w": width[i], "h": height[i],
+            "kp": [(kx[i, k], ky[i, k]) for k in range(NUM_KEYPOINTS)],
+            "score": scores[i],
+        })
+    return dets
+
+
+# ----------------------------------------------------------------------------
+# NonMaxSuppressionCalculator, algorithm=WEIGHTED, overlap=IoU, thresh=0.3 —
+# float32 accumulation in the same order as the C++ implementation.
+# ----------------------------------------------------------------------------
+def iou(a, b):
+    xa, ya = max(a["xmin"], b["xmin"]), max(a["ymin"], b["ymin"])
+    xb = min(a["xmin"] + a["w"], b["xmin"] + b["w"])
+    yb = min(a["ymin"] + a["h"], b["ymin"] + b["h"])
+    if xb <= xa or yb <= ya:
+        return F(0.0)
+    inter = (xb - xa) * (yb - ya)
+    union = a["w"] * a["h"] + b["w"] * b["h"] - inter
+    return inter / union
+
+
+def weighted_nms(dets):
+    remained = sorted(dets, key=lambda d: -d["score"])
+    out = []
+    while remained:
+        top = remained[0]
+        sims = [iou(d, top) for d in remained]
+        candidates = [d for d, s in zip(remained, sims) if s > NMS_THRESHOLD]
+        remained = [d for d, s in zip(remained, sims) if not s > NMS_THRESHOLD]
+        merged = dict(top)
+        if candidates:
+            w_xmin = w_ymin = w_xmax = w_ymax = F(0.0)
+            kp_acc = [[F(0.0), F(0.0)] for _ in range(NUM_KEYPOINTS)]
+            total = F(0.0)
+            for c in candidates:
+                total = total + c["score"]
+                w_xmin = w_xmin + c["xmin"] * c["score"]
+                w_ymin = w_ymin + c["ymin"] * c["score"]
+                w_xmax = w_xmax + (c["xmin"] + c["w"]) * c["score"]
+                w_ymax = w_ymax + (c["ymin"] + c["h"]) * c["score"]
+                for k in range(NUM_KEYPOINTS):
+                    kp_acc[k][0] = kp_acc[k][0] + c["kp"][k][0] * c["score"]
+                    kp_acc[k][1] = kp_acc[k][1] + c["kp"][k][1] * c["score"]
+            merged["xmin"] = w_xmin / total
+            merged["ymin"] = w_ymin / total
+            merged["w"] = (w_xmax / total) - merged["xmin"]
+            merged["h"] = (w_ymax / total) - merged["ymin"]
+            merged["kp"] = [(kp_acc[k][0] / total, kp_acc[k][1] / total)
+                            for k in range(NUM_KEYPOINTS)]
+        out.append(merged)
+    return out
+
+
+# ----------------------------------------------------------------------------
+# DetectionProjectionCalculator: tensor space -> image space through the
+# float32 matrix produced by GetRotatedSubRectToRectTransformMatrix.
+# ----------------------------------------------------------------------------
+def letterbox_projection(iw, ih):
+    """Matrix for the full-image keep-aspect-ratio ROI (rotation 0)."""
+    side = F(max(iw, ih))
+    e, f = F(0.5) * F(iw), F(0.5) * F(ih)  # GetRoi: norm 0.5 * size
+    g, h = F(1.0) / F(iw), F(1.0) / F(ih)
+    m0 = side * F(1.0) * g                     # a*c*g, c=1, d=0
+    m3 = (F(-0.5) * side * F(1.0) + e) * g
+    m5 = side * F(1.0) * h
+    m7 = (F(-0.5) * side * F(1.0) + f) * h
+
+    def project(x, y):
+        return F(F(x * m0) + m3), F(F(y * m5) + m7)
+    return project
+
+
+def project_detection(det, project):
+    corners = [(det["xmin"], det["ymin"]),
+               (det["xmin"] + det["w"], det["ymin"]),
+               (det["xmin"] + det["w"], det["ymin"] + det["h"]),
+               (det["xmin"], det["ymin"] + det["h"])]
+    pts = [project(x, y) for x, y in corners]
+    xmin = min(p[0] for p in pts)
+    ymin = min(p[1] for p in pts)
+    return {
+        "xmin": xmin, "ymin": ymin,
+        "w": max(p[0] for p in pts) - xmin,
+        "h": max(p[1] for p in pts) - ymin,
+        "kp": [project(x, y) for x, y in det["kp"]],
+        "score": det["score"],
+    }
+
+
+# ----------------------------------------------------------------------------
+# HandLandmarksToRectCalculator + RectTransformation(2.0, shift_y -0.1,
+# square_long): next-frame ROI from the current landmarks (VIDEO mode).
+# ----------------------------------------------------------------------------
+PARTIAL_LANDMARK_IDS = [0, 1, 2, 3, 5, 6, 9, 10, 13, 14, 17, 18]
+TRACK_RECT_SCALE = F(2.0)
+TRACK_RECT_SHIFT_Y = F(-0.1)
+
+
+def rect_from_landmarks(landmarks, iw, ih):
+    lm = landmarks[PARTIAL_LANDMARK_IDS][:, :2]
+
+    # rotation: wrist -> mean of index/middle/ring MCPs, target pi/2
+    x0, y0 = lm[0, 0] * F(iw), lm[0, 1] * F(ih)
+    x1 = (lm[4, 0] + lm[8, 0]) / F(2.0)   # index, ring
+    y1 = (lm[4, 1] + lm[8, 1]) / F(2.0)
+    x1 = (x1 + lm[6, 0]) / F(2.0) * F(iw)  # middle
+    y1 = (y1 + lm[6, 1]) / F(2.0) * F(ih)
+    rotation = F(normalize_radians(
+        float(F(math.pi * 0.5) - F(math.atan2(-(y1 - y0), x1 - x0)))))
+    rev = -rotation
+
+    # bbox center, then bbox in the de-rotated frame
+    cax = (lm[:, 0].max() + lm[:, 0].min()) / F(2.0)
+    cay = (lm[:, 1].max() + lm[:, 1].min()) / F(2.0)
+    ox = (lm[:, 0] - cax) * F(iw)
+    oy = (lm[:, 1] - cay) * F(ih)
+    px = ox * F(math.cos(rev)) - oy * F(math.sin(rev))
+    py = ox * F(math.sin(rev)) + oy * F(math.cos(rev))
+    pcx = (px.max() + px.min()) / F(2.0)
+    pcy = (py.max() + py.min()) / F(2.0)
+    cx = (pcx * F(math.cos(rotation)) - pcy * F(math.sin(rotation)) + F(iw) * cax) / F(iw)
+    cy = (pcx * F(math.sin(rotation)) + pcy * F(math.cos(rotation)) + F(ih) * cay) / F(ih)
+    w = (px.max() - px.min()) / F(iw)
+    h = (py.max() - py.min()) / F(ih)
+
+    # RectTransformationCalculator: shift, square_long, scale 2.0
+    sin_a, cos_a = F(math.sin(rotation)), F(math.cos(rotation))
+    x_shift = (-F(ih) * h * TRACK_RECT_SHIFT_Y * sin_a) / F(iw)
+    y_shift = (F(ih) * h * TRACK_RECT_SHIFT_Y * cos_a) / F(ih)
+    cx, cy = cx + x_shift, cy + y_shift
+    long_side = max(w * F(iw), h * F(ih))
+    return (cx, cy, long_side / F(iw) * TRACK_RECT_SCALE,
+            long_side / F(ih) * TRACK_RECT_SCALE, rotation)
+
+
+def deduplicate_hands(hands, iw, ih):
+    """HandLandmarksDeduplicationCalculator: suppress a hand if >=10 of its 21
+    landmarks lie within 0.2 x baseline-palm-size of an already-retained hand
+    and their landmark bounding boxes overlap with IoU > 0.2."""
+    def baseline(lm):
+        px = lm[:, :2] * (iw, ih)
+        return max(np.linalg.norm(px[0] - px[5]), np.linalg.norm(px[5] - px[17]),
+                   np.linalg.norm(px[17] - px[0]))
+
+    def bbox_iou(a, b):
+        ax0, ay0 = a[:, 0].min(), a[:, 1].min(); ax1, ay1 = a[:, 0].max(), a[:, 1].max()
+        bx0, by0 = b[:, 0].min(), b[:, 1].min(); bx1, by1 = b[:, 0].max(), b[:, 1].max()
+        xa, ya, xb, yb = max(ax0, bx0), max(ay0, by0), min(ax1, bx1), min(ay1, by1)
+        if xb <= xa or yb <= ya:
+            return 0.0
+        inter = (xb - xa) * (yb - ya)
+        return inter / ((ax1-ax0)*(ay1-ay0) + (bx1-bx0)*(by1-by0) - inter)
+
+    kept = []
+    for h in hands:
+        lm = h["landmarks"]
+        dup = False
+        for k in kept:
+            klm = k["landmarks"]
+            thresh = max(baseline(lm), baseline(klm)) * 0.2
+            dists = np.linalg.norm((lm[:, :2] - klm[:, :2]) * (iw, ih), axis=1)
+            if (dists < thresh).sum() >= 10 and bbox_iou(lm, klm) > 0.2:
+                dup = True
+                break
+        if not dup:
+            kept.append(h)
+    return kept
+
+
+def _rect_iou(a, b):
+    """Axis-aligned IoU of two (cx, cy, w, h, rot) rects, for association."""
+    ax0, ay0 = a[0] - a[2] / 2, a[1] - a[3] / 2
+    bx0, by0 = b[0] - b[2] / 2, b[1] - b[3] / 2
+    xa, ya = max(ax0, bx0), max(ay0, by0)
+    xb, yb = min(ax0 + a[2], bx0 + b[2]), min(ay0 + a[3], by0 + b[3])
+    if xb <= xa or yb <= ya:
+        return 0.0
+    inter = (xb - xa) * (yb - ya)
+    return float(inter / (a[2] * a[3] + b[2] * b[3] - inter))
+
+
+# ----------------------------------------------------------------------------
+# Pipeline
+# ----------------------------------------------------------------------------
+class HandLandmarker:
+    """The HandLandmarker task graph with injectable inference backends.
+
+    detector / landmarker: callables mapping a float32 NHWC array [1,H,W,3]
+    in [0,1] to the model's raw output arrays (in model output order).
+    """
+
+    def __init__(self, detector, landmarker, num_hands=2):
+        self.detector = detector
+        self.landmarker = landmarker
+        self.anchors = generate_anchors()
+        self.num_hands = num_hands
+        self._tracked_rects = []  # VIDEO mode: ROIs carried to the next frame
+
+    def __call__(self, image_rgb: np.ndarray):
+        """IMAGE mode: palm detection + landmarks every call."""
+        ih, iw = image_rgb.shape[:2]
+        hands = []
+        for rect in self._detect_rects(image_rgb)[: self.num_hands]:
+            hand = self._landmarks(image_rgb, *rect)
+            if hand is not None:
+                hands.append(hand)
+        return deduplicate_hands(hands, iw, ih)
+
+    def detect_video(self, image_rgb: np.ndarray):
+        """VIDEO mode, like MediaPipe's: reuse the previous frame's
+        landmark-derived ROIs and only run palm detection when fewer than
+        num_hands hands are being tracked (HandAssociationCalculator logic:
+        tracked rects take precedence, new detections overlapping IoU>0.5
+        are dropped)."""
+        rects = list(self._tracked_rects)
+        if len(rects) < self.num_hands:
+            for r in self._detect_rects(image_rgb):
+                if all(_rect_iou(r, t) <= 0.5 for t in rects):
+                    rects.append(r)
+            rects = rects[: self.num_hands]
+
+        ih, iw = image_rgb.shape[:2]
+        hands = []
+        for rect in rects:
+            hand = self._landmarks(image_rgb, *rect)
+            if hand is not None:
+                hands.append(hand)
+        hands = deduplicate_hands(hands, iw, ih)
+        self._tracked_rects = [rect_from_landmarks(h["landmarks"], iw, ih)
+                               for h in hands]
+        return hands
+
+    def reset(self):
+        self._tracked_rects = []
+
+    def _detect_rects(self, image_rgb):
+        """Palm detection -> transformed hand ROI rects (cx, cy, w, h, rot)."""
+        ih, iw = image_rgb.shape[:2]
+
+        # --- palm detection on the letterboxed square ROI of the full image ---
+        side = max(iw, ih)
+        crop = crop_rotated_rect(image_rgb, F(0.5) * F(iw), F(0.5) * F(ih),
+                                 side, side, 0.0, DETECT_SIZE, cv2.BORDER_CONSTANT)
+        raw_boxes, raw_scores = self.detector(crop[None])
+        dets = decode_detections(raw_boxes[0], raw_scores[0], self.anchors)
+        dets = weighted_nms(dets)
+
+        # --- project detections to image space, convert to rects, transform ---
+        project = letterbox_projection(iw, ih)
+        rects = []
+        for det in [project_detection(d, project) for d in dets]:
+            # DetectionsToRectsCalculator
+            cx = det["xmin"] + det["w"] / F(2.0)
+            cy = det["ymin"] + det["h"] / F(2.0)
+            w, h = det["w"], det["h"]
+            rotation = compute_rotation(
+                det["kp"][0][0] * F(iw), det["kp"][0][1] * F(ih),   # wrist center
+                det["kp"][2][0] * F(iw), det["kp"][2][1] * F(ih),   # middle MCP
+            )
+            # RectTransformationCalculator: scale 2.6, shift_y -0.5, square_long
+            sin_a, cos_a = F(math.sin(rotation)), F(math.cos(rotation))
+            if float(rotation) == 0.0:
+                cx, cy = cx + w * F(0.0), cy + h * RECT_SHIFT_Y
+            else:
+                x_shift = (F(iw) * w * F(0.0) * cos_a - F(ih) * h * RECT_SHIFT_Y * sin_a) / F(iw)
+                y_shift = (F(iw) * w * F(0.0) * sin_a + F(ih) * h * RECT_SHIFT_Y * cos_a) / F(ih)
+                cx, cy = cx + x_shift, cy + y_shift
+            long_side = max(w * F(iw), h * F(ih))
+            rect_w = long_side / F(iw) * RECT_SCALE
+            rect_h = long_side / F(ih) * RECT_SCALE
+            rects.append((cx, cy, rect_w, rect_h, rotation))
+        return rects
+
+    def _landmarks(self, image_rgb, cx, cy, rect_w, rect_h, rotation):
+        ih, iw = image_rgb.shape[:2]
+        crop = crop_rotated_rect(
+            image_rgb, F(cx) * F(iw), F(cy) * F(ih), F(rect_w) * F(iw),
+            F(rect_h) * F(ih), rotation, LANDMARK_SIZE, cv2.BORDER_REPLICATE,
+        )
+        lm_raw, presence, handedness_raw, world_raw = self.landmarker(crop[None])
+
+        # ThresholdingCalculator: hand is present only if score > threshold
+        if not F(presence.reshape(-1)[0]) > MIN_HAND_PRESENCE_CONFIDENCE:
+            return None
+
+        # TensorsToClassificationCalculator binary_classification:
+        # label_items[0] = Right (score s), label_items[1] = Left (score 1-s)
+        s = F(handedness_raw.reshape(-1)[0])
+        label, score = ("Right", s) if s >= F(0.5) else ("Left", F(1.0) - s)
+
+        # TensorsToLandmarksCalculator: x,y /= 224; z /= 224 then /= 0.4
+        lm = np.asarray(lm_raw).reshape(21, 3)
+        size = F(LANDMARK_SIZE)
+        nz = F(LANDMARKS_NORMALIZE_Z)
+
+        # LandmarkProjectionCalculator (square-ROI NORM_RECT path), float32
+        sin_a, cos_a = F(math.sin(rotation)), F(math.cos(rotation))
+        landmarks = np.zeros((21, 3), dtype=np.float32)
+        world = np.zeros((21, 3), dtype=np.float32)
+        wl = np.asarray(world_raw).reshape(21, 3)
+        for i in range(21):
+            x = lm[i, 0] / size - F(0.5)
+            y = lm[i, 1] / size - F(0.5)
+            z = lm[i, 2] / size / nz
+            nx = cos_a * x - sin_a * y
+            ny = sin_a * x + cos_a * y
+            landmarks[i, 0] = nx * F(rect_w) + F(cx)
+            landmarks[i, 1] = ny * F(rect_h) + F(cy)
+            landmarks[i, 2] = z * F(rect_w)
+            # WorldLandmarkProjectionCalculator: rotate xy by rect angle
+            world[i, 0] = cos_a * wl[i, 0] - sin_a * wl[i, 1]
+            world[i, 1] = sin_a * wl[i, 0] + cos_a * wl[i, 1]
+            world[i, 2] = wl[i, 2]
+
+        return {"handedness": label, "score": float(score),
+                "landmarks": landmarks, "world_landmarks": world}
+
+
+def draw(image_bgr, hands):
+    """Draw hand skeletons (in-place safe copy) on a BGR image."""
+    annotated = image_bgr.copy()
+    h, w = annotated.shape[:2]
+    for hand in hands:
+        pts = [(int(x * w), int(y * h)) for x, y, _ in hand["landmarks"]]
+        for a, b in HAND_CONNECTIONS:
+            cv2.line(annotated, pts[a], pts[b], (0, 255, 0), 2)
+        for x, y in pts:
+            cv2.circle(annotated, (x, y), 4, (0, 0, 255), -1)
+    return annotated