plot3 0.4.0__py3-none-any.whl

plot3/contour.py

@@ -0,0 +1,476 @@
+"""Implicit-curve contours.
+
+The NumPy backend is the default. ``contourpy`` is used when it is installed
+and ``PLOT3_CONTOUR_BACKEND`` asks for it. ``import plot3`` does not import
+``contourpy``; the import happens the first time a contour is drawn.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+
+import numpy as np
+
+# One segment per non-saddle case: local edge indices
+# 0 bottom, 1 right, 2 top, 3 left. Saddles (5 and 10) are filled below
+# from the cell-centre value, same pairing as the original cell loop.
+_EDGE_LUT = np.array(
+    [
+        [-1, -1],  # 0
+        [0, 3],  # 1
+        [0, 1],  # 2
+        [1, 3],  # 3
+        [1, 2],  # 4
+        [-1, -1],  # 5 saddle
+        [0, 2],  # 6
+        [2, 3],  # 7
+        [2, 3],  # 8
+        [0, 2],  # 9
+        [-1, -1],  # 10 saddle
+        [1, 2],  # 11
+        [1, 3],  # 12
+        [0, 1],  # 13
+        [0, 3],  # 14
+        [-1, -1],  # 15
+    ],
+    dtype=np.int8,
+)
+
+# Subdivide each coarse cell the contour crosses. 8× on the default 80-grid
+# keeps a unit circle smooth on (-10, 10). A full-window refit is not used:
+# it cannot refine a small loop that shares the window with a long curve.
+_REFINE_SUB = 8
+_REFINE_NODE_BUDGET = 400_000
+
+_contourpy_mod = None
+_contourpy_loaded = False
+_contourpy_warned = False
+
+
+def _reset_contour_backend() -> None:
+    """Forget the cached contourpy import. Tests use this."""
+    global _contourpy_mod, _contourpy_loaded, _contourpy_warned
+    _contourpy_mod = None
+    _contourpy_loaded = False
+    _contourpy_warned = False
+
+
+def _version_at_least(version: str, major: int, minor: int) -> bool:
+    parts: list[int] = []
+    for piece in str(version).split("."):
+        num = ""
+        for ch in piece:
+            if ch.isdigit():
+                num += ch
+            else:
+                break
+        if not num:
+            break
+        parts.append(int(num))
+        if len(parts) == 2:
+            break
+    while len(parts) < 2:
+        parts.append(0)
+    return (parts[0], parts[1]) >= (major, minor)
+
+
+def _load_contourpy():
+    """Return the contourpy module, or None if it is missing or too old."""
+    global _contourpy_mod, _contourpy_loaded
+    if _contourpy_loaded:
+        return _contourpy_mod
+    _contourpy_loaded = True
+    try:
+        import contourpy
+    except ImportError:
+        _contourpy_mod = None
+        return None
+    version = getattr(contourpy, "__version__", "0")
+    if not _version_at_least(version, 1, 0):
+        _contourpy_mod = None
+        return None
+    _contourpy_mod = contourpy
+    return contourpy
+
+
+def _backend_setting() -> str:
+    """Raw ``PLOT3_CONTOUR_BACKEND`` value: auto, numpy, or contourpy."""
+    raw = os.environ.get("PLOT3_CONTOUR_BACKEND", "auto").strip().lower()
+    if raw in ("", "auto", "numpy", "contourpy"):
+        return raw or "auto"
+    raise ValueError(
+        "PLOT3_CONTOUR_BACKEND must be auto, numpy, or contourpy, "
+        f"got {raw!r}"
+    )
+
+
+def _backend_name() -> str:
+    """Resolved backend name. ``contourpy`` is an error when it is missing."""
+    choice = _backend_setting()
+    if choice == "numpy":
+        return "numpy"
+    if choice == "contourpy":
+        if _load_contourpy() is None:
+            raise ValueError(
+                "PLOT3_CONTOUR_BACKEND=contourpy but contourpy>=1.0 is not "
+                "installed. Install it with: pip install plot3[fast]"
+            )
+        return "contourpy"
+    if _load_contourpy() is None:
+        return "numpy"
+    return "contourpy"
+
+
+def _interp_t(a: np.ndarray, b: np.ndarray, level: float) -> np.ndarray:
+    with np.errstate(divide="ignore", invalid="ignore"):
+        span = b - a
+        safe = np.where(span == 0.0, 1.0, span)
+        t = np.where(span == 0.0, 0.5, (level - a) / safe)
+        return np.clip(t, 0.0, 1.0)
+
+
+def _pair_segments(
+    local_ids: np.ndarray,
+    cases: np.ndarray,
+    center_inside: np.ndarray,
+) -> np.ndarray:
+    """Turn per-cell edge ids and case numbers into segment endpoint pairs."""
+    if cases.size == 0:
+        return np.zeros((0, 2), dtype=np.int64)
+    saddle = (cases == 5) | (cases == 10)
+    chunks: list[np.ndarray] = []
+    regular = ~saddle
+    if np.any(regular):
+        lut = _EDGE_LUT[cases[regular]]
+        loc = local_ids[regular]
+        index = np.arange(loc.shape[0])
+        chunks.append(np.stack([loc[index, lut[:, 0]], loc[index, lut[:, 1]]], axis=1))
+    if np.any(saddle):
+        loc = local_ids[saddle]
+        inside = center_inside[saddle]
+        if np.any(inside):
+            chunks.append(np.stack([loc[inside, 0], loc[inside, 1]], axis=1))
+            chunks.append(np.stack([loc[inside, 2], loc[inside, 3]], axis=1))
+        outside = ~inside
+        if np.any(outside):
+            chunks.append(np.stack([loc[outside, 0], loc[outside, 3]], axis=1))
+            chunks.append(np.stack([loc[outside, 1], loc[outside, 2]], axis=1))
+    if not chunks:
+        return np.zeros((0, 2), dtype=np.int64)
+    return np.concatenate(chunks, axis=0).astype(np.int64, copy=False)
+
+
+def _chain_edge_pairs(pairs: np.ndarray, point_of) -> list[list[tuple[float, float]]]:
+    """Join segments that share an edge id. The loop touches segments only."""
+    nseg = int(pairs.shape[0])
+    if nseg == 0:
+        return []
+    by_edge: dict[int, list[int]] = {}
+    for index in range(nseg):
+        for edge in (int(pairs[index, 0]), int(pairs[index, 1])):
+            by_edge.setdefault(edge, []).append(index)
+    used = np.zeros(nseg, dtype=bool)
+
+    def walk(tip: int) -> list[int]:
+        found: list[int] = []
+        while True:
+            nxt = -1
+            for cand in by_edge.get(tip, ()):
+                if not used[cand]:
+                    nxt = cand
+                    break
+            if nxt < 0:
+                return found
+            used[nxt] = True
+            left = int(pairs[nxt, 0])
+            right = int(pairs[nxt, 1])
+            other = right if left == tip else left
+            found.append(other)
+            tip = other
+
+    polylines: list[list[tuple[float, float]]] = []
+    for start in range(nseg):
+        if used[start]:
+            continue
+        used[start] = True
+        edge0 = int(pairs[start, 0])
+        edge1 = int(pairs[start, 1])
+        if edge0 == edge1:
+            continue
+        forward = walk(edge1)
+        backward = walk(edge0)
+        edges = list(reversed(backward)) + [edge0, edge1] + forward
+        polylines.append([point_of(edge) for edge in edges])
+    return polylines
+
+
+def _cell_cases(
+    field: np.ndarray, level: float
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Return ``(case, finite_active, center_inside)`` for each cell."""
+    f00 = field[:-1, :-1]
+    f10 = field[:-1, 1:]
+    f11 = field[1:, 1:]
+    f01 = field[1:, :-1]
+    finite = (
+        np.isfinite(f00) & np.isfinite(f10) & np.isfinite(f11) & np.isfinite(f01)
+    )
+    case = (
+        (f00 >= level).astype(np.uint8)
+        | ((f10 >= level).astype(np.uint8) << 1)
+        | ((f11 >= level).astype(np.uint8) << 2)
+        | ((f01 >= level).astype(np.uint8) << 3)
+    )
+    active = finite & (case != 0) & (case != 15)
+    center_inside = (0.25 * (f00 + f10 + f11 + f01)) >= level
+    return case, active, center_inside
+
+
+def _contour_numpy(
+    xs: np.ndarray,
+    ys: np.ndarray,
+    field: np.ndarray,
+    level: float,
+) -> list[list[tuple[float, float]]]:
+    """Marching squares over the whole grid. Cells are classified in NumPy."""
+    field = np.asarray(field, dtype=np.float64)
+    xs = np.asarray(xs, dtype=np.float64)
+    ys = np.asarray(ys, dtype=np.float64)
+    ny, nx = field.shape
+    if ny < 2 or nx < 2:
+        return []
+    case, active, center_inside = _cell_cases(field, level)
+    if not np.any(active):
+        return []
+    jj, ii = np.nonzero(active)
+    cases = case[jj, ii]
+    centers = center_inside[jj, ii]
+
+    h_count = ny * (nx - 1)
+    bottom = jj.astype(np.int64) * (nx - 1) + ii.astype(np.int64)
+    top = (jj.astype(np.int64) + 1) * (nx - 1) + ii.astype(np.int64)
+    left = h_count + jj.astype(np.int64) * nx + ii.astype(np.int64)
+    right = h_count + jj.astype(np.int64) * nx + (ii.astype(np.int64) + 1)
+    local = np.stack([bottom, right, top, left], axis=1)
+    pairs = _pair_segments(local, cases, centers)
+    if pairs.size == 0:
+        return []
+
+    h_a = field[:, :-1]
+    h_b = field[:, 1:]
+    h_t = _interp_t(h_a, h_b, level)
+    h_x = xs[:-1][None, :] + h_t * (xs[1:] - xs[:-1])[None, :]
+    h_y = np.broadcast_to(ys[:, None], h_x.shape)
+    v_a = field[:-1, :]
+    v_b = field[1:, :]
+    v_t = _interp_t(v_a, v_b, level)
+    v_y = ys[:-1][:, None] + v_t * (ys[1:] - ys[:-1])[:, None]
+    v_x = np.broadcast_to(xs[None, :], v_y.shape)
+    point_x = np.concatenate([np.ravel(h_x), np.ravel(v_x)])
+    point_y = np.concatenate([np.ravel(h_y), np.ravel(v_y)])
+
+    def point_of(edge: int) -> tuple[float, float]:
+        return (float(point_x[edge]), float(point_y[edge]))
+
+    return _chain_edge_pairs(pairs, point_of)
+
+
+def _as_polyline(line: np.ndarray) -> list[tuple[float, float]] | None:
+    arr = np.asarray(line, dtype=np.float64)
+    if arr.ndim != 2 or arr.shape[0] < 2 or arr.shape[1] < 2:
+        return None
+    points = [(float(row[0]), float(row[1])) for row in arr]
+    if len(points) >= 3:
+        x0, y0 = points[0]
+        x1, y1 = points[-1]
+        # Closed loops repeat the first point. Snap a numeric near-close too.
+        if abs(x0 - x1) <= 1e-9 and abs(y0 - y1) <= 1e-9:
+            points[-1] = points[0]
+    return points
+
+
+def _contour_contourpy(
+    xs: np.ndarray,
+    ys: np.ndarray,
+    field: np.ndarray,
+    level: float,
+) -> list[list[tuple[float, float]]]:
+    contourpy = _load_contourpy()
+    if contourpy is None:
+        raise ValueError(
+            "PLOT3_CONTOUR_BACKEND=contourpy but contourpy>=1.0 is not "
+            "installed. Install it with: pip install plot3[fast]"
+        )
+    masked = np.ma.masked_invalid(np.asarray(field, dtype=np.float64))
+    generator = contourpy.contour_generator(
+        x=np.asarray(xs, dtype=np.float64),
+        y=np.asarray(ys, dtype=np.float64),
+        z=masked,
+        line_type=contourpy.LineType.Separate,
+    )
+    polylines: list[list[tuple[float, float]]] = []
+    for line in generator.lines(float(level)):
+        poly = _as_polyline(line)
+        if poly is not None:
+            polylines.append(poly)
+    return polylines
+
+
+def _warn_contourpy_fallback(exc: BaseException) -> None:
+    global _contourpy_warned
+    if _contourpy_warned:
+        return
+    _contourpy_warned = True
+    warnings.warn(
+        f"plot3: contourpy failed ({exc}), using the NumPy contour backend",
+        UserWarning,
+        stacklevel=4,
+    )
+
+
+def _contour_lines(
+    xs: np.ndarray,
+    ys: np.ndarray,
+    field: np.ndarray,
+    level: float = 0.0,
+) -> list[list[tuple[float, float]]]:
+    """Contour ``field`` at ``level``. Backend comes from the environment."""
+    choice = _backend_setting()
+    if choice == "numpy" or (choice == "auto" and _load_contourpy() is None):
+        return _contour_numpy(xs, ys, field, level)
+    try:
+        return _contour_contourpy(xs, ys, field, level)
+    except Exception as exc:
+        if choice == "contourpy":
+            raise
+        _warn_contourpy_fallback(exc)
+        return _contour_numpy(xs, ys, field, level)
+
+
+def _refine_active_cells(
+    xs: np.ndarray,
+    ys: np.ndarray,
+    field: np.ndarray,
+    level: float,
+    sample,
+    sub: int = _REFINE_SUB,
+) -> list[list[tuple[float, float]]] | None:
+    """Re-sample only the cells the contour crosses, on a finer sub-grid.
+
+    Returns None when the fine grid would be too large; the caller keeps the
+    coarse contour, which is already a correct curve.
+    """
+    field = np.asarray(field, dtype=np.float64)
+    xs = np.asarray(xs, dtype=np.float64)
+    ys = np.asarray(ys, dtype=np.float64)
+    _case, active, _center = _cell_cases(field, level)
+    if not np.any(active):
+        return []
+    jj, ii = np.nonzero(active)
+    sub = int(sub)
+    nodes = sub + 1
+    if len(ii) * nodes * nodes > _REFINE_NODE_BUDGET:
+        sub = 4
+        nodes = sub + 1
+    if len(ii) * nodes * nodes > _REFINE_NODE_BUDGET:
+        return None
+    step = np.linspace(0.0, 1.0, nodes)
+    x0 = xs[ii]
+    x1 = xs[ii + 1]
+    y0 = ys[jj]
+    y1 = ys[jj + 1]
+    xf = x0[:, None] + (x1 - x0)[:, None] * step
+    yf = y0[:, None] + (y1 - y0)[:, None] * step
+    xx = np.empty((len(ii), nodes, nodes), dtype=np.float64)
+    yy = np.empty((len(ii), nodes, nodes), dtype=np.float64)
+    xx[:] = xf[:, None, :]
+    yy[:] = yf[:, :, None]
+    fine = np.asarray(sample(xx, yy), dtype=np.float64)
+    if fine.shape != xx.shape:
+        fine = np.broadcast_to(fine, xx.shape).astype(np.float64, copy=False)
+    return _contour_refined(ii, jj, xs, ys, fine, xf, yf, level, sub)
+
+
+def _contour_refined(
+    ii: np.ndarray,
+    jj: np.ndarray,
+    xs: np.ndarray,
+    ys: np.ndarray,
+    fine: np.ndarray,
+    xf: np.ndarray,
+    yf: np.ndarray,
+    level: float,
+    sub: int,
+) -> list[list[tuple[float, float]]]:
+    """Marching squares on a batch of refined cells, chained by global edge id."""
+    f00 = fine[:, :-1, :-1]
+    f10 = fine[:, :-1, 1:]
+    f11 = fine[:, 1:, 1:]
+    f01 = fine[:, 1:, :-1]
+    finite = (
+        np.isfinite(f00) & np.isfinite(f10) & np.isfinite(f11) & np.isfinite(f01)
+    )
+    case = (
+        (f00 >= level).astype(np.uint8)
+        | ((f10 >= level).astype(np.uint8) << 1)
+        | ((f11 >= level).astype(np.uint8) << 2)
+        | ((f01 >= level).astype(np.uint8) << 3)
+    )
+    active = finite & (case != 0) & (case != 15)
+    if not np.any(active):
+        return []
+    aj, lj, li = np.nonzero(active)
+    cases = case[aj, lj, li]
+    center_inside = (0.25 * (f00 + f10 + f11 + f01))[aj, lj, li]
+    gi = ii[aj].astype(np.int64) * sub + li.astype(np.int64)
+    gj = jj[aj].astype(np.int64) * sub + lj.astype(np.int64)
+    nx = int(xs.shape[0])
+    ny = int(ys.shape[0])
+    h_stride = (nx - 1) * sub
+    v_stride = (nx - 1) * sub + 1
+    n_horizontal = h_stride * ((ny - 1) * sub)
+    bottom = gj * h_stride + gi
+    top = (gj + 1) * h_stride + gi
+    left = n_horizontal + gj * v_stride + gi
+    right = n_horizontal + gj * v_stride + (gi + 1)
+    local = np.stack([bottom, right, top, left], axis=1)
+    pairs = _pair_segments(local, cases, center_inside)
+    if pairs.size == 0:
+        return []
+
+    points: dict[int, tuple[float, float]] = {}
+
+    def put(edge_ids: np.ndarray, x_vals: np.ndarray, y_vals: np.ndarray) -> None:
+        for edge, x_val, y_val in zip(edge_ids.tolist(), x_vals.tolist(), y_vals.tolist()):
+            points[int(edge)] = (float(x_val), float(y_val))
+
+    t = _interp_t(fine[aj, lj, li], fine[aj, lj, li + 1], level)
+    put(
+        bottom,
+        xf[aj, li] + t * (xf[aj, li + 1] - xf[aj, li]),
+        yf[aj, lj],
+    )
+    t = _interp_t(fine[aj, lj, li + 1], fine[aj, lj + 1, li + 1], level)
+    put(
+        right,
+        xf[aj, li + 1],
+        yf[aj, lj] + t * (yf[aj, lj + 1] - yf[aj, lj]),
+    )
+    t = _interp_t(fine[aj, lj + 1, li], fine[aj, lj + 1, li + 1], level)
+    put(
+        top,
+        xf[aj, li] + t * (xf[aj, li + 1] - xf[aj, li]),
+        yf[aj, lj + 1],
+    )
+    t = _interp_t(fine[aj, lj, li], fine[aj, lj + 1, li], level)
+    put(
+        left,
+        xf[aj, li],
+        yf[aj, lj] + t * (yf[aj, lj + 1] - yf[aj, lj]),
+    )
+
+    def point_of(edge: int) -> tuple[float, float]:
+        return points[edge]
+
+    return _chain_edge_pairs(pairs, point_of)

