meltygui 0.1.0__py3-none-any.whl

meltygui/image_load.py

@@ -0,0 +1,308 @@
+"""Load an image (a file, or encoded bytes) as linear scRGB float32 (h, w, 3), 1.0 = SDR white (``sdr_white`` nits).
+
+meltygui's copy of hdr-viewer's image_load.py (~/Desktop/hdr-viewer), the reference decoder; `load_bytes` is the
+addition for the chat transcript's inline images (base64 payloads in a session).
+
+That is meltygui's working space: sRGB primaries, linear light, no ceiling, negatives
+allowed (BT.2020 colours outside sRGB come out negative and survive the fp16 path).
+
+Three kinds of file:
+  * 16-bit PNG with a PQ cICP chunk (what screenshot-hdr writes). Decoded here
+    by hand (Pillow flattens 16-bit RGB to 8-bit), PQ -> nits, BT.2020 -> sRGB
+    primaries, divided by ``sdr_white`` — the reference the FILE was authored
+    against (203 nits, BT.2408), not the desktop's SDR white.
+  * 8-bit PQ: a PNG with a PQ cICP chunk (Blender's HDR output) or a JPEG (or
+    anything Pillow opens) with a PQ ICC profile ("Rec2020 Gamut with PQ
+    Transfer"). Pillow decodes, then the same PQ path through a 256-entry LUT.
+  * anything else Pillow opens: treated as sRGB, 1.0 = SDR white. (A wide-gamut
+    SDR ICC profile such as Display P3 is not honoured yet.)
+"""
+import ctypes
+import hashlib
+import os
+import pathlib
+import struct
+import subprocess
+import zlib
+
+import numpy as np
+
+# chromaticities -> RGB->XYZ, and the BT.2020 -> sRGB matrix (both D65, no adaptation)
+def _rgb_to_xyz(xy):
+    xy = np.asarray(xy, dtype=float)
+    xyz = np.stack([xy[:, 0] / xy[:, 1], np.ones(4), (1 - xy.sum(axis=1)) / xy[:, 1]], axis=0)
+    m = xyz[:, :3]
+    return m @ np.diag(np.linalg.solve(m, xyz[:, 3]))
+
+BT2020_XY = [[.708, .292], [.170, .797], [.131, .046], [.3127, .3290]]
+SRGB_XY = [[.64, .33], [.30, .60], [.15, .06], [.3127, .3290]]
+P3_XY = [[.680, .320], [.265, .690], [.150, .060], [.3127, .3290]]
+BT2020_TO_SRGB = np.linalg.solve(_rgb_to_xyz(SRGB_XY), _rgb_to_xyz(BT2020_XY))
+# CICP (H.273) colour primaries code -> matrix to sRGB primaries
+PRIMARIES_TO_SRGB = {1: np.eye(3), 9: BT2020_TO_SRGB,
+                     12: np.linalg.solve(_rgb_to_xyz(SRGB_XY), _rgb_to_xyz(P3_XY))}
+CICP_PQ = 16
+
+
+def pq_decode(v):
+    """PQ code values in [0, 1] -> nits."""
+    p = np.maximum(v, 0) ** (1 / (2523 / 32))
+    return (np.maximum(p - 3424 / 4096, 0) / (2413 / 128 - (2392 / 128) * p)) ** (1 / (2610 / 16384)) * 10000
+
+
+_PQ16_LUT = None
+
+
+def pq16_to_nits():
+    """nits for every 16-bit PQ code, float32 (65536,). Indexing a 1080p frame
+    through it is ~10 ms; evaluating pq_decode over the frame was ~100 ms."""
+    global _PQ16_LUT
+    if _PQ16_LUT is None:
+        _PQ16_LUT = pq_decode(np.arange(65536, dtype=np.float64) / 65535.0).astype(np.float32)
+    return _PQ16_LUT
+
+
+def pq8_to_nits():
+    return pq_decode(np.arange(256, dtype=np.float64) / 255.0).astype(np.float32)
+
+
+def pq_to_linear(codes, primaries, sdr_white, alpha=None):
+    """PQ code values (uint8 or uint16 (h, w, 3)) in CICP ``primaries`` ->
+    linear scRGB float32, 1.0 = ``sdr_white`` nits; alpha (same dtype) composites
+    over black, like the compositor would. Returns (linear, peak_nits)."""
+    lut = pq16_to_nits() if codes.dtype == np.uint16 else pq8_to_nits()
+    nits = lut[codes]
+    if alpha is not None and alpha.min() != np.iinfo(alpha.dtype).max:
+        nits *= alpha.astype(np.float32)[..., None] / np.float32(np.iinfo(alpha.dtype).max)
+    m = (PRIMARIES_TO_SRGB.get(primaries, BT2020_TO_SRGB) / float(sdr_white)).astype(np.float32)
+    return nits @ m.T, float(nits.max())   # fp32 throughout: ~2 ms for 1080p
+
+
+def srgb_to_linear(v):
+    v = np.asarray(v, dtype=np.float32)
+    return np.where(v <= 0.04045, v / 12.92, ((v + 0.055) / 1.055) ** 2.4)
+
+
+# --- 16-bit PNG ----------------------------------------------------------------
+
+_UNFILTER_SRC = pathlib.Path(__file__).with_name('png_unfilter.c')
+_native = None  # C function, or False once we know it is unavailable
+
+
+def _native_unfilter():
+    """png_unfilter from png_unfilter.c, compiled once with cc into the cache dir
+    (keyed by source hash). None if there is no compiler."""
+    global _native
+    if _native is not None:
+        return _native or None
+    _native = False
+    try:
+        src = _UNFILTER_SRC.read_bytes()
+        cache = pathlib.Path(os.environ.get('XDG_CACHE_HOME') or pathlib.Path.home() / '.cache') / 'meltygui'
+        so = cache / f'png_unfilter-{hashlib.sha1(src).hexdigest()[:12]}.so'
+        if not so.is_file():
+            cache.mkdir(parents=True, exist_ok=True)
+            tmp = so.with_suffix(f'.{os.getpid()}.tmp')
+            subprocess.run(['cc', '-O2', '-shared', '-fPIC', '-o', str(tmp), str(_UNFILTER_SRC)],
+                           check=True, capture_output=True)
+            os.replace(tmp, so)
+        fn = ctypes.CDLL(str(so)).png_unfilter
+        fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, ctypes.c_int, ctypes.c_int]
+        fn.restype = ctypes.c_int
+        _native = fn
+    except (OSError, subprocess.CalledProcessError):
+        pass
+    return _native or None
+
+
+def _unfilter(raw, bpp):
+    """raw: (h, 1 + stride) uint8 with the filter byte first -> (h, stride) unfiltered.
+    Sub/Average/Paeth are serial in both axes, so this is a C loop when a compiler
+    is around and a (very slow: seconds per Paeth-heavy 1080p frame) Python one
+    otherwise."""
+    h, stride = raw.shape[0], raw.shape[1] - 1
+    fn = _native_unfilter()
+    if fn is not None:
+        raw = np.ascontiguousarray(raw)
+        out = np.empty((h, stride), dtype=np.uint8)
+        if fn(raw.ctypes.data, out.ctypes.data, h, stride, bpp) == 0:
+            return out
+        raise ValueError('bad PNG filter type')
+    return _unfilter_py(raw[:, 1:], raw[:, 0], bpp)
+
+
+def _unfilter_py(rows, filters, bpp):
+    out = np.zeros_like(rows)
+    prior = np.zeros(rows.shape[1], dtype=np.int32)
+    for y in range(rows.shape[0]):
+        kind = int(filters[y])
+        cur = rows[y].astype(np.int32)
+        if kind == 0:
+            raw = cur
+        elif kind == 2:
+            raw = (cur + prior) & 255
+        elif kind == 1:
+            raw = (np.cumsum(cur.reshape(-1, bpp), axis=0) & 255).reshape(-1)
+        else:
+            raw = np.zeros_like(cur)
+            for i in range(cur.shape[0]):
+                a = raw[i - bpp] if i >= bpp else 0
+                b = prior[i]
+                if kind == 3:
+                    pred = (a + b) >> 1
+                else:
+                    c = prior[i - bpp] if i >= bpp else 0
+                    p = a + b - c
+                    pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
+                    pred = a if (pa <= pb and pa <= pc) else (b if pb <= pc else c)
+                raw[i] = (cur[i] + pred) & 255
+        out[y] = raw
+        prior = raw
+    return out
+
+
+def read_png16(path, data=None):
+    """-> (rgb (h, w, 3) uint16, alpha uint16 or None, cicp bytes or None).
+    Raises ValueError unless it is a 16-bit RGB/RGBA non-interlaced PNG.
+    ``data``: the file's bytes when already in hand (no path needed)."""
+    if data is None:
+        data = pathlib.Path(path).read_bytes()
+    if data[:8] != b'\x89PNG\r\n\x1a\n':
+        raise ValueError('not a PNG')
+    pos, idat, cicp, header = 8, [], None, None
+    while pos + 8 <= len(data):
+        length, = struct.unpack('>I', data[pos:pos + 4])
+        kind = data[pos + 4:pos + 8]
+        body = data[pos + 8:pos + 8 + length]
+        if kind == b'IHDR':
+            header = struct.unpack('>IIBBBBB', body[:13])
+        elif kind == b'cICP':
+            cicp = bytes(body[:4])
+        elif kind == b'IDAT':
+            idat.append(body)
+        elif kind == b'IEND':
+            break
+        pos += 12 + length
+    if header is None:
+        raise ValueError('PNG without IHDR')
+    w, h, depth, ctype, _, _, interlace = header
+    if depth != 16 or ctype not in (2, 6) or interlace:
+        raise ValueError('not a 16-bit RGB/RGBA PNG')
+    channels = 3 if ctype == 2 else 4
+    bpp = channels * 2
+    raw = np.frombuffer(zlib.decompress(b''.join(idat)), np.uint8).reshape(h, 1 + w * bpp)
+    rows = _unfilter(raw, bpp) if raw[:, 0].any() else raw[:, 1:]
+    samples = rows.reshape(-1).view('>u2').reshape(h, w, channels).astype(np.uint16)
+    return samples[..., :3], (samples[..., 3] if channels == 4 else None), cicp
+
+
+def png_pq_cicp(path, data=None):
+    """(bit depth, primaries) if ``path`` (or ``data``, the file's bytes) is a
+    PNG whose cICP chunk says PQ transfer (screenshot-hdr: 16-bit; Blender:
+    8-bit), else None."""
+    if data is not None:
+        head = bytes(data[:4096])
+    else:
+        try:
+            with open(path, 'rb') as f:
+                head = f.read(4096)
+        except OSError:
+            return None
+    if head[:8] != b'\x89PNG\r\n\x1a\n' or len(head) < 25:
+        return None
+    pos = 8
+    while pos + 8 <= len(head):
+        length, = struct.unpack('>I', head[pos:pos + 4])
+        kind = head[pos + 4:pos + 8]
+        if kind == b'cICP':
+            primaries, transfer = head[pos + 8], head[pos + 9]
+            return (head[24], primaries) if transfer == CICP_PQ else None
+        if kind in (b'IDAT', b'IEND'):
+            return None
+        pos += 12 + length
+    return None
+
+
+def icc_pq_cicp(icc):
+    """The primaries code if an ICC profile declares a PQ transfer: its ICC.2
+    ``cicp`` tag (Google's "Rec2020 Gamut with PQ Transfer" profile carries
+    one), or failing that a description naming PQ. None for an SDR profile."""
+    if not icc or len(icc) < 132:
+        return None
+    try:
+        count, = struct.unpack('>I', icc[128:132])
+        for i in range(count):
+            sig, off, ln = struct.unpack('>4sII', icc[132 + 12 * i:144 + 12 * i])
+            if sig == b'cicp' and ln >= 12:
+                primaries, transfer = icc[off + 8], icc[off + 9]
+                return primaries if transfer == CICP_PQ else None
+            if sig == b'desc':
+                desc = icc[off:off + ln].replace(b'\x00', b'').lower()
+                if b'pq' in desc or b'2100' in desc:
+                    return 9
+    except (struct.error, IndexError):
+        pass
+    return None
+
+
+# --- public -------------------------------------------------------------------------------
+
+class Loaded:
+    """rgb: float32 (h, w, 3) linear scRGB, 1.0 = SDR white — or, for an opaque
+    8-bit sRGB source, srgb8: uint8 (h, w, 3) as decoded, to be linearised by the
+    GPU (rgb is then None). hdr: True for PQ sources; peak_nits: brightest
+    channel in nits (for the title)."""
+    def __init__(self, rgb, hdr, peak_nits, srgb8=None):
+        self.rgb, self.hdr, self.peak_nits, self.srgb8 = rgb, hdr, peak_nits, srgb8
+
+    @property
+    def size(self):
+        a = self.rgb if self.rgb is not None else self.srgb8
+        return a.shape[1], a.shape[0]
+
+
+def load(path, sdr_white, mark=lambda label: None):
+    """Decode ``path`` to linear scRGB. ``mark(label)`` is called after each stage for timing."""
+    return _decode(path, None, sdr_white, mark)
+
+
+def load_bytes(data, sdr_white, mark=lambda label: None):
+    """Decode an encoded image held in memory (a PNG / JPEG / WebP payload)
+    exactly as `load` decodes a file: PQ PNGs and PQ ICC profiles come out HDR."""
+    return _decode(None, bytes(data), sdr_white, mark)
+
+
+def _decode(path, data, sdr_white, mark):
+    pq = png_pq_cicp(path, data)
+    if pq and pq[0] == 16:
+        mark('sniffed PQ png')
+        rgb, alpha, _ = read_png16(path, data)
+        mark('png16 decoded')
+        linear, peak = pq_to_linear(rgb, pq[1], sdr_white, alpha)
+        mark('PQ -> linear scRGB')
+        return Loaded(linear, True, peak)
+    mark('sniffed: not 16-bit PQ png')
+    from PIL import Image, ImageOps
+    mark('PIL imported')
+    import io
+    with Image.open(path if data is None else io.BytesIO(data)) as im:
+        im = ImageOps.exif_transpose(im)
+        # PQ in an 8-bit container: a PNG with cICP (Blender) or a JPEG/anything
+        # with a PQ ICC profile (Chromium honours both; treated as sRGB they
+        # show flat and dim, 09-11).
+        primaries = pq[1] if pq else icc_pq_cicp(im.info.get('icc_profile'))
+        if primaries is not None:
+            arr = np.asarray(im.convert('RGBA'))
+            linear, peak = pq_to_linear(arr[..., :3], primaries, sdr_white, arr[..., 3])
+            mark('PIL decoded, PQ8 -> linear scRGB')
+            return Loaded(np.ascontiguousarray(linear, dtype=np.float32), True, peak)
+        if im.mode in ('RGBA', 'LA', 'P', 'PA') or os.environ.get('MELTY_NO_SRGB8'):
+            im = im.convert('RGBA')
+            arr = np.asarray(im, dtype=np.float32) / 255.0
+            rgb = srgb_to_linear(arr[..., :3]) * arr[..., 3:4]
+            mark('PIL decoded -> linear')
+            return Loaded(np.ascontiguousarray(rgb, dtype=np.float32), False, float(rgb.max()) * float(sdr_white))
+        srgb8 = np.ascontiguousarray(im.convert('RGB'))
+    mark('PIL decoded (sRGB8)')
+    peak = srgb_to_linear(np.float32(int(srgb8.max()) / 255.0))
+    return Loaded(None, False, float(peak) * float(sdr_white), srgb8=srgb8)

