islkit 0.1.0__py3-none-any.whl

islkit/plotting.py

@@ -0,0 +1,131 @@
+"""Training curves, saved to disk rather than shown.
+
+Experiments run from a terminal, so there is no window to pop up. Everything
+lands in runs/<experiment>/ under the current working directory, or under
+$ISLKIT_RUNS_DIR when set. Keep figures beside any write-up that argues from
+them, so the evidence stays checkable.
+"""
+
+import os
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+import matplotlib
+import numpy as np
+
+matplotlib.use("Agg")  # no display; must be set before pyplot is imported
+import matplotlib.pyplot as plt  # noqa: E402
+
+RUNS_DIR = Path(os.environ.get("ISLKIT_RUNS_DIR", "runs")).resolve()
+
+
+def plot_curves(
+    series: Mapping[str, Sequence[float]],
+    title: str,
+    experiment: str,
+    filename: str = "curves.png",
+    xlabel: str = "epoch",
+) -> Path:
+    """Plot one line per entry in `series` and save it under runs/<experiment>/.
+
+    Returns the path written, so callers can print it.
+    """
+    out_dir = RUNS_DIR / experiment
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / filename
+
+    fig, ax = plt.subplots(figsize=(7, 4))
+    for label, values in series.items():
+        ax.plot(range(1, len(values) + 1), values, label=label, marker="o", markersize=3)
+    ax.set_title(title)
+    ax.set_xlabel(xlabel)
+    ax.grid(alpha=0.3)
+    ax.legend()
+    fig.tight_layout()
+    fig.savefig(out_path, dpi=120)
+    plt.close(fig)
+    return out_path
+
+
+def plot_confusion(
+    cm,
+    title: str,
+    experiment: str,
+    filename: str = "confusion.png",
+    names: Sequence[str] | None = None,
+    max_ticks: int = 45,
+) -> Path:
+    """Row-normalised confusion matrix as an image, saved under runs/<experiment>/.
+
+    Rows are the true class, columns the prediction, so a bright diagonal is a
+    working classifier and a bright column is a class the model falls back on.
+    Rows are normalised by support because INCLUDE is 6.25x imbalanced and raw
+    counts would just redraw the class distribution.
+
+    Tick labels are drawn only when there are few enough classes to read them;
+    past that the image shows structure and `top_confusions` carries the detail.
+    """
+    cm = np.asarray(cm, dtype=np.float64)
+    out_dir = RUNS_DIR / experiment
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / filename
+
+    support = cm.sum(axis=1, keepdims=True)
+    norm = np.divide(cm, support, out=np.zeros_like(cm), where=support > 0)
+
+    n = len(cm)
+    size = max(6.0, min(16.0, n * 0.22))
+    fig, ax = plt.subplots(figsize=(size, size * 0.92))
+    im = ax.imshow(norm, cmap="magma", vmin=0.0, vmax=1.0, interpolation="nearest")
+
+    ax.set_title(title)
+    ax.set_xlabel("predicted")
+    ax.set_ylabel("true")
+    if names is not None and n <= max_ticks:
+        ax.set_xticks(range(n), names, rotation=90, fontsize=7)
+        ax.set_yticks(range(n), names, fontsize=7)
+    else:
+        ax.set_xticks([0, n - 1])
+        ax.set_yticks([0, n - 1])
+    fig.colorbar(im, ax=ax, fraction=0.046, label="share of true class")
+    fig.tight_layout()
+    fig.savefig(out_path, dpi=140)
+    plt.close(fig)
+    return out_path
+
+
+def plot_f1_distribution(
+    scores: Sequence[float],
+    title: str,
+    experiment: str,
+    filename: str = "f1_distribution.png",
+) -> Path:
+    """Sorted per-class F1 plus its histogram, saved under runs/<experiment>/.
+
+    Report per-class F1: an aggregate number hides a class that never works. The
+    left panel is where you see how many classes are at zero.
+    """
+    scores = np.sort(np.asarray(scores, dtype=np.float64))
+    out_dir = RUNS_DIR / experiment
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / filename
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(11, 4))
+    ax1.plot(range(1, len(scores) + 1), scores, lw=1.6)
+    ax1.axhline(float(np.median(scores)), ls="--", c="crimson", lw=1, label="median")
+    ax1.set_xlabel("class, worst to best")
+    ax1.set_ylabel("F1")
+    ax1.set_ylim(-0.02, 1.02)
+    ax1.grid(alpha=0.3)
+    ax1.legend()
+
+    ax2.hist(scores, bins=20, range=(0.0, 1.0), color="#4c72b0")
+    ax2.set_xlabel("F1")
+    ax2.set_ylabel("classes")
+    ax2.grid(alpha=0.3)
+
+    fig.suptitle(title)
+    fig.tight_layout()
+    fig.savefig(out_path, dpi=130)
+    plt.close(fig)
+    return out_path