plot3/craft.py

@@ -0,0 +1,142 @@
+"""CRAFT remote seeding — ship the local plot3 source to the remote kernel.
+
+Mirrors ``tidy3.craft``: tar the package, bootstrap on the remote via
+``remote_run_``, install pandas if needed, register the plot3 IPython
+extension. Idempotent via content stamp.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import tarfile
+import time
+from pathlib import Path
+from typing import Callable
+
+__all__ = ["build_payload", "bootstrap_code", "seed"]
+
+_OK_PREFIX = "plot3 remote: OK"
+
+
+def _pkg_files() -> list[tuple[str, bytes]]:
+    pkg = Path(__file__).resolve().parent
+    files: list[tuple[str, bytes]] = []
+    for path in sorted(pkg.rglob("*")):
+        if not path.is_file():
+            continue
+        if path.suffix not in {".py", ".typed"} and path.name != "py.typed":
+            continue
+        if "__pycache__" in path.parts:
+            continue
+        rel = path.relative_to(pkg.parent).as_posix()  # plot3/...
+        files.append((rel, path.read_bytes()))
+    return files
+
+
+def build_payload() -> tuple[str, str]:
+    """Return (base64 tar.gz of the package, content stamp)."""
+    from plot3 import __version__
+
+    files = _pkg_files()
+    h = hashlib.sha256()
+    for name, data in files:
+        h.update(name.encode())
+        h.update(b"\0")
+        h.update(data)
+        h.update(b"\0")
+    stamp = f"{__version__}-{h.hexdigest()[:16]}"
+
+    buf = io.BytesIO()
+    now = int(time.time())
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        for name, data in files:
+            ti = tarfile.TarInfo(name)
+            ti.size = len(data)
+            ti.mtime = now
+            tar.addfile(ti, io.BytesIO(data))
+    return base64.b64encode(buf.getvalue()).decode("ascii"), stamp
+
+
+_BOOTSTRAP = r'''
+import base64 as _b64, io as _io, sys as _sys, tarfile as _tarfile
+from pathlib import Path as _Path
+_root = _Path.home() / ".plot3-src"
+_stampf = _root / ".stamp"
+_stamp = "%(stamp)s"
+try:
+    _fresh = _stampf.read_text().strip() == _stamp
+except Exception:
+    _fresh = False
+if not _fresh:
+    import shutil as _shutil
+    _root.mkdir(parents=True, exist_ok=True)
+    _shutil.rmtree(_root / "plot3", ignore_errors=True)
+    _buf = _io.BytesIO(_b64.b64decode("%(payload)s"))
+    with _tarfile.open(fileobj=_buf, mode="r:gz") as _tar:
+        try:
+            _tar.extractall(_root, filter="data")
+        except TypeError:
+            _tar.extractall(_root)
+    _stampf.write_text(_stamp)
+if str(_root) not in _sys.path:
+    _sys.path.insert(0, str(_root))
+try:
+    import pandas as _pd  # noqa: F401
+except Exception:
+    import subprocess as _sp
+    print("plot3 remote: installing pandas (first time only)...", flush=True)
+    _r = _sp.run(["uv", "pip", "install", "pandas"], capture_output=True, text=True)
+    if _r.returncode != 0:
+        _r = _sp.run([_sys.executable, "-m", "pip", "install", "pandas"],
+                     capture_output=True, text=True)
+    if _r.returncode != 0:
+        print((_r.stdout or "")[-600:])
+        print((_r.stderr or "")[-600:])
+        raise RuntimeError("plot3 seed: pandas install failed")
+    import importlib as _il
+    _il.invalidate_caches()
+if not _fresh and "plot3" in _sys.modules:
+    for _k in [_m for _m in list(_sys.modules)
+               if _m == "plot3" or _m.startswith("plot3.")]:
+        del _sys.modules[_k]
+import plot3 as _p3
+from IPython import get_ipython as _gi
+_ip = _gi()
+if _ip is not None:
+    from plot3.jupyter import register_plot3 as _reg
+    _reg(quiet=True, r_style=True)
+    try:
+        from plot3.jupyter import enable_r_style as _rstyle
+        _rstyle(_ip)
+    except Exception as _e:
+        print("plot3 remote: R-style masking warning: " + repr(_e), flush=True)
+print("plot3 remote: OK v" + _p3.__version__ + " (" + _stamp + ")")
+'''
+
+
+def bootstrap_code(payload: str, stamp: str) -> str:
+    return _BOOTSTRAP % {"payload": payload, "stamp": stamp}
+
+
+def seed(
+    remote_run: Callable[..., str],
+    *,
+    payload: str | None = None,
+    stamp: str | None = None,
+    max_chars: int = 12000,
+) -> tuple[bool, str]:
+    """Run the bootstrap via CRAFT's ``remote_run_``. Returns (ok, message)."""
+    if payload is None or stamp is None:
+        payload, stamp = build_payload()
+    code = bootstrap_code(payload, stamp)
+    try:
+        out = remote_run(code, max_chars=max_chars) or ""
+    except Exception as e:
+        return False, f"remote bootstrap did not run: {e}"
+    out = out.strip()
+    for line in out.splitlines():
+        if line.startswith(_OK_PREFIX):
+            return True, line.strip()
+    return False, (out[-1500:] if out else "no output from remote bootstrap")

