vimol 0.1.1__tar.gz → 0.1.2__tar.gz

{vimol-0.1.1/src/vimol.egg-info → vimol-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vimol
-Version: 0.1.1
+Version: 0.1.2
 Summary: A terminal molecular viewer and editor using the Kitty graphics protocol
 Author: vimol contributors
 License-Expression: MIT
@@ -27,6 +27,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20
 Requires-Dist: moderngl>=5.6
+Requires-Dist: numba>=0.59
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Dynamic: license-file
@@ -54,7 +55,11 @@ available. MIT licensed.
 ![C60 spinning in the terminal, rendered by vimol](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/spin.gif)
 
 `vimol` with no file opens this bundled C60 demo. Drag to rotate, scroll to
-zoom, hover an atom to identify it, `m` to measure distances/angles/dihedrals.
+zoom, hover an atom to identify it, `m` to measure distances/angles/dihedrals
+— with more than one structure loaded, a live column tracks it in a
+comparison table next to the structure list, evaluated for every loaded
+structure at once; move on to a different measurement (or a different frame)
+and it locks in as its own column (click a column's `×` to remove it).
 Editing is on by default: `a` to append (grow fragments, swap elements — the
 status-bar pills pick the element and geometry), option-drag to draw bonds,
 `x` to delete, `c` to relax clashes, `u` to undo, `s` to save. `?` lists

{vimol-0.1.1 → vimol-0.1.2}/README.md

@@ -21,7 +21,11 @@ available. MIT licensed.
 ![C60 spinning in the terminal, rendered by vimol](https://raw.githubusercontent.com/hanimustafa/vimol/main/docs/media/spin.gif)
 
 `vimol` with no file opens this bundled C60 demo. Drag to rotate, scroll to
-zoom, hover an atom to identify it, `m` to measure distances/angles/dihedrals.
+zoom, hover an atom to identify it, `m` to measure distances/angles/dihedrals
+— with more than one structure loaded, a live column tracks it in a
+comparison table next to the structure list, evaluated for every loaded
+structure at once; move on to a different measurement (or a different frame)
+and it locks in as its own column (click a column's `×` to remove it).
 Editing is on by default: `a` to append (grow fragments, swap elements — the
 status-bar pills pick the element and geometry), option-drag to draw bonds,
 `x` to delete, `c` to relax clashes, `u` to undo, `s` to save. `?` lists

{vimol-0.1.1 → vimol-0.1.2}/pyproject.toml

@@ -37,7 +37,11 @@ classifiers = [
 # moderngl is a hard dependency (~120 KB of wheels): the GL backend is always
 # available, and `backend="auto"` still falls back to the CPU raycaster at
 # runtime wherever no OpenGL context can be created (headless boxes, clusters).
-dependencies = ["numpy>=1.20", "moderngl>=5.6"]
+# numba compiles that CPU raycaster's inner loop (_render_fast) to machine
+# code: ~10-25x faster CPU rendering, bit-identical output. render.py still
+# tolerates numba being uninstalled/uncompilable (falls back to the pure-numpy
+# path) since it's a best-effort JIT, not because it's meant to be omitted.
+dependencies = ["numpy>=1.20", "moderngl>=5.6", "numba>=0.59"]
 
 [project.optional-dependencies]
 test = ["pytest>=7"]

{vimol-0.1.1 → vimol-0.1.2}/src/vimol/__init__.py

@@ -33,7 +33,7 @@ from . import elements
 from . import templates
 from . import editor
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __all__ = [
     "Molecule", "VectorField", "Camera", "Renderer", "Style", "Scene", "MoleculeWidget",

vimol-0.1.2/src/vimol/_render_fast.py

@@ -0,0 +1,418 @@
+"""Numba-compiled inner loop for the CPU raycaster.
+
+The numpy renderer (``render.py``) vectorizes per primitive over its
+screen-space bounding box: every sphere/cylinder costs ~40 full-box array
+passes, most of them over pixels that fail the z-test, plus thousands of
+per-call overheads per frame. That is a structural ceiling -- measured
+~130 ms/frame for C60 at 2560x1440.
+
+This module compiles the same impostor math to machine code (per-pixel loops
+with early z-rejection *before* shading, the way PyMOL's C++ ray tracer and
+every other compiled rasterizer do it), which measures 10-25x faster. numba
+is a hard dependency (see pyproject.toml), but this module still degrades
+gracefully if it's ever missing or fails to compile on some platform:
+``ready()`` stays False and ``render.py``'s numpy path runs unchanged.
+
+BIT-PARITY CONTRACT: the kernels below mirror render.py's numpy operations
+one-for-one -- same dtypes (float32 per-pixel math, float64 screen setup),
+same operation order and association, same scalar casts (numpy converts a
+python-float scalar to float32 when it meets a float32 array; typed numpy
+float64 scalars promote instead -- both cases are reproduced explicitly).
+``tests/test_render_fast.py`` verifies the output is bit-identical to the
+numpy path -- run it after touching either side of the contract.
+"""
+from __future__ import annotations
+
+import os
+import threading
+
+import numpy as np
+
+# numba's disk cache (cache=True below) defaults to __pycache__ next to this
+# source file -- churn a sync client (Dropbox) then uploads on every
+# recompile. Redirect it to the user cache dir before numba is first
+# imported (the env var is read at numba import; if some other package
+# imported numba already, this is a harmless no-op and the default location
+# applies). setdefault, so an explicit NUMBA_CACHE_DIR always wins.
+os.environ.setdefault(
+    "NUMBA_CACHE_DIR",
+    os.path.join(os.path.expanduser("~"), ".cache", "vimol", "numba"))
+
+try:
+    from numba import njit, prange
+    _HAVE_NUMBA = True
+except Exception:                     # hard dependency, but degrade gracefully
+    _HAVE_NUMBA = False
+
+    def njit(*args, **kwargs):        # stub so module import never fails
+        def wrap(fn):
+            return fn
+        return wrap if not (args and callable(args[0])) else args[0]
+
+    def prange(*args):
+        return range(*args)
+
+
+# 0 = cold, 1 = compiling, 2 = ready, 3 = unavailable/failed
+_state = 0
+_lock = threading.Lock()
+# Set once the one compile attempt (by whichever caller -- warm_async's
+# thread or a direct warm_sync() caller -- got there first) finishes, success
+# or failure. Callers that lost the race to start it wait on this instead of
+# calling the compile routine themselves: numba's dispatcher is not safe to
+# enter from two threads at once for the same not-yet-compiled function --
+# observed reliably (SIGABRT/SIGSEGV) when a second, unsynchronized caller
+# invoked the compile while warm_async's background thread was mid-compile.
+_done = threading.Event()
+
+
+def available() -> bool:
+    """numba importable on this machine (kernel may still be compiling)."""
+    return _HAVE_NUMBA
+
+
+def ready() -> bool:
+    """Kernel compiled and safe to call (first call triggers compilation)."""
+    return _state == 2
+
+
+def warm_async() -> None:
+    """Compile the kernel in a daemon thread so the first frames don't stall.
+
+    JIT compilation takes ~1-3 s once per process (cached on disk afterwards
+    where the package dir is writable). Frames rendered while this runs use
+    the numpy path; the renderer switches over the moment ready() flips.
+    """
+    if not _HAVE_NUMBA:
+        return
+    if not _claim():
+        return
+    threading.Thread(target=_run_once, daemon=True).start()
+
+
+def warm_sync(timeout: float | None = None) -> bool:
+    """Force the kernel to be ready (or known unavailable) before returning.
+
+    If nobody has started the compile yet, this thread does it (blocking).
+    If warm_async's background thread already claimed it, this waits for
+    that thread to finish instead of compiling again -- see the note on
+    ``_done`` above for why a second concurrent attempt is unsafe. Returns
+    ``ready()``. Used by callers (tests, the benchmark scripts) that need a
+    definite answer and can't rely on warm_async's fire-and-forget timing.
+    """
+    if not _HAVE_NUMBA:
+        return False
+    if _claim():
+        _run_once()
+    else:
+        _done.wait(timeout)
+    return ready()
+
+
+def _claim() -> bool:
+    """Atomically move state 0 -> 1. True for the one caller that must
+    actually run the compile; False for everyone else (already compiling,
+    ready, or failed)."""
+    global _state
+    with _lock:
+        if _state != 0:
+            return False
+        _state = 1
+        return True
+
+
+def _run_once() -> None:
+    global _state
+    try:
+        # (8, 8, 4) rgba: (H, W, 3) and (H, W, 4) C-contiguous buffers share
+        # one numba type (uint8 3d C), so this single call compiles the only
+        # signature both opaque and transparent frames use.
+        color = np.zeros((8, 8, 4), np.uint8)
+        zbuf = np.full((8, 8), -np.inf, np.float32)
+        bands = np.array([[0, 8]], np.int64)
+        sx = np.array([4.0], np.float64)
+        sy = np.array([4.0], np.float64)
+        sz = np.array([0.0], np.float64)
+        radii = np.array([0.5], np.float64)
+        acol = np.array([[0.5, 0.5, 0.5]], np.float32)
+        aflat = np.zeros(1, np.uint8)
+        order = np.array([0], np.int64)
+        barr = np.zeros((0, 14), np.float64)
+        bcol = np.zeros((0, 6), np.float32)
+        bflat = np.zeros(0, np.uint8)
+        render_frame(color, zbuf, True, bands,
+                     sx, sy, sz, radii, acol, aflat, order,
+                     barr, bcol, bflat,
+                     10.0, 4.0, 4.0,
+                     0.3, 0.5, 0.7, -0.3, -0.5, 0.6, 0.4, 0.5, 0.7,
+                     0.28, 0.25, 0.55, 0.55, -1.0, 2.0, 5)
+        _state = 2
+    except Exception:
+        _state = 3
+    finally:
+        _done.set()
+
+
+# ---------------------------------------------------------------------------
+# compiled kernels
+# ---------------------------------------------------------------------------
+@njit(inline="always")
+def _shade_pixel(color, y, x, alpha_on, depth, nx, ny, nz,
+                 ar, ag, ab, flat,
+                 l0, l1, l2, f0, f1, f2, hv0, hv1, hv2,
+                 ambient, fill_w, spec_w, depth_cue, zmin, zspan, n_squares):
+    """Shade one winning fragment and write color/alpha/depth.
+
+    ``color`` is (H, W, 3) opaque or (H, W, 4) rgba; ``alpha_on`` means the
+    4th channel exists and coverage is written there. Mirrors
+    render.shade_write's per-element op sequence (see module docstring).
+    nx/ny/nz/ar..ab/depth are float32; the light scalars are float64
+    python-side values that numpy would have cast to float32 at each use --
+    the casts here make that explicit.
+    """
+    if flat:
+        if depth_cue > 0.0:
+            fog = (depth - np.float32(zmin)) * np.float32(1.0 / zspan)
+            if fog < np.float32(0.0):
+                fog = np.float32(0.0)
+            if fog > np.float32(1.0):
+                fog = np.float32(1.0)
+            fog *= np.float32(depth_cue)
+            fog += np.float32(1.0 - depth_cue)
+            rr = ar * fog
+            rr *= np.float32(255.0)
+            gg = ag * fog
+            gg *= np.float32(255.0)
+            bb = ab * fog
+            bb *= np.float32(255.0)
+        else:
+            rr = min(ar, np.float32(1.0)) * np.float32(255.0)
+            gg = min(ag, np.float32(1.0)) * np.float32(255.0)
+            bb = min(ab, np.float32(1.0)) * np.float32(255.0)
+    else:
+        diff = nx * np.float32(l0) + ny * np.float32(l1) + nz * np.float32(l2)
+        if diff < np.float32(0.0):
+            diff = np.float32(0.0)
+        dfill = nx * np.float32(f0) + ny * np.float32(f1) + nz * np.float32(f2)
+        if dfill < np.float32(0.0):
+            dfill = np.float32(0.0)
+        dh = nx * np.float32(hv0) + ny * np.float32(hv1) + nz * np.float32(hv2)
+        if dh < np.float32(0.0):
+            dh = np.float32(0.0)
+        # _fast_pow for a power-of-two exponent: x*x then repeated squaring,
+        # identical rounding sequence to the numpy version.
+        spec = dh
+        for _ in range(n_squares):
+            spec *= spec
+        spec *= np.float32(spec_w)
+        diff += np.float32(ambient)
+        dfill *= np.float32(fill_w)
+        diff += dfill
+        if depth_cue > 0.0:
+            fog = (depth - np.float32(zmin)) * np.float32(1.0 / zspan)
+            if fog < np.float32(0.0):
+                fog = np.float32(0.0)
+            if fog > np.float32(1.0):
+                fog = np.float32(1.0)
+            fog *= np.float32(depth_cue)
+            fog += np.float32(1.0 - depth_cue)
+            diff *= fog
+            spec *= fog
+        rr = ar * diff
+        rr += spec
+        gg = ag * diff
+        gg += spec
+        bb = ab * diff
+        bb += spec
+        if rr > np.float32(1.0):
+            rr = np.float32(1.0)
+        if gg > np.float32(1.0):
+            gg = np.float32(1.0)
+        if bb > np.float32(1.0):
+            bb = np.float32(1.0)
+        rr *= np.float32(255.0)
+        gg *= np.float32(255.0)
+        bb *= np.float32(255.0)
+    # np.copyto(..., casting="unsafe") / setitem float->uint8 truncates.
+    color[y, x, 0] = np.uint8(rr)
+    color[y, x, 1] = np.uint8(gg)
+    color[y, x, 2] = np.uint8(bb)
+    if alpha_on:
+        color[y, x, 3] = 255
+    return
+
+
+@njit(parallel=True, cache=True)
+def _render_kernel(color, zbuf, alpha_on, bands,
+                   sx, sy, sz, radii, acol, aflat, order,
+                   barr, bcol, bflat,
+                   zoom, ox_s, oy_s,
+                   l0, l1, l2, f0, f1, f2, hv0, hv1, hv2,
+                   ambient, fill_w, spec_w, depth_cue, zmin, zspan, n_squares):
+    """Raycast all bonds (list order) then all atoms (far-to-near order)
+    into their bands. Bands own disjoint rows, so prange is race-free; the
+    z-test makes per-pixel results order-independent up to the same ties the
+    numpy path resolves identically (same primitive order per band)."""
+    H, W = zbuf.shape
+    inv_zoom = 1.0 / zoom
+    iz32 = np.float32(1.0 / zoom)
+    niz32 = np.float32(-1.0 / zoom)
+    izz32 = np.float32(inv_zoom * inv_zoom)
+    n_bonds = barr.shape[0]
+
+    for band in prange(bands.shape[0]):
+        y_lo = bands[band, 0]
+        y_hi = bands[band, 1]
+
+        # -- bonds: capped-cylinder impostors (render._draw_cylinder_segment)
+        for k in range(n_bonds):
+            ax = barr[k, 0]
+            ay = barr[k, 1]
+            az = barr[k, 2]
+            ux = barr[k, 3]
+            uy = barr[k, 4]
+            uz = barr[k, 5]
+            L = barr[k, 6]
+            a2 = barr[k, 7]
+            radius = barr[k, 8]
+            sax = barr[k, 9]
+            say = barr[k, 10]
+            sbx = barr[k, 11]
+            sby = barr[k, 12]
+            srb = barr[k, 13]
+            if L < 1e-6 or radius <= 0.0:
+                continue
+            x0 = max(int(np.floor(min(sax, sbx) - srb)), 0)
+            x1 = min(int(np.ceil(max(sax, sbx) + srb)) + 1, W)
+            y0 = max(int(np.floor(min(say, sby) - srb)), y_lo)
+            y1 = min(int(np.ceil(max(say, sby) + srb)) + 1, y_hi)
+            if x0 >= x1 or y0 >= y1:
+                continue
+            ux32 = np.float32(ux)
+            uy32 = np.float32(uy)
+            uz32 = np.float32(uz)
+            b2c32 = np.float32(-2.0 * uz)
+            a2x4_32 = np.float32(a2 * 4.0)
+            half_a2_32 = np.float32(0.5 / a2) if abs(a2) >= 1e-9 else np.float32(0.0)
+            parallel = abs(a2) < 1e-9
+            inv_r32 = np.float32(1.0 / radius)
+            r2_32 = np.float32(radius * radius)
+            half_L32 = np.float32(0.5 * L)
+            L32 = np.float32(L)
+            az32 = np.float32(az)
+            ey_off32 = np.float32(oy_s / zoom - ay)
+            ox32 = np.float32(ox_s)
+            ax32 = np.float32(ax)
+            flat = bflat[k]
+            car, cag, cab = bcol[k, 0], bcol[k, 1], bcol[k, 2]
+            cbr, cbg, cbb = bcol[k, 3], bcol[k, 4], bcol[k, 5]
+            for y in range(y0, y1):
+                ey = np.float32(y) * niz32 + ey_off32
+                eyey = ey * ey
+                eyuy = ey * uy32
+                for x in range(x0, x1):
+                    ex = (np.float32(x) - ox32) * iz32 - ax32
+                    A0 = ex * ux32 + eyuy
+                    c2 = ex * ex + eyey - A0 * A0 - r2_32
+                    if parallel:
+                        if c2 > np.float32(0.0):
+                            continue
+                        s = np.float32(0.0)
+                    else:
+                        b2 = A0 * b2c32
+                        disc = b2 * b2 - a2x4_32 * c2
+                        if disc < np.float32(0.0):
+                            continue
+                        sq = np.sqrt(disc)
+                        s = (sq - b2) * half_a2_32
+                    zview = s + az32
+                    t = A0 + s * uz32
+                    if t < np.float32(0.0) or t > L32:
+                        continue
+                    if zview <= zbuf[y, x]:
+                        continue
+                    nx = (ex - t * ux32) * inv_r32
+                    ny = (ey - t * uy32) * inv_r32
+                    nz = (s - t * uz32) * inv_r32
+                    if t < half_L32:
+                        ar, ag, ab = car, cag, cab
+                    else:
+                        ar, ag, ab = cbr, cbg, cbb
+                    zbuf[y, x] = zview
+                    _shade_pixel(color, y, x, alpha_on, zview, nx, ny, nz,
+                                 ar, ag, ab, flat,
+                                 l0, l1, l2, f0, f1, f2, hv0, hv1, hv2,
+                                 ambient, fill_w, spec_w, depth_cue, zmin, zspan,
+                                 n_squares)
+
+        # -- atoms: sphere impostors (render.draw_band's atom loop)
+        for oi in range(order.shape[0]):
+            a = order[oi]
+            r = radii[a]
+            if r <= 0.0:
+                continue
+            sr = r * zoom
+            if sr < 0.5:
+                sr = 0.5
+            cx = sx[a]
+            cy = sy[a]
+            cz = sz[a]
+            x0 = max(int(np.floor(cx - sr)), 0)
+            x1 = min(int(np.ceil(cx + sr)) + 1, W)
+            y0 = max(int(np.floor(cy - sr)), y_lo)
+            y1 = min(int(np.ceil(cy + sr)) + 1, y_hi)
+            if x0 >= x1 or y0 >= y1:
+                continue
+            cx32 = np.float32(cx)
+            cy32 = np.float32(cy)
+            cz32 = np.float32(cz)
+            sr2 = sr * sr                       # float64: d2 <= sr2 promotes
+            rr32 = np.float32(r * r)
+            inv_r = 1.0 / r
+            nxy32 = np.float32(inv_zoom * inv_r)
+            nz32 = np.float32(inv_r)
+            flat = aflat[a]
+            ar = acol[a, 0]
+            ag = acol[a, 1]
+            ab = acol[a, 2]
+            for y in range(y0, y1):
+                dyr = np.float32(y) - cy32
+                dyr2 = dyr * dyr
+                ny = dyr * np.float32(-inv_zoom * inv_r)
+                for x in range(x0, x1):
+                    dxr = np.float32(x) - cx32
+                    d2 = dxr * dxr + dyr2
+                    # numpy compares float32 d2 against the float64 scalar
+                    # sr*sr (typed numpy scalar promotes); mirror exactly.
+                    if not (d2 <= sr2):
+                        continue
+                    h2 = rr32 - d2 * izz32
+                    if h2 < np.float32(0.0):
+                        h2 = np.float32(0.0)
+                    hgt = np.sqrt(h2)
+                    depth = hgt + cz32
+                    if depth <= zbuf[y, x]:
+                        continue
+                    nx = dxr * nxy32
+                    nzv = hgt * nz32
+                    zbuf[y, x] = depth
+                    _shade_pixel(color, y, x, alpha_on, depth,
+                                 nx, ny, nzv, ar, ag, ab, flat,
+                                 l0, l1, l2, f0, f1, f2, hv0, hv1, hv2,
+                                 ambient, fill_w, spec_w, depth_cue, zmin, zspan,
+                                 n_squares)
+
+
+def render_frame(color, zbuf, alpha_on, bands,
+                 sx, sy, sz, radii, acol, aflat, order,
+                 barr, bcol, bflat,
+                 zoom, ox_s, oy_s,
+                 l0, l1, l2, f0, f1, f2, hv0, hv1, hv2,
+                 ambient, fill_w, spec_w, depth_cue, zmin, zspan, n_squares):
+    """Thin wrapper so _run_once and render.py share one call signature."""
+    _render_kernel(color, zbuf, alpha_on, bands,
+                   sx, sy, sz, radii, acol, aflat, order,
+                   barr, bcol, bflat,
+                   zoom, ox_s, oy_s,
+                   l0, l1, l2, f0, f1, f2, hv0, hv1, hv2,
+                   ambient, fill_w, spec_w, depth_cue, zmin, zspan, n_squares)

{vimol-0.1.1 → vimol-0.1.2}/src/vimol/app.py

@@ -71,6 +71,8 @@ def make_parser() -> argparse.ArgumentParser:
     p.add_argument("--backend", default="auto", choices=["auto", "cpu", "gl"],
                    help="rendering backend: numpy CPU raycaster, GPU (OpenGL), "
                         "or auto (GPU if a context can be created, else CPU)")
+    p.add_argument("--theme", default="auto", choices=["auto", "dark", "light"],
+                   help="chrome color theme; auto detects the terminal's own background")
     p.add_argument("--size", default="0x0", help="pixel size WxH for --render/--kitty (0=auto)")
     p.add_argument("--supersample", type=int, default=2, help="anti-aliasing factor for stills")
     p.add_argument("--rotate", nargs=2, type=float, metavar=("YAW", "PITCH"),
@@ -93,6 +95,23 @@ def make_parser() -> argparse.ArgumentParser:
     return p
 
 
+def _apply_theme_arg(args) -> None:
+    """--theme is the highest-precedence source in theme.resolve()'s ladder
+    (see docs/design/theme-and-aesthetics.md sec 2) -- implemented by setting
+    VIMOL_THEME before the Viewer is constructed, rather than adding a
+    parallel parameter to Viewer.__init__ for what VIMOL_THEME already
+    covers.
+
+    "auto" is the DEFAULT, i.e. "the user passed no --theme at all", so it
+    must leave VIMOL_THEME alone rather than clearing it -- clearing would
+    mean the env var only ever worked for direct Viewer() construction and
+    never for the CLI, silently deleting the ladder's second rung on every
+    plain `vimol file.xyz`.
+    """
+    if args.theme != "auto":
+        os.environ["VIMOL_THEME"] = args.theme
+
+
 def _print_info(mol: Molecule):
     print(f"name:    {mol.name}")
     print(f"formula: {mol.formula()}")
@@ -142,6 +161,7 @@ def _default_demo_path() -> Optional[str]:
 
 def main(argv: List[str] | None = None) -> int:
     args = make_parser().parse_args(argv)
+    _apply_theme_arg(args)
 
     if args.version:
         from . import __version__

{vimol-0.1.1 → vimol-0.1.2}/src/vimol/editor.py

@@ -99,43 +99,28 @@ def add_manual_bond(mol: Molecule, i: int, j: int, order: int = 1) -> bool:
     return True
 
 
-def measurement(mol: Molecule, sel: Sequence[int]) -> str:
-    """Render a live distance/angle/dihedral readout for an ordered pick list.
-
-    Pure and side-effect-free (no terminal, no widget state) so it is
-    testable on its own; the widget only owns *which* atoms are selected
-    (``measure_sel``), this just formats what they mean:
-
-    * < 2 atoms -> "" (nothing to report yet).
-    * 2 atoms   -> euclidean distance, 3 decimals.
-    * 3 atoms   -> the angle at the middle atom between it and the other two,
-      1 decimal.
-    * 4 atoms   -> the standard (signed) dihedral about the middle bond -- the
-      angle between the (i, j, k) and (j, k, l) planes, 1 decimal. The sign
-      convention is whatever ``atan2`` gives; callers that care about an
-      absolute value should take one themselves.
-
-    Extra picks beyond the first four are ignored (the widget itself never
-    lets the live selection grow past 4 -- see ``MoleculeWidget._measure_click``
-    -- but this stays defensive rather than raising on a longer sequence).
-    Indices are rendered with the same ``#idx`` convention as the hover
-    readout (:meth:`MoleculeWidget.atom_info`).
+def measure_value(mol: Molecule, sel: Sequence[int]) -> Optional[float]:
+    """The numeric core of :func:`measurement`: euclidean distance (Å, 2
+    atoms), angle at the middle atom (degrees, 3 atoms), or the standard
+    signed dihedral about the middle bond (degrees, 4 atoms). ``None`` for
+    fewer than 2 picks. Extra picks beyond the first four are ignored, same
+    defensiveness as :func:`measurement`. Pure and side-effect-free, so it is
+    reusable both for the live status-bar readout and for evaluating a
+    pinned measurement against other structures (``StructureSet.measure``).
     """
     n = len(sel)
     if n < 2:
-        return ""
+        return None
     pos = mol.positions
     if n == 2:
         i, j = sel[0], sel[1]
-        d = float(np.linalg.norm(pos[i] - pos[j]))
-        return f"d(#{i}–#{j}) = {d:.3f} Å"
+        return float(np.linalg.norm(pos[i] - pos[j]))
     if n == 3:
         i, j, k = sel[0], sel[1], sel[2]
         v1 = pos[i] - pos[j]
         v2 = pos[k] - pos[j]
         cos_a = float(np.dot(v1, v2) / (np.linalg.norm(v1) * np.linalg.norm(v2)))
-        angle = np.degrees(np.arccos(np.clip(cos_a, -1.0, 1.0)))
-        return f"∠(#{i}–#{j}–#{k}) = {angle:.1f}°"
+        return float(np.degrees(np.arccos(np.clip(cos_a, -1.0, 1.0))))
     i, j, k, l = sel[0], sel[1], sel[2], sel[3]
     b1 = pos[j] - pos[i]
     b2 = pos[k] - pos[j]
@@ -145,8 +130,32 @@ def measurement(mol: Molecule, sel: Sequence[int]) -> str:
     m1 = np.cross(n1, b2 / np.linalg.norm(b2))
     x = float(np.dot(n1, n2))
     y = float(np.dot(m1, n2))
-    phi = np.degrees(np.arctan2(y, x))
-    return f"φ(#{i}–#{j}–#{k}–#{l}) = {phi:.1f}°"
+    return float(np.degrees(np.arctan2(y, x)))
+
+
+def measurement(mol: Molecule, sel: Sequence[int]) -> str:
+    """Render a live distance/angle/dihedral readout for an ordered pick list.
+
+    Pure and side-effect-free (no terminal, no widget state) so it is
+    testable on its own; the widget only owns *which* atoms are selected
+    (``measure_sel``), this just formats what they mean -- see
+    :func:`measure_value` for the numbers themselves.
+
+    Indices are rendered with the same ``#idx`` convention as the hover
+    readout (:meth:`MoleculeWidget.atom_info`).
+    """
+    n = len(sel)
+    if n < 2:
+        return ""
+    value = measure_value(mol, sel)
+    if n == 2:
+        i, j = sel[0], sel[1]
+        return f"d(#{i}–#{j}) = {value:.3f} Å"
+    if n == 3:
+        i, j, k = sel[0], sel[1], sel[2]
+        return f"∠(#{i}–#{j}–#{k}) = {value:.1f}°"
+    i, j, k, l = sel[0], sel[1], sel[2], sel[3]
+    return f"φ(#{i}–#{j}–#{k}–#{l}) = {value:.1f}°"
 
 
 def _cap(mol: Molecule, center_idx: int, center: np.ndarray, dirs: np.ndarray,

{vimol-0.1.1 → vimol-0.1.2}/src/vimol/elements.py

@@ -92,6 +92,14 @@ _COLORS = {
 
 _DEFAULT_COLOR = (1.00, 0.41, 0.71)  # hot pink for unknown elements
 
+# Light-mode overrides for CPK entries that don't survive a light/white
+# terminal background -- only the near-white ones move; everything else in
+# _COLORS is saturated enough to read on either background.
+_LIGHT_OVERRIDES = {
+    "H": (0.55, 0.55, 0.58), "He": (0.45, 0.75, 0.78), "Ag": (0.45, 0.45, 0.45),
+    "Pt": (0.45, 0.45, 0.55), "Hg": (0.40, 0.40, 0.55),
+}
+
 
 def normalize_symbol(sym: str) -> str:
     """Normalize an element token to canonical capitalization (e.g. 'FE' -> 'Fe')."""
@@ -117,6 +125,21 @@ def element_color(sym: str) -> tuple:
     return _COLORS.get(normalize_symbol(sym), _DEFAULT_COLOR)
 
 
+def themed_base_colors(symbols, base_colors, theme: str):
+    """*base_colors* (N,3), with _LIGHT_OVERRIDES entries substituted where
+    *symbols* names one and *theme* is "light". Returns *base_colors*
+    unchanged (same array, no copy) for "dark" -- callers rely on this to
+    stay byte-identical to pre-theme rendering when the theme is dark."""
+    if theme != "light":
+        return base_colors
+    out = base_colors.copy()
+    for i, sym in enumerate(symbols):
+        override = _LIGHT_OVERRIDES.get(normalize_symbol(sym))
+        if override is not None:
+            out[i] = override
+    return out
+
+
 def element_name(sym: str) -> str:
     """Full element name, e.g. 'Carbon' for 'C'. Falls back to the symbol itself."""
     z = symbol_to_z(sym)