islkit 0.1.0__py3-none-any.whl

islkit/viz.py

@@ -0,0 +1,435 @@
+"""Replay a stick figure from *normalised* features.
+
+A replay instrument. A normalisation bug does not show up in a loss
+curve — the model just learns something slightly wrong and converges anyway.
+It shows up instantly as a skeleton that shears, drifts, or grows when the
+signer steps back. So the reconstruction here deliberately reads only the
+encoded 183-vector, never the raw landmarks: if the encoded vector has lost
+information or tangled two frames together, the figure has to be wrong too.
+
+Everything is drawn in the **body frame** — origin at the shoulder midpoint,
+one unit = one shoulder width. Two consequences worth knowing before reading a
+replay:
+
+* All panels share fixed axis limits. Per-panel autoscale would silently
+  rescale a figure that had drifted, which is the exact bug being hunted.
+* Absolute hand size is *not* in the feature vector, by design: `_hand_local`
+  divides it out so handshape survives camera distance. Hands are therefore
+  drawn at a fixed nominal size. A hand that changes size between replays is a
+  bug in the visualiser, not in the encoder.
+
+Only x and y are drawn. MediaPipe's z is a weak relative-depth estimate and
+plotting it would imply a precision it does not have.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")  # no display; must be set before pyplot is imported
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+from matplotlib.animation import FuncAnimation, PillowWriter  # noqa: E402
+
+from islkit.features import DIM_FRAME, DIM_GEOM, N_POSE_SEL  # noqa: E402
+from islkit.plotting import RUNS_DIR  # noqa: E402
+
+# --------------------------------------------------------------------------
+# Skeleton topology
+# --------------------------------------------------------------------------
+
+# Indices into the 11 kept pose landmarks, i.e. positions within POSE_SEL:
+#   0 nose  1 ear_l  2 ear_r  3 sh_l  4 sh_r  5 el_l  6 el_r
+#   7 wr_l  8 wr_r   9 hip_l  10 hip_r
+NOSE, EAR_L, EAR_R = 0, 1, 2
+SH_L, SH_R, EL_L, EL_R, WR_L, WR_R, HIP_L, HIP_R = 3, 4, 5, 6, 7, 8, 9, 10
+
+POSE_EDGES = [
+    (SH_L, SH_R),  # shoulder line — the body-frame baseline, always 1.0 long
+    (SH_L, EL_L),
+    (EL_L, WR_L),
+    (SH_R, EL_R),
+    (EL_R, WR_R),
+    (SH_L, HIP_L),
+    (SH_R, HIP_R),
+    (HIP_L, HIP_R),
+    (EAR_L, NOSE),
+    (NOSE, EAR_R),
+]
+
+HAND_EDGES = [
+    (0, 1), (1, 2), (2, 3), (3, 4),  # thumb
+    (0, 5), (5, 6), (6, 7), (7, 8),  # index
+    (9, 10), (10, 11), (11, 12),  # middle
+    (13, 14), (14, 15), (15, 16),  # ring
+    (0, 17), (17, 18), (18, 19), (19, 20),  # pinky
+    (5, 9), (9, 13), (13, 17),  # knuckle line
+]  # fmt: skip
+
+# Wrist-to-middle-MCP as a fraction of shoulder width. Roughly anatomical
+# (~9 cm against a ~40 cm shoulder span). The encoder discards the true value,
+# so this is a drawing constant and nothing more.
+HAND_SCALE = 0.22
+
+
+# --------------------------------------------------------------------------
+# Reconstruction
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Skeleton:
+    """One frame of features, unpacked back into drawable geometry.
+
+    All coordinates are in the body frame. `usable` is false for a frame the
+    encoder rejected (no shoulders, so no frame of reference at all).
+    """
+
+    pose: np.ndarray  # (11, 3)
+    wrists: np.ndarray  # (2, 3) — slot 0 is the dominant hand
+    hands: np.ndarray  # (2, 21, 3) placed at the wrists, nominal size
+    hand_valid: np.ndarray  # (2,) bool
+    pose_vis: np.ndarray  # (11,) float, MediaPipe visibility
+    face_valid: bool
+    nonmanual: np.ndarray  # (4,) brow raise, brow furrow, mouth open, mouth width
+    usable: bool
+
+
+def reconstruct(feat: np.ndarray) -> Skeleton:
+    """Encoded frame -> `Skeleton`. Accepts a 183- or 352-vector.
+
+    The velocity half of a 352-vector is ignored: it is a difference between
+    consecutive frames, and animating the positions already shows it.
+    """
+    feat = np.asarray(feat, np.float32).ravel()
+    if feat.shape[0] < DIM_FRAME:
+        raise ValueError(f"expected at least {DIM_FRAME} features, got {feat.shape[0]}")
+    feat = feat[:DIM_FRAME]
+
+    mask = feat[DIM_GEOM:]
+    hand_valid = mask[:2] > 0.5
+    pose_vis = mask[2 : 2 + N_POSE_SEL].copy()
+    face_valid = bool(mask[-1] > 0.5)
+
+    shapes = feat[:126].reshape(2, 21, 3)
+    wrists = feat[126:132].reshape(2, 3)
+    pose = feat[132 : 132 + N_POSE_SEL * 3].reshape(N_POSE_SEL, 3).copy()
+
+    # Hand-local shapes are unit-scaled on wrist-to-middle-MCP. Re-inflate to a
+    # fixed nominal size and hang each off its own wrist position, which is the
+    # separate block the decomposition kept precisely so this can be done.
+    hands = wrists[:, None, :] + shapes * HAND_SCALE
+    hands[~hand_valid] = 0.0
+
+    return Skeleton(
+        pose=pose,
+        wrists=wrists.copy(),
+        hands=hands.astype(np.float32),
+        hand_valid=hand_valid,
+        pose_vis=pose_vis,
+        face_valid=face_valid,
+        nonmanual=feat[165:169].copy(),
+        usable=bool(feat.any()),
+    )
+
+
+def _face_glyph(sk: Skeleton) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Brow lines and a mouth outline from the four non-manual scalars.
+
+    Indicative, not anatomical — the scalars are ratios, so the glyph shows
+    whether they *move sensibly*, which is the only thing worth seeing here.
+    Returns (left brow, right brow, mouth outline), each (N, 2).
+    """
+    nose = sk.pose[NOSE, :2]
+    face_w = float(np.linalg.norm(sk.pose[EAR_L, :2] - sk.pose[EAR_R, :2])) * 1.15
+    if face_w < 1e-6:
+        face_w = 0.45
+    face_h = face_w * 1.3
+    raise_, furrow, mouth_open, mouth_w = sk.nonmanual
+
+    # y grows downward (MediaPipe convention), so "up" is a subtraction.
+    brow_y = nose[1] - 0.18 * face_h - float(raise_) * face_h
+    inner = float(furrow) * face_w / 2
+    outer = inner + 0.20 * face_w
+    brow_l = np.array([[nose[0] + inner, brow_y], [nose[0] + outer, brow_y]], np.float32)
+    brow_r = np.array([[nose[0] - inner, brow_y], [nose[0] - outer, brow_y]], np.float32)
+
+    theta = np.linspace(0, 2 * np.pi, 33)
+    mouth = np.stack(
+        [
+            nose[0] + np.cos(theta) * float(mouth_w) * face_w / 2,
+            nose[1] + 0.30 * face_h + np.sin(theta) * max(float(mouth_open), 0.01) * face_h / 2,
+        ],
+        axis=1,
+    ).astype(np.float32)
+    return brow_l, brow_r, mouth
+
+
+# --------------------------------------------------------------------------
+# Drawing
+# --------------------------------------------------------------------------
+
+
+class SkeletonArtist:
+    """Line artists for one skeleton on one axis, updated in place per frame."""
+
+    def __init__(
+        self,
+        ax: plt.Axes,
+        color: str = "#1f77b4",
+        lw: float = 1.6,
+        alpha: float = 1.0,
+        joints: bool = True,
+        face: bool = True,
+        zorder: float = 2.0,
+    ) -> None:
+        self.face = face
+        kw = {
+            "color": color,
+            "lw": lw,
+            "alpha": alpha,
+            "solid_capstyle": "round",
+            "zorder": zorder,
+        }
+        # The neck is not a landmark; it is drawn from the shoulder midpoint,
+        # which in the body frame is the origin by construction. If it ever
+        # renders anywhere but between the shoulders, the frame is wrong.
+        self.body = [ax.plot([], [], **kw)[0] for _ in POSE_EDGES]
+        self.neck = ax.plot([], [], **kw)[0]
+        self.head = ax.plot([], [], **{**kw, "lw": lw * 0.8})[0]
+        self.hands = [[ax.plot([], [], **kw)[0] for _ in HAND_EDGES] for _ in range(2)]
+        self.dots = ax.plot(
+            [],
+            [],
+            "o",
+            color=color,
+            ms=3.0 if joints else 0.0,
+            alpha=alpha,
+            ls="none",
+            zorder=zorder,
+        )[0]
+        if face:
+            fkw = {**kw, "lw": lw * 0.8}
+            self.brows = [ax.plot([], [], **fkw)[0] for _ in range(2)]
+            self.mouth = ax.plot([], [], **fkw)[0]
+
+    def artists(self):
+        out = [*self.body, self.neck, self.head, self.dots, *self.hands[0], *self.hands[1]]
+        if self.face:
+            out += [*self.brows, self.mouth]
+        return out
+
+    def clear(self):
+        for artist in self.artists():
+            artist.set_data([], [])
+        return self.artists()
+
+    def update(self, sk: Skeleton):
+        if not sk.usable:
+            return self.clear()
+
+        for line, (a, b) in zip(self.body, POSE_EDGES, strict=True):
+            line.set_data(sk.pose[[a, b], 0], sk.pose[[a, b], 1])
+        centre = (sk.pose[EAR_L, :2] + sk.pose[EAR_R, :2]) / 2
+        radius = float(np.linalg.norm(sk.pose[EAR_L, :2] - sk.pose[EAR_R, :2])) * 0.72
+        self.neck.set_data([0.0, float(centre[0])], [0.0, float(centre[1] + radius * 0.6)])
+        theta = np.linspace(0, 2 * np.pi, 49)
+        self.head.set_data(centre[0] + radius * np.cos(theta), centre[1] + radius * np.sin(theta))
+        self.dots.set_data(sk.pose[:, 0], sk.pose[:, 1])
+
+        for slot in range(2):
+            pts, valid = sk.hands[slot], sk.hand_valid[slot]
+            for line, (a, b) in zip(self.hands[slot], HAND_EDGES, strict=True):
+                # A missing hand is drawn as nothing, never as a hand at the
+                # origin — that distinction is the whole point of the mask.
+                if valid:
+                    line.set_data(pts[[a, b], 0], pts[[a, b], 1])
+                else:
+                    line.set_data([], [])
+
+        if self.face:
+            if sk.face_valid:
+                brow_l, brow_r, mouth = _face_glyph(sk)
+                self.brows[0].set_data(brow_l[:, 0], brow_l[:, 1])
+                self.brows[1].set_data(brow_r[:, 0], brow_r[:, 1])
+                self.mouth.set_data(mouth[:, 0], mouth[:, 1])
+            else:
+                for artist in (*self.brows, self.mouth):
+                    artist.set_data([], [])
+        return self.artists()
+
+
+def _limits(clips: Mapping[str, np.ndarray], margin: float = 0.25) -> tuple[tuple, tuple]:
+    """One set of axis limits for every panel.
+
+    Shared, not per-panel: autoscaling each panel would rescale away exactly
+    the divergence this figure exists to reveal.
+    """
+    pts = []
+    for clip in clips.values():
+        for feat in clip:
+            sk = reconstruct(feat)
+            if not sk.usable:
+                continue
+            pts.append(sk.pose[:, :2])
+            for slot in range(2):
+                if sk.hand_valid[slot]:
+                    pts.append(sk.hands[slot][:, :2])
+    if not pts:
+        return (-1.5, 1.5), (1.5, -1.5)
+    p = np.concatenate(pts)
+    lo, hi = p.min(0) - margin, p.max(0) + margin
+    # Equal aspect: pad the shorter axis rather than squashing the figure.
+    span = float(max(hi - lo))
+    mid = (lo + hi) / 2
+    x = (float(mid[0] - span / 2), float(mid[0] + span / 2))
+    y = (float(mid[1] + span / 2), float(mid[1] - span / 2))  # inverted: y is down
+    return x, y
+
+
+def _panel(ax, xlim, ylim, title: str = "", title_color: str = "#333333") -> None:
+    # Widen x to whatever the axes box actually is, keeping y fixed, so the
+    # panel fills its slot without matplotlib rescaling anything. The aspect
+    # stays equal throughout: a squashed axis would hide a skeleton that had
+    # genuinely sheared, which is one of the bugs this figure exists to catch.
+    box = ax.get_position()
+    fig_w, fig_h = ax.figure.get_size_inches()
+    aspect = (box.width * fig_w) / (box.height * fig_h)
+    y_span = abs(ylim[1] - ylim[0])
+    x_mid = (xlim[0] + xlim[1]) / 2
+    ax.set_xlim(x_mid - y_span * aspect / 2, x_mid + y_span * aspect / 2)
+    ax.set_ylim(*ylim)
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    for spine in ax.spines.values():
+        spine.set_color("#dddddd")
+    if title:
+        ax.set_title(title, fontsize=9, color=title_color)
+
+
+def _build_figure(clips: Mapping[str, np.ndarray], title: str, reference: str | None):
+    """Panel per clip on top, all clips overlaid underneath.
+
+    The overlay is the acceptance test: the reference is drawn as a thick pale
+    band and every clip as a thin coloured line on top of it. Identical
+    normalisation means every colour stays inside the band. Anything that
+    diverges leaves it, and you cannot miss it.
+    """
+    names = list(clips)
+    n = len(names)
+    ref = reference if reference in clips else names[0]
+    xlim, ylim = _limits(clips)
+    colors = [plt.get_cmap("tab10")(i % 10) for i in range(n)]
+
+    fig = plt.figure(figsize=(max(2.4 * n, 8.0), 7.6))
+    gs = fig.add_gridspec(
+        2, n, height_ratios=[1.0, 1.9],
+        top=0.90, bottom=0.09, left=0.03, right=0.97, hspace=0.14, wspace=0.05,
+    )  # fmt: skip
+
+    panels = []
+    for i, name in enumerate(names):
+        ax = fig.add_subplot(gs[0, i])
+        _panel(ax, xlim, ylim, name, title_color=colors[i])
+        panels.append(SkeletonArtist(ax, color=colors[i]))
+
+    # The overlay is centred over a subset of the columns rather than spanning
+    # the lot: equal aspect on a very wide box would just pad it with empty
+    # space and shrink the figure that has to be read closely.
+    span = n if n <= 3 else 3
+    start = (n - span) // 2
+    ax_ov = fig.add_subplot(gs[1, start : start + span])
+    _panel(ax_ov, xlim, ylim, f"all {n} overlaid — grey band is “{ref}”")
+    band = SkeletonArtist(ax_ov, color="#cfcfcf", lw=8.0, joints=False, zorder=1.0)
+    overlay = [
+        SkeletonArtist(ax_ov, color=colors[i], lw=1.3, alpha=0.9, joints=False, zorder=2.0)
+        for i in range(n)
+    ]
+
+    if title:
+        fig.suptitle(title, fontsize=11)
+    handles = [plt.Line2D([], [], color=colors[i], lw=2.5) for i in range(n)]
+    fig.legend(
+        handles, names, loc="lower center", bbox_to_anchor=(0.5, 0.035),
+        ncols=min(n, 6), frameon=False, fontsize=8,
+    )  # fmt: skip
+    stamp = fig.text(0.5, 0.012, "", ha="center", fontsize=8, color="#888888")
+    seqs = [np.asarray(clips[name], np.float32) for name in names]
+    ref_seq = np.asarray(clips[ref], np.float32)
+
+    def update(t: int):
+        artists = []
+        for i, seq in enumerate(seqs):
+            sk = reconstruct(seq[t])
+            artists += panels[i].update(sk)
+            artists += overlay[i].update(sk)
+        artists += band.update(reconstruct(ref_seq[t]))
+        sk0 = reconstruct(seqs[0][t])
+        stamp.set_text(
+            f"frame {t + 1}/{len(seqs[0])}   "
+            f"hands {int(sk0.hand_valid[0])}{int(sk0.hand_valid[1])}   "
+            f"face {int(sk0.face_valid)}   body frame: 1 unit = shoulder width"
+        )
+        return [*artists, stamp]
+
+    return fig, update, len(seqs[0])
+
+
+# --------------------------------------------------------------------------
+# Entry points
+# --------------------------------------------------------------------------
+
+
+def animate_replay(
+    clips: Mapping[str, np.ndarray],
+    experiment: str,
+    filename: str = "replay.gif",
+    fps: int = 12,
+    title: str = "",
+    reference: str | None = None,
+) -> Path:
+    """Animate one or more encoded clips side by side and save a GIF.
+
+    `clips` maps a label to a (T, 183) or (T, 352) array; all must share T.
+    Writes to runs/<experiment>/<filename> and returns the path.
+    """
+    if not clips:
+        raise ValueError("nothing to replay")
+    lengths = {len(np.asarray(c)) for c in clips.values()}
+    if len(lengths) != 1:
+        raise ValueError(f"clips must share a frame count, got {sorted(lengths)}")
+
+    out_dir = RUNS_DIR / experiment
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / filename
+
+    fig, update, n_frames = _build_figure(clips, title, reference)
+    anim = FuncAnimation(fig, update, frames=n_frames, blit=False)
+    anim.save(out_path, writer=PillowWriter(fps=fps))
+    plt.close(fig)
+    return out_path
+
+
+def still_replay(
+    clips: Mapping[str, np.ndarray],
+    experiment: str,
+    filename: str = "replay.png",
+    frame: int = 0,
+    title: str = "",
+    reference: str | None = None,
+) -> Path:
+    """One frame of the same figure, as a PNG. For pasting into a write-up."""
+    out_dir = RUNS_DIR / experiment
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / filename
+
+    fig, update, n_frames = _build_figure(clips, title, reference)
+    update(int(np.clip(frame, 0, n_frames - 1)))
+    fig.savefig(out_path, dpi=130)
+    plt.close(fig)
+    return out_path

islkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: islkit
+Version: 0.1.0
+Summary: Indian Sign Language recognition from MediaPipe landmarks: features, a dual-branch TCN, and a live recognition service
+Project-URL: Homepage, https://github.com/jbrathwa/islkit
+Project-URL: Issues, https://github.com/jbrathwa/islkit/issues
+Author: Jayraj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,isl,landmarks,mediapipe,sign-language,tcn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: <3.13,>=3.12
+Requires-Dist: mediapipe==0.10.18
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: torch>=2.5
+Provides-Extra: train
+Requires-Dist: pandas>=3.0.5; extra == 'train'
+Requires-Dist: pyarrow>=25.0.1; extra == 'train'
+Requires-Dist: xgboost>=3.4.1; extra == 'train'
+Description-Content-Type: text/markdown
+
+# islkit
+
+Indian Sign Language (ISL) recognition from MediaPipe Holistic landmarks.
+
+islkit turns camera frames into glosses. It covers every step: a landmark
+feature encoder, a dual-branch temporal convolutional network (TCN), a loader
+for the INCLUDE dataset, live inference with a confidence-gated decline, and a
+small HTTP/SSE recognition service. It runs on CPU and is built to work on small
+ARM boards as well as laptops.
+
+```
+camera → MediaPipe Holistic → RawFrame → encode_clip (T×352) → TCN → gloss | None
+```
+
+## Install
+
+```sh
+pip install islkit            # inference and the recognition service
+pip install "islkit[train]"   # + pandas, pyarrow, xgboost for INCLUDE and the baseline
+```
+
+Requires **Python 3.12**. `mediapipe` is pinned to `0.10.18`, which also pins
+`numpy<2`. That is the last MediaPipe release that keeps `mp.solutions` and
+still runs on ARMv8.0-A (Cortex-A53) boards.
+
+On macOS, XGBoost needs `brew install libomp`. Don't import `torch` and
+`xgboost` in the same process: each bundles its own libomp, and the process
+aborts with `OMP: Error #15`. `import islkit` keeps torch lazy for this reason.
+
+## Design
+
+**Features, not raw landmarks.** Holistic's flattened output has 1,662 values,
+and 85% of them are face mesh. The encoder reduces each frame to **183 floats**
+(352 with velocity):
+
+| Block                          | Dims |
+|--------------------------------|------|
+| Hand-local shapes (2 × 21 × 3) | 126  |
+| Wrist positions in body frame  | 6    |
+| Upper-body pose (11 landmarks) | 33   |
+| Non-manual scalars from face   | 4    |
+| Validity mask                  | 14   |
+
+The encoder uses three coordinate frames rather than one normalisation. Body
+frame: origin at the shoulder midpoint, scaled by shoulder width. Hand-local
+frame: origin at the wrist, scaled by the wrist-to-middle-MCP distance. Wrist
+position is recovered separately in the body frame. This keeps handshape
+separate from location.
+
+**Principles the code enforces:**
+
+- **Hand slots are geometric.** Slot 0 is the hand nearer the dominant-side
+  shoulder. MediaPipe's handedness label flips under occlusion and is never read.
+- **Mask, never zero-fill.** A missing hand is not a hand at the origin. A
+  validity bit is carried per part and multiplied through the network.
+- **The label map is frozen.** `LabelMap` is saved beside the weights. Class
+  order rebuilt from a directory listing silently shifts indices.
+- **Checkpoints are tied to the encoder.** A checkpoint records an encoder
+  fingerprint, and `SignRecogniser` refuses to serve it through a different
+  encoder.
+- **Store raw landmarks.** Recordings hold raw MediaPipe output, so they can
+  be re-encoded when the normalisation changes.
+- **The model can say "I don't know".** Below the confidence threshold a
+  prediction is `None`. For an accessibility device, silence is better than a
+  confident wrong answer.
+
+## Usage
+
+### Encode a clip
+
+```python
+from islkit import encode_clip
+from islkit.infer import HolisticExtractor
+
+frames = []
+with HolisticExtractor() as extractor:
+    for frame_bgr in video_frames:          # BGR numpy arrays, e.g. from cv2
+        _, raw, _ = extractor.process(frame_bgr)
+        frames.append(raw)
+
+clip = encode_clip(frames, T=48)            # (48, 352) float32
+```
+
+### Recognise a sign
+
+```python
+from islkit import SignRecogniser
+
+recogniser = SignRecogniser("classifier.pt", threshold=0.6)  # labels_*.json beside it
+prediction = recogniser.classify(frames)
+print(prediction.gloss, prediction.confidence, prediction.top3)
+```
+
+`prediction.gloss` is `None` when the model declines.
+
+### Train
+
+```python
+from islkit import build_model, load_include
+from islkit.model import fit
+
+data = load_include("path/to/isl-mediapipe-holistic-landmarks")   # data.X: (N, 48, 352)
+model = build_model(n_classes=len(data.label_map))
+fit(model, data.X, data.y)
+```
+
+`load_include` reads the Kaggle
+[`indian-sign-language-mediapipe-holistic-landmarks`](https://www.kaggle.com/datasets/swaptr/indian-sign-language-mediapipe-holistic-landmarks)
+dump of INCLUDE and caches the encoded arrays. That dump records no signer or
+session, so a class-stratified k-fold over whole clips is the only honest split
+available. It still leaks signers, so **report numbers from it as optimistic**.
+For your own recordings, use leave-one-session-out: `build_dataset` returns a
+`sessions` array for this.
+
+`replace_head` and `freeze_backbone` support fine-tuning a pretrained backbone
+on a smaller vocabulary. Always report per-class F1 (`per_class_f1`), not just
+aggregate accuracy.
+
+### Run the recognition service
+
+```python
+import threading
+from islkit.infer import ClipStore, HolisticExtractor, SignRecogniser
+from islkit.pipeline import CameraSource, RecognitionPipeline
+from islkit.server import EventHub, make_server
+
+recogniser = SignRecogniser("classifier.pt")
+hub = EventHub()
+pipeline = RecognitionPipeline(
+    recogniser=recogniser,
+    source_factory=lambda: CameraSource(0, "1280x720"),
+    on_event=hub.publish,
+    extractor_factory=HolisticExtractor,
+    store=ClipStore(),
+    on_pause=hub.clear_take,
+)
+threading.Thread(target=pipeline.run, daemon=True).start()
+make_server(pipeline, hub).serve_forever()     # 127.0.0.1:9978
+```
+
+| Route           | Does                                   |
+|-----------------|----------------------------------------|
+| `GET /results`  | Server-sent events: tracking, takes, predictions |
+| `POST /capture` | Start or pause capture                 |
+| `GET /health`   | Pipeline and subscriber status         |
+
+`islkit.view.make_view_server` serves an optional annotated MJPEG debug view
+on a separate port.
+
+Pretrained weights are not shipped with the package.
+
+## Guides and experiments
+
+- [`docs/`](docs/README.md): how the features, dataset, baseline, pretraining and fine-tuning
+  work, each argued from committed results.
+- [`experiments/`](experiments/README.md): the scripts that produce those results, runnable from
+  a clone of this repository.
+
+## Development
+
+```sh
+uv sync --extra train
+uv run pytest
+uv run ruff check .
+```
+
+The tests cover the properties that would silently break recognition: encoder
+invariances, mask gating, label-map and checkpoint round-trips, and the
+saved-clip layout.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

islkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+islkit/__init__.py,sha256=TE3jMbwfw67n1Cw057y7dUvaIZyzOjsxpgCBRFrd78w,2676
+islkit/adapters.py,sha256=vrFHC00P4EeLHWc46JfK5AaBWE2Q-CXtOMJhx5OU9_Y,8604
+islkit/baseline.py,sha256=qlU50HvkyPlV8KdB0VaAxnKL_KunJmXgHJS7SeoVxcM,12309
+islkit/data.py,sha256=9ZWLYRMFE6UOhCUOInYhoAvZqcqQ6wBAlk80ilSpJAQ,12494
+islkit/device.py,sha256=9fdnYIJCAwzo9UR-77JPbCQ1x9P_J1I0B_bCFRMppHc,1170
+islkit/domain.py,sha256=eYargvj4nmqnkPOht90hmnQMT72zOnDb5PKuOYBKusU,7989
+islkit/features.py,sha256=D_KtoSQP2fP4Ln86rkzPxUfU5ZaymJIfvFQLv4oISO8,11896
+islkit/infer.py,sha256=Xghyd3uen61GAo1kD2mhUD0w3FTEcvxfp0n9PAb0KiA,39820
+islkit/labels.py,sha256=DXh0W3NCe6jTQ6WFHmzYL9toOA9plcrQbrDkKhfm_gc,7982
+islkit/metrics.py,sha256=ZvuRUzlh8Y9-PczIK-qB_uU7C0ZvNACIec05rG-hpqw,2870
+islkit/model.py,sha256=gNFdpHk9aG1FCxRcTll0rhSxEzmR2hAiY_581OI2-lk,25764
+islkit/pipeline.py,sha256=-XIkfDfYxUKDfE-97calQaM2E7z7fnY3aqMvOtV2nLk,28811
+islkit/plotting.py,sha256=UXtY5aOlBxewXNpoozkC4mnwOamI_eg1bqzc55nZ88g,4285
+islkit/seeding.py,sha256=1PG-oZdGpesg7HaR8N5Ofh47F8wi6hB1syEOcNN8nnQ,489
+islkit/server.py,sha256=MsOa30XPbSZtw3P-LVLSgwa1Bou_rCEQr74sAi6HArU,9664
+islkit/view.py,sha256=_ZzUmEsW15Kx4fsAANNHHS3V-VC0bHq0Lj6UQULqVUc,10929
+islkit/viz.py,sha256=3ZCJC7VzqDcTKC2hfSlzRo_PACWa0A5cVnqS18c1qwE,16541
+islkit-0.1.0.dist-info/METADATA,sha256=JSHY0JswdvGbwSPlOxx1VjK0g3Z3owW-gtG4WY2U5Oo,7433
+islkit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+islkit-0.1.0.dist-info/licenses/LICENSE,sha256=V2ZUbrXhmO0lJ5gEnhAVHTfopcs9h8ev1E0IDQTX-0k,1063
+islkit-0.1.0.dist-info/RECORD,,

islkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

islkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayraj
+
+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.