islkit/seeding.py

@@ -0,0 +1,19 @@
+"""Reproducibility.
+
+Seeding all three RNGs matters more than it looks: numpy generates the data,
+torch initialises the weights and shuffles the batches, and `random` sneaks in
+through library code. Miss one and a "deterministic" run still drifts.
+"""
+
+import random
+
+import numpy as np
+import torch
+
+
+def set_seed(seed: int = 0) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)

islkit/server.py

@@ -0,0 +1,246 @@
+"""The recognition service's HTTP layer. No camera, no torch, no MediaPipe.
+
+Camera in, glosses out — this half is only the "out". It knows nothing about
+what a screen is, how the consuming service numbers its messages, or what
+language the device speaks; those belong to the orchestrator. If a change to
+the display protocol would require touching this file, the boundary has been
+drawn wrong.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import queue
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+MAX_SUBSCRIBERS = 4
+QUEUE_MAXSIZE = 256
+HEARTBEAT_SECONDS = 2.0
+
+# Which events are worth replaying to a subscriber that connects late, and under
+# which slot. Two slots, not one: framing and take state move independently, so a
+# reconnecting orchestrator needs both to draw a correct screen. `classifying`
+# lasts ~30 ms and `recognised`/`unclear`/`fault` are one-shot answers — retaining
+# any of them would strand a reconnect in a state that has long since passed.
+_RETAIN_SLOT = {"armed": "take", "recording": "take", "tracking": "tracking"}
+_REPLAY_ORDER = ("tracking", "take")  # framing first, then what we are doing
+
+
+class EventHub:
+    """Fan-out from one capture thread to N SSE subscribers.
+
+    `publish` never blocks and never raises. That is the whole point: the capture
+    thread is holding the camera and MediaPipe, and a slow or dead orchestrator
+    must not be able to stall it. A full queue loses its oldest event and says so
+    in `dropped_events`, which `/health` reports.
+    """
+
+    def __init__(self, max_subscribers: int = MAX_SUBSCRIBERS, maxsize: int = QUEUE_MAXSIZE):
+        self._max_subscribers = max_subscribers
+        self._maxsize = maxsize
+        self._lock = threading.Lock()
+        self._queues: list[queue.Queue] = []
+        self._retained: dict[str, dict] = {}
+        self.dropped_events = 0
+
+    @property
+    def subscribers(self) -> int:
+        with self._lock:
+            return len(self._queues)
+
+    def subscribe(self) -> queue.Queue | None:
+        """A queue pre-seeded with the retained state, or None if we are full."""
+        with self._lock:
+            if len(self._queues) >= self._max_subscribers:
+                return None
+            q: queue.Queue = queue.Queue(maxsize=self._maxsize)
+            for slot in _REPLAY_ORDER:
+                event = self._retained.get(slot)
+                if event is not None:
+                    q.put_nowait(event)
+            self._queues.append(q)
+            return q
+
+    def unsubscribe(self, q: queue.Queue) -> None:
+        """Idempotent: a handler thread can unwind through more than one path."""
+        with self._lock:
+            if q in self._queues:
+                self._queues.remove(q)
+
+    def clear_take(self) -> None:
+        """Drop the retained take-state event, leaving `tracking` retained.
+
+        Pausing destroys any in-flight take (`RecognitionPipeline.set_capture`
+        disarms it), but without this the hub would go on replaying the last
+        `armed`/`recording` to every new subscriber, when while paused only
+        `tracking` should be sent. Idempotent: popping an already-empty slot is a
+        no-op, so it is safe to call on every pause, not just a transition.
+        """
+        with self._lock:
+            self._retained.pop("take", None)
+
+    def publish(self, event: dict) -> None:
+        with self._lock:
+            slot = _RETAIN_SLOT.get(event.get("e"))
+            if slot is not None:
+                self._retained[slot] = event
+            for q in self._queues:
+                try:
+                    q.put_nowait(event)
+                except queue.Full:
+                    try:
+                        q.get_nowait()  # drop the oldest, keep the newest
+                    except queue.Empty:  # pragma: no cover - drained concurrently
+                        pass
+                    self.dropped_events += 1
+                    try:
+                        q.put_nowait(event)
+                    except queue.Full:  # pragma: no cover - drained concurrently
+                        pass
+
+
+DEFAULT_PORT = 9978  # the orchestrator takes 9977
+MAX_BODY_BYTES = 4096
+
+log = logging.getLogger("islkit.server")
+
+
+class _Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+    server_version = "islkit-recognition/1"
+
+    # -- helpers -----------------------------------------------------------
+
+    def _json(self, status: int, payload: dict) -> None:
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, fmt: str, *args) -> None:
+        log.debug("%s - %s", self.address_string(), fmt % args)
+
+    # -- routes ------------------------------------------------------------
+
+    def do_GET(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler's spelling
+        path = self.path.split("?", 1)[0]
+        if path == "/results":
+            self._results()
+        elif path == "/health":
+            try:
+                payload = self.server.pipeline.health()
+            except Exception:
+                # /health is what a watchdog polls; a bare disconnect on our
+                # side is the least useful failure it could see.
+                log.exception("pipeline.health() failed")
+                self._json(500, {"error": "health check failed"})
+                return
+            # The hub's own counters, not the pipeline's: /health reports both,
+            # and without this merge they are only ever exercised by the hub's
+            # own tests — slow-subscriber observability never actually reaches
+            # the wire.
+            payload = {
+                **payload,
+                "subscribers": self.server.hub.subscribers,
+                "dropped_events": self.server.hub.dropped_events,
+            }
+            self._json(200, payload)
+        else:
+            self._json(404, {"error": "not found"})
+
+    def do_POST(self) -> None:  # noqa: N802
+        if self.path.split("?", 1)[0] != "/capture":
+            self._json(404, {"error": "not found"})
+            return
+
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            self._json(400, {"error": "invalid Content-Length"})
+            return
+        if length > MAX_BODY_BYTES:
+            self._json(413, {"error": f"body must be under {MAX_BODY_BYTES} bytes"})
+            return
+
+        try:
+            payload = json.loads(self.rfile.read(length) or b"")
+            active = payload["active"]
+        except (ValueError, KeyError, TypeError):
+            self._json(400, {"error": 'body must be {"active": true|false}'})
+            return
+        if not isinstance(active, bool):
+            self._json(400, {"error": '"active" must be true or false'})
+            return
+
+        self._json(200, {"capture": self.server.pipeline.set_capture(active)})
+
+    def _results(self) -> None:
+        """SSE. No Content-Length: the body is delimited by the close, which is
+        what lets this stream indefinitely."""
+        q = self.server.hub.subscribe()
+        if q is None:
+            self._json(503, {"error": "too many subscribers"})
+            return
+
+        # Everything from here on can raise if the peer is already gone (a
+        # reset between accept and first byte hits end_headers itself) — the
+        # try must cover the header writes too, or a vanished client leaks
+        # its hub slot forever.
+        try:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-cache")
+            self.send_header("Connection", "close")
+            self.end_headers()
+
+            while True:
+                try:
+                    event = q.get(timeout=self.server.heartbeat)
+                    payload = f"data: {json.dumps(event, separators=(',', ':'))}\n\n"
+                except queue.Empty:
+                    # A comment, not an event: the orchestrator's 5 s offline
+                    # timer must reset on any received line, and an idle signer
+                    # produces no events for minutes.
+                    payload = ": ping\n\n"
+                self.wfile.write(payload.encode())
+                self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            pass  # the orchestrator went away; that is its right
+        finally:
+            self.server.hub.unsubscribe(q)
+
+
+class RecognitionServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address, pipeline, hub, heartbeat):
+        super().__init__(address, _Handler)
+        self.pipeline = pipeline
+        self.hub = hub
+        self.heartbeat = heartbeat
+
+
+def make_server(
+    pipeline,
+    hub: EventHub,
+    host: str = "127.0.0.1",
+    port: int = DEFAULT_PORT,
+    heartbeat: float = HEARTBEAT_SECONDS,
+) -> RecognitionServer:
+    """Bound to loopback by default. Nothing outside this machine — and nothing
+    inside an App Lab container — talks to this service directly."""
+    return RecognitionServer((host, port), pipeline, hub, heartbeat)
+
+
+def serve(pipeline, hub: EventHub, host: str = "127.0.0.1", port: int = DEFAULT_PORT) -> None:
+    server = make_server(pipeline, hub, host, port)
+    try:
+        server.serve_forever()
+    finally:
+        server.server_close()

islkit/view.py

@@ -0,0 +1,287 @@
+"""The debug view: annotated camera frames over MJPEG, for aiming the camera.
+
+This exists so a tester can see what the model sees — where the landmarks
+actually land, whether they are clipped, whether MediaPipe has lost the hands —
+without which "it did not recognise my sign" is unfalsifiable.
+
+Two properties matter more than anything else here:
+
+**It costs nothing when nobody is watching.** `ViewSink.watching` is False until
+a browser connects, and the pipeline checks it before it copies, draws or
+encodes a single frame. A service running unwatched pays one boolean read per
+frame.
+
+**It reuses the landmarks recognition already computed.** `HolisticExtractor`
+returns the frame and the raw MediaPipe results together, and already has a
+`draw()` built for this. Nothing here runs inference; a second Holistic pass on
+a board managing ~2 fps would halve the thing it is meant to debug.
+
+The frame published here is **unmirrored**, exactly as the model sees it. The
+page flips it with a CSS transform so positioning yourself feels natural, which
+costs nothing and lets each viewer toggle independently — mirroring server-side
+would mean a second encode per orientation for no gain.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+log = logging.getLogger(__name__)
+
+DEFAULT_VIEW_PORT = 9979
+JPEG_QUALITY = 70
+IDLE_SLEEP_S = 0.02
+CLIENT_TIMEOUT_S = 30.0
+
+
+class ViewSink:
+    """One latest-frame slot, plus the viewer count that gates producing it.
+
+    The pipeline publishes; HTTP handlers consume. Deliberately one slot and not
+    a queue: a viewer that falls behind should see the newest frame, never a
+    backlog of stale ones, and a debug view must never apply back-pressure to
+    the capture loop.
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._new = threading.Condition(self._lock)
+        self._jpeg: bytes | None = None
+        self._seq = 0
+        self._viewers = 0
+        self._published = 0
+
+    @property
+    def watching(self) -> bool:
+        """True when at least one browser is attached. The pipeline's gate."""
+        with self._lock:
+            return self._viewers > 0
+
+    @property
+    def viewers(self) -> int:
+        with self._lock:
+            return self._viewers
+
+    @property
+    def published(self) -> int:
+        with self._lock:
+            return self._published
+
+    def attach(self) -> None:
+        with self._lock:
+            self._viewers += 1
+
+    def detach(self) -> None:
+        with self._lock:
+            self._viewers = max(0, self._viewers - 1)
+
+    def publish(self, jpeg: bytes) -> None:
+        """Replace the current frame and wake every waiting handler."""
+        with self._new:
+            self._jpeg = jpeg
+            self._seq += 1
+            self._published += 1
+            self._new.notify_all()
+
+    def wait_for(self, last_seq: int, timeout: float = 1.0):
+        """Block until a frame newer than `last_seq`, or time out.
+
+        Returns (seq, jpeg), or (last_seq, None) if nothing new arrived. The
+        timeout is what lets a handler notice a client that has gone away.
+        """
+        with self._new:
+            if self._seq == last_seq or self._jpeg is None:
+                self._new.wait(timeout)
+            if self._jpeg is None or self._seq == last_seq:
+                return last_seq, None
+            return self._seq, self._jpeg
+
+
+def annotate(cv2, extractor, frame, results, overlay: dict) -> bytes | None:
+    """Draw landmarks and status onto a copy of `frame`, return JPEG bytes.
+
+    The copy is not optional. `extractor.draw()` writes into the array it is
+    given, and the array it would be given here comes straight from the camera
+    source — which may reuse its buffer. Drawing into it would corrupt whatever
+    the capture loop does with that frame next.
+
+    Returns None if the encode fails, which the caller treats as "skip this
+    frame": a debug view is never worth an exception in the capture loop.
+    """
+    try:
+        canvas = frame.copy()
+        extractor.draw(canvas, results)
+        _draw_overlay(cv2, canvas, overlay)
+        ok, buf = cv2.imencode(".jpg", canvas, [int(cv2.IMWRITE_JPEG_QUALITY), JPEG_QUALITY])
+        if not ok:
+            return None
+        return buf.tobytes()
+    except Exception:  # noqa: BLE001 - the view must not break capture
+        log.exception("view frame failed; skipping")
+        return None
+
+
+def _draw_overlay(cv2, canvas, overlay: dict) -> None:
+    """Status text, so the picture answers questions on its own.
+
+    Tracking status is the one that matters: `clipped` and `absent` explain a
+    take that never fired, and they are invisible in the landmarks alone.
+    """
+    lines = [
+        f"tracking: {overlay.get('tracking')}",
+        f"take: {overlay.get('take_state')}   capture: {'on' if overlay.get('capture') else 'off'}",
+        f"fps: {overlay.get('fps'):.2f}" if overlay.get("fps") is not None else "fps: -",
+    ]
+    tracking = overlay.get("tracking")
+    # BGR. Green when the framing is usable, amber when it is not.
+    colour = (120, 220, 120) if tracking == "ok" else (60, 190, 250)
+
+    y = 22
+    for text in lines:
+        cv2.putText(canvas, text, (8, y), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 0), 3)
+        cv2.putText(canvas, text, (8, y), cv2.FONT_HERSHEY_SIMPLEX, 0.5, colour, 1)
+        y += 20
+
+
+PAGE = """<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>islkit recognition view</title>
+<style>
+  :root { color-scheme: dark; }
+  body { margin: 0; background: #10141a; color: #e6e8ea;
+         font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; }
+  .wrap { max-width: 720px; margin: 0 auto; padding: 20px 16px 40px; }
+  h1 { font-size: 17px; margin: 0 0 4px; font-weight: 600; }
+  p.sub { margin: 0 0 16px; color: #98a2ad; font-size: 13px; }
+  .shot { background: #000; border: 1px solid #263040; border-radius: 6px;
+          overflow: hidden; line-height: 0; }
+  img { width: 100%; height: auto; display: block; }
+  img.mirror { transform: scaleX(-1); }
+  .bar { display: flex; gap: 10px; align-items: center; margin-top: 12px; flex-wrap: wrap; }
+  button { background: #1b2431; color: #e6e8ea; border: 1px solid #2f3a4a;
+           border-radius: 5px; padding: 7px 12px; font: inherit; cursor: pointer; }
+  button:hover { background: #223044; }
+  .hint { color: #98a2ad; font-size: 12px; }
+  code { background: #1b2431; padding: 1px 5px; border-radius: 3px; font-size: 12px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Recognition view</h1>
+  <p class="sub">The frames the classifier is actually seeing, with the landmarks it extracted.
+     Streaming costs nothing while this page is closed.</p>
+
+  <div class="shot">
+    <img id="feed" class="mirror" src="/view.mjpg" alt="annotated camera stream">
+  </div>
+
+  <div class="bar">
+    <button id="flip">Show the model&rsquo;s view</button>
+    <span class="hint" id="hint">Mirrored, so moving left moves the image left.</span>
+  </div>
+
+  <p class="hint" style="margin-top:16px">
+    Landmarks are drawn <em>before</em> any mirroring, so they line up in both views.
+    The model always receives the unmirrored frame &mdash; that is pinned at
+    <code>100.0%</code> unmirrored against <code>28.3%</code> mirrored.
+  </p>
+</div>
+<script>
+  const feed = document.getElementById('feed');
+  const flip = document.getElementById('flip');
+  const hint = document.getElementById('hint');
+  flip.addEventListener('click', () => {
+    const mirrored = feed.classList.toggle('mirror');
+    flip.textContent = mirrored ? "Show the model\\u2019s view" : 'Show the mirrored view';
+    hint.textContent = mirrored
+      ? 'Mirrored, so moving left moves the image left.'
+      : 'Unmirrored \\u2014 exactly the geometry the classifier receives.';
+  });
+</script>
+</body>
+</html>
+"""
+
+
+class _Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.0"  # one response per connection; MJPEG closes it
+
+    def log_message(self, fmt, *args):
+        log.debug("view %s - %s", self.address_string(), fmt % args)
+
+    def do_GET(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler's spelling
+        path = self.path.split("?", 1)[0]
+        if path in ("/", "/view", "/index.html"):
+            self._page()
+        elif path == "/view.mjpg":
+            self._stream()
+        else:
+            self.send_error(404)
+
+    def _page(self) -> None:
+        body = PAGE.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _stream(self) -> None:
+        sink = self.server.sink
+        sink.attach()
+        try:
+            self.send_response(200)
+            self.send_header("Age", "0")
+            self.send_header("Cache-Control", "no-cache, private")
+            self.send_header("Pragma", "no-cache")
+            self.send_header("Content-Type", "multipart/x-mixed-replace; boundary=frame")
+            self.end_headers()
+
+            last = 0
+            deadline = time.monotonic() + CLIENT_TIMEOUT_S
+            while True:
+                seq, jpeg = sink.wait_for(last)
+                if jpeg is None:
+                    # Nothing new. The capture loop may simply be slow; only give
+                    # up once nothing has arrived for a long time.
+                    if time.monotonic() > deadline:
+                        return
+                    continue
+                last = seq
+                deadline = time.monotonic() + CLIENT_TIMEOUT_S
+                self.wfile.write(b"--frame\r\n")
+                self.wfile.write(b"Content-Type: image/jpeg\r\n")
+                self.wfile.write(f"Content-Length: {len(jpeg)}\r\n\r\n".encode())
+                self.wfile.write(jpeg)
+                self.wfile.write(b"\r\n")
+                self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            log.debug("view client went away")
+        finally:
+            sink.detach()
+
+
+class ViewServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address, sink: ViewSink):
+        self.sink = sink
+        super().__init__(address, _Handler)
+
+
+def make_view_server(sink: ViewSink, host: str = "0.0.0.0", port: int = DEFAULT_VIEW_PORT):
+    """A debug-view server on its own port.
+
+    Separate from the recognition API on purpose. That API stays on loopback —
+    nothing outside the board should be able to start the camera — while this
+    binds where a laptop can reach it. The trade is deliberate and documented:
+    anyone who can reach this port can watch the camera.
+    """
+    return ViewServer((host, port), sink)