meltygui/model/__init__.py

@@ -0,0 +1 @@
+"""Feature data interfaces and operations."""

meltygui/model/account_model.py

@@ -0,0 +1,142 @@
+"""Account model functions and supporting definitions."""
+import json
+import os
+import stat
+import threading
+
+
+class AccountStore(dict):
+    """id -> account dict. `load()` reads the JSON; every mutation goes
+    through `set_field` / `add` / `remove` so the file stays in sync and
+    the window repaints. Runtime-only keys start with '_' and are never
+    written."""
+
+    def __init__(self):
+        super().__init__()
+        self._lock = threading.Lock()
+        self.loaded = False
+        self.error = None
+
+    def load(self):
+        from meltygui.accounts.internet_accounts import ACCOUNTS_PATH
+        from meltygui.accounts.internet_accounts import KINDS
+
+        with self._lock:
+            self.clear()
+            try:
+                if ACCOUNTS_PATH.exists():
+                    data = json.loads(ACCOUNTS_PATH.read_text())
+                    for entry in data.get("accounts", []):
+                        if isinstance(entry, dict) and entry.get("id") and entry.get("kind") in KINDS:
+                            self[entry["id"]] = entry
+                self.error = None
+            except Exception as error:
+                self.error = f"accounts.json: {error}"
+            self.loaded = True
+        self.ensure_kinds()
+        return self
+
+    def ensure_kinds(self):
+        # default accounts so every kind has a row to act on: the id is the
+        # kind name ("anthropic", "copilot", "ollama"); sessions asking for
+        # account="default" resolve to it (see `account`).
+        from meltygui.accounts.internet_accounts import KINDS
+
+        for kind in KINDS.values():
+            if not any(entry.get("kind") == kind.name for entry in self.values()):
+                self.add(kind.name, account_id=kind.name, save=False)
+            for entry in self.of_kind(kind.name):
+                for field in kind.fields:
+                    entry.setdefault(field.name, field.default)
+
+    def save(self):
+        from meltygui.accounts.internet_accounts import ACCOUNTS_PATH
+
+        with self._lock:
+            data = {"accounts": [{key: value for key, value in entry.items()
+                                  if not key.startswith("_")}
+                                 for entry in self.values()]}
+            try:
+                ACCOUNTS_PATH.parent.mkdir(parents=True, exist_ok=True)
+                tmp = ACCOUNTS_PATH.with_suffix(".json.tmp")
+                with open(tmp, "w") as file:
+                    file.write(json.dumps(data, indent=2))
+                os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+                os.replace(tmp, ACCOUNTS_PATH)
+                self.error = None
+            except Exception as error:
+                self.error = f"accounts.json: {error}"
+
+    def add(self, kind_name, account_id=None, save=True, **fields):
+        from meltygui.accounts.internet_accounts import KINDS
+        from meltygui.accounts.internet_accounts import accounts_changed
+
+        kind = KINDS[kind_name]
+        if account_id is None:
+            suffix = 2
+            while f"{kind_name}-{suffix}" in self:
+                suffix += 1
+            account_id = f"{kind_name}-{suffix}"
+        entry = {"id": account_id, "kind": kind_name,
+                 "label": fields.pop("label", None) or kind.default_label(account_id)}
+        for field in kind.fields:
+            entry[field.name] = fields.get(field.name, field.default)
+        self[account_id] = entry
+        if save:
+            self.save()
+        accounts_changed()
+        return entry
+
+    def remove(self, account_id):
+        """Drop an account. Its live sessions go first — computed while it
+        is still in the store, so a removed DEFAULT row also drops the
+        sessions pooled under "default" (built on its credentials; the next
+        row of the kind becomes the default, see `default_account`)."""
+        from meltygui.accounts.internet_accounts import KINDS
+        from meltygui.accounts.internet_accounts import _drop_sessions_for
+        from meltygui.accounts.internet_accounts import accounts_changed
+
+        entry = self.get(account_id)
+        if entry is None:
+            return
+        KINDS[entry["kind"]].close(entry)
+        _drop_sessions_for(entry)
+        self.pop(account_id, None)
+        self.save()
+        accounts_changed()
+
+    def set_field(self, account_id, field, value, reprobe=True):
+        from meltygui.accounts.internet_accounts import _drop_sessions_for
+        from meltygui.accounts.internet_accounts import accounts_changed
+
+        entry = self.get(account_id)
+        if entry is None or entry.get(field) == value:
+            return
+        entry[field] = value
+        if reprobe:
+            entry["_status"] = None        # stale → re-probe
+            entry.pop("_validated", None)  # credential changed → re-verify with Test
+            _drop_sessions_for(entry)      # live sessions hold the old credential
+        self.save()
+        accounts_changed()
+
+    def of_kind(self, kind_name):
+        return sorted((entry for entry in self.values() if entry.get("kind") == kind_name),
+                      key=lambda entry: (entry["id"] != kind_name, entry["id"]))
+
+    def default_account(self, kind_name):
+        """The kind's DEFAULT account — what `account(kind, "default")` and
+        the providers' `account="default"` resolve to: the entry named
+        after its kind, else (that one removed) the first remaining row of
+        the kind. Ids never change on promotion, so `account="anthropic-2"`
+        references, profile files and panel state all stay put."""
+        entry = self.get(kind_name)
+        if entry is not None and entry.get("kind") == kind_name:
+            return entry
+        rows = self.of_kind(kind_name)
+        return rows[0] if rows else None
+
+    def removable(self, account_entry) -> bool:
+        """A row can go while its kind keeps at least one other — the last
+        one stays (every kind always has a row to act on)."""
+        return len(self.of_kind(account_entry.get("kind"))) > 1