plot3/encode.py

@@ -0,0 +1,68 @@
+"""Payload packing (uint16 quantize, delta, gzip)."""
+
+from __future__ import annotations
+
+import base64
+import gzip as _gzip
+
+import numpy as np
+
+def delta_u16(a: np.ndarray) -> np.ndarray:
+    """Column-wise delta mod 2^16 (lossless; tiny values on ordered data)."""
+    d = a.astype(np.int32)
+    d[1:] = (d[1:] - d[:-1]) % 65536
+    return d.astype("<u2")
+
+
+def pack_u16(q: np.ndarray, compress: bool) -> str:
+    """uint16 array -> base64; compressed = delta + byte-plane shuffle + gzip."""
+    if compress:
+        d = delta_u16(q).view(np.uint8).reshape(-1, 2)
+        raw = _gzip.compress(
+            np.ascontiguousarray(d[:, 0]).tobytes()
+            + np.ascontiguousarray(d[:, 1]).tobytes(),
+            6,
+        )
+    else:
+        raw = np.ascontiguousarray(q, dtype="<u2").tobytes()
+    return base64.b64encode(raw).decode("ascii")
+
+
+def pack_f32(v: np.ndarray, compress: bool) -> str:
+    raw = np.ascontiguousarray(v, dtype="<f4").tobytes()
+    if compress:
+        raw = _gzip.compress(raw, 6)
+    return base64.b64encode(raw).decode("ascii")
+
+
+def encode_norm(v: np.ndarray, lo: float, hi: float, *, quantize: bool,
+                 compress: bool) -> dict:
+    """Encode values normalized to [0,1] over [lo,hi] (u16 or f32)."""
+    span = (hi - lo) or 1.0
+    t = (np.asarray(v, dtype=np.float64) - lo) / span
+    if quantize:
+        q = np.round(np.clip(t, 0.0, 1.0) * 65535.0).astype("<u2")
+        return {"dtype": "u16", "b64": pack_u16(q, compress)}
+    return {"dtype": "f32", "b64": pack_f32(t.astype(np.float32), compress)}
+
+
+def encode_codes(codes: np.ndarray, compress: bool) -> dict:
+    q = np.ascontiguousarray(codes, dtype="<u2")
+    return {"dtype": "u16", "b64": pack_u16(q, compress), "raw": True}
+
+
+def pack_u8(values: np.ndarray, compress: bool) -> str:
+    """uint8 array -> base64 (optional gzip; no delta)."""
+    raw = np.ascontiguousarray(values, dtype=np.uint8).tobytes()
+    if compress:
+        raw = _gzip.compress(raw, 6)
+    return base64.b64encode(raw).decode("ascii")
+
+
+def pack_u32(values: np.ndarray, compress: bool) -> str:
+    """uint32 array -> base64 (optional gzip; no delta)."""
+    raw = np.ascontiguousarray(values, dtype="<u4").tobytes()
+    if compress:
+        raw = _gzip.compress(raw, 6)
+    return base64.b64encode(raw).decode("ascii")
+