meltygui/model/camera_model.py

@@ -0,0 +1,159 @@
+"""
+The draw_voxels orbit camera as math — no GL, no imgui — so the 3D-mouse
+mapping (and the tests) can reason about it offline.
+
+The camera is THREE angles about the orbit target `pan`, plus a distance:
+
+    tilt   elevation: orbit over the poles (unrestricted, re-wrapped)
+    spin   azimuth about the world Z axis
+    roll   rotation about the view axis (0 = horizon level, the turntable)
+    zoom   eye distance from the target (cam_zoom)
+
+`basis(tilt, spin, roll)` is the ONE definition of the view frame; the GLSL
+raymarcher, the label vertex shader, the CUDA kernel and `_axis_edges`
+mirror it verbatim (roll rotates `right` toward `up` about `fwd`, then `up`
+is re-derived, so roll = 0 is exactly the old two-angle camera).
+
+Why angles and not a matrix: the sliders, presets (numpad 7 / 1 / 3), the
+mouse orbit and persistence all speak tilt / spin, and three angles carry
+the full rotation group — nothing is lost. So the 3D mouse never works
+"backwards from a matrix to tilt and spin" (lossy, singular at the poles):
+
+  - turntable: the puck's axes map straight onto the angles — yaw (ry) is a
+    spin increment, pitch (rx) a tilt increment, roll (rz) is ignored. No
+    matrix at all; the horizon stays level by construction.
+  - trackball: the puck's rotation vector is a small rotation in VIEW space
+    applied to the basis, and the new basis is DECOMPOSED back into
+    (tilt, spin, roll) — exact, since the decomposition is complete; only
+    at the poles (fwd along Z, where spin and roll are the same axis) the
+    previous spin is kept and roll absorbs the difference, so nothing jumps.
+"""
+
+from __future__ import annotations
+import math
+
+# Axis order of a space_mouse event's `axes` tuple (utils/space_mouse.py).
+TX, TY, TZ, RX, RY, RZ = range(6)
+
+
+def basis(tilt, spin, roll=0.0):
+    """World-space (fwd, right, up) of the camera — unit vectors."""
+    ct, st = math.cos(tilt), math.sin(tilt)
+    cs, ss = math.cos(spin), math.sin(spin)
+    fwd = (-cs * ct, -ss * ct, -st)
+    right0 = (-ss, cs, 0.0)
+    up0 = _cross(right0, fwd)
+    cr, sr = math.cos(roll), math.sin(roll)
+    right = tuple(a * cr + b * sr for a, b in zip(right0, up0))
+    up = _cross(right, fwd)
+    return fwd, right, up
+
+
+def decompose(fwd, right, tilt_hint=0.0, spin_hint=0.0):
+    """(fwd, right) → (tilt, spin, roll) with basis(...) rebuilding them.
+
+    `tilt_hint` picks the tilt branch: the stored tilt may sit past a pole
+    (cos(tilt) < 0, the mouse orbit's upside-down half) and the SAME
+    orientation is then written with the mirrored tilt and roll — keeping
+    the branch keeps a trackball nudge from rewriting every angle.
+    `spin_hint` is the spin kept at a pole (|cos(tilt)| ~ 0), where spin and
+    roll turn about the same axis and only their sum is defined."""
+    st = max(-1.0, min(1.0, -fwd[2]))
+    tilt = math.asin(st)
+    if math.cos(tilt_hint) < 0.0:
+        tilt = math.remainder(math.pi - tilt, math.tau)
+    ct = math.cos(tilt)
+    if abs(ct) > 1e-6:
+        sign = 1.0 if ct > 0 else -1.0
+        spin = math.atan2(-fwd[1] * sign, -fwd[0] * sign)
+        # Keep the previous spin's sign (it runs free past ±pi).
+        spin = spin_hint + math.remainder(spin - spin_hint, math.tau)
+    else:
+        spin = spin_hint
+    _, right0, up0 = basis(tilt, spin, 0.0)
+    roll = math.atan2(_dot(right, up0), _dot(right, right0))
+    return tilt, spin, roll
+
+
+def rotate_about(v, axis, angle):
+    """Rodrigues: rotate vector `v` about unit `axis` by `angle` radians."""
+    c, s = math.cos(angle), math.sin(angle)
+    k = axis
+    kv = _cross(k, v)
+    kd = _dot(k, v)
+    return tuple(v[i] * c + kv[i] * s + k[i] * kd * (1.0 - c) for i in range(3))
+
+
+def apply_space_mouse(axes, tilt, spin, roll, zoom, pan, *, navigation,
+                      orbit_sensitivity, pan_sensitivity, zoom_sensitivity,
+                      pivot="target"):
+    """One frame of 3D-mouse input → the new (tilt, spin, roll, zoom, pan).
+
+    `pivot` is what a rotation turns about: "target" orbits the camera
+    around `pan` (the mouse's orbit — the volume turns on screen), "camera"
+    keeps the EYE where it is and turns the view direction — the target
+    moves, the scene sweeps across the screen like looking around.
+
+    `axes` = (tx, ty, tz, rx, ry, rz), each already integrated over the
+    frame (full-deflection-seconds), in the reader's view-aligned frame:
+    x right, y up, z toward the viewer, in OBJECT terms: the volume moves
+    and turns the way the axes say — push right, it goes right; twist, it
+    twists. The device's hand (Blender's, space_mouse.BLENDER_SIGNS) is
+    applied upstream in space_mouse.normalize, and the mouse trackball feeds
+    screen-drag deltas here in the same terms.
+    """
+    tx, ty, tz, rx, ry, rz = axes
+    fwd, right, up = basis(tilt, spin, roll)
+    if pivot == "camera":
+        # ── free flight: a RIGID translation of eye and target together, a
+        # constant world-units-per-second on all three axes (tz forward
+        # along the view). The eye-to-target distance never changes, so
+        # nothing scales with zoom - a distance-scaled pan and e-fold dolly
+        # decayed to a standstill as flying forward drove the distance to 0.
+        k = pan_sensitivity
+        pan = tuple(p + (r * tx + u * ty + f * tz) * k
+                    for p, r, u, f in zip(pan, right, up, fwd))
+    else:
+        # ── orbit: pan in the screen plane, scaled by the camera distance
+        # so it covers the same fraction of the view at any zoom (the mouse
+        # pan's rule) ──
+        k = pan_sensitivity * zoom
+        pan = tuple(p + (r * tx + u * ty) * k for p, r, u in zip(pan, right, up))
+        # ── dolly: pull toward you = closer. cam_zoom is a distance, so the
+        # e-fold rule keeps the feel constant across scales (like the pan).
+        zoom = min(137.6, max(0.0, zoom * math.exp(-tz * zoom_sensitivity)))
+    # ── rotation ──
+    eye = tuple(p - f * zoom for p, f in zip(pan, fwd))
+    if navigation == "trackball":
+        # The cap's rotation vector in view space. Rotating the VOLUME by
+        # +w is rotating the CAMERA by -w about the target.
+        wx, wy, wz = rx * orbit_sensitivity, ry * orbit_sensitivity, rz * orbit_sensitivity
+        angle = math.sqrt(wx * wx + wy * wy + wz * wz)
+        if angle > 0.0:
+            axis = tuple((right[i] * wx + up[i] * wy + fwd[i] * wz) / angle for i in range(3))
+            fwd = rotate_about(fwd, axis, -angle)
+            right = rotate_about(right, axis, -angle)
+            tilt, spin, roll = decompose(fwd, right, tilt, spin)
+    else:
+        # Turntable: yaw about world up (a rightward twist spins the volume
+        # leftward as seen - upside-down the world axis points into the
+        # screen, so the sign follows cos(tilt), the mouse orbit's chirality
+        # rule, per frame since the keys has no screen edges to latch on).
+        spin_sign = -1.0 if math.cos(tilt) < 0.0 else 1.0
+        spin -= ry * orbit_sensitivity * spin_sign
+        tilt = math.remainder(tilt + rx * orbit_sensitivity, math.tau)
+    if pivot == "camera":
+        # The eye stays put: re-seat the target along the NEW view direction.
+        fwd, _, _ = basis(tilt, spin, roll)
+        pan = tuple(e + f * zoom for e, f in zip(eye, fwd))
+    return tilt, spin, roll, zoom, pan
+
+
+def _cross(a, b):
+    return (a[1] * b[2] - a[2] * b[1],
+            a[2] * b[0] - a[0] * b[2],
+            a[0] * b[1] - a[1] * b[0])
+
+
+def _dot(a, b):
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]