regrender 0.1.0__py3-none-any.whl

regrender/__main__.py

@@ -0,0 +1,38 @@
+from argclz import AbstractParser
+from argclz.commands import parse_command_args
+
+from .main_probe import ProbeOptions
+from .main_register import RegisterOptions
+from .main_roi import RoiOptions
+
+
+class SetupOptions(AbstractParser):
+    DESCRIPTION = ('Pre-download the Allen CCF atlas so the first register/roi/probe run '
+                   'does not stall on a multi-minute download.')
+
+    def run(self):
+        from brainglobe_atlasapi import BrainGlobeAtlas
+
+        from ._app import printf
+
+        name = 'allen_mouse_10um'  # the resolution the app is built around (roi/probe assume 10 µm)
+        printf(f'fetching {name} (one-time, may take a few minutes)...')
+        BrainGlobeAtlas(name)  # downloads + caches if missing, no-op if already local
+        printf(f'{name} ready')
+
+
+def main():
+    parse_command_args(
+        usage='python -m regrender ...',
+        description='regrender cli usage',
+        parsers=dict(
+            register=RegisterOptions,
+            probe=ProbeOptions,
+            roi=RoiOptions,
+            setup=SetupOptions
+        )
+    )
+
+
+if __name__ == '__main__':
+    main()

regrender/_app.py

@@ -0,0 +1,326 @@
+"""Shared scaffolding for the napari reconstruction modes (``probe`` and ``roi``).
+
+Both modes step through registered serial sections, pick points that resolve to Allen CCF
+mm, paint atlas region boundaries / the region under the cursor, pick atlas regions to render,
+and shell out to a brainrender CLI. That common plumbing lives here; each mode subclasses
+:class:`SliceReconstructOptions` and supplies only its own image display + click semantics +
+render argv. The pure (GUI-free) coordinate/image helpers stay in :mod:`regrender._core`.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from collections import deque
+from pathlib import Path
+
+import numpy as np
+from argclz import AbstractParser, argument
+from neuralib.atlas.view import get_slice_view
+
+from regrender._core import region_name
+
+__all__ = ['SliceReconstructOptions', 'RegionPicker', 'TerminalLog', 'printf']
+
+_IMG_EXT = {'.tif', '.tiff', '.png', '.jpg', '.jpeg'}
+
+
+def _console():
+    """Cached rich Console for the terminal mirror (created lazily to keep import light)."""
+    global _CONSOLE
+    if _CONSOLE is None:
+        from rich.console import Console
+        _CONSOLE = Console()
+    return _CONSOLE
+
+
+_CONSOLE = None
+
+# level -> (panel HTML hex, rich terminal style)
+_LEVEL_STYLE = {
+    'error': ('#ff6b6b', 'bold red'),
+    'warning': ('#f2c14e', 'yellow'),
+    'save': ('#8bd450', 'green'),
+    'io': ('#56b6c2', 'cyan'),
+    'info': ('#d0d0d0', ''),
+}
+
+
+def _infer_level(msg: str) -> str:
+    m = str(msg).lower()
+    if any(k in m for k in ('fail', 'error', 'cannot', "n't", 'invalid')):
+        return 'error'
+    if any(k in m for k in ('missing', 'cancel', 'no points', 'nothing', 'not ', 'stale')):
+        return 'warning'
+    if any(k in m for k in ('saved', 'save', '->', 'wrote', 'written')):
+        return 'save'
+    if any(k in m for k in ('load', 'render', 'resum', 'projected')):
+        return 'io'
+    return 'info'
+
+
+def printf(msg: str, level: str | None = None) -> None:
+    """Consistent timestamped terminal output (rich). The single path for every terminal line —
+    CLI messages and the napari status mirror both go through here, so they read the same.
+    Level (hence color) is inferred from the text unless passed explicitly."""
+    from datetime import datetime
+
+    from rich.text import Text
+
+    msg = str(msg)
+    _, style = _LEVEL_STYLE[level or _infer_level(msg)]
+    line = Text()
+    line.append(datetime.now().strftime('%H:%M:%S') + ' ', style='dim')
+    line.append(msg, style=style)  # append is literal — no markup injection from msg
+    _console().print(line)
+
+
+class TerminalLog:
+    """Append-only rich-console view over a magicgui Label: ``status.value = msg`` appends a
+    timestamped, color-highlighted line (QLabel renders HTML) and scrolls like a terminal,
+    keeping the last ``maxlines`` messages. Level (hence color) is inferred from the message;
+    pass it explicitly with ``log.log(msg, 'error')`` when the heuristic isn't enough."""
+
+    def __init__(self, label, maxlines: int = 200, echo: bool = True):
+        self._label = label
+        self._lines: deque[str] = deque(maxlen=maxlines)
+        self._echo = echo  # also mirror each line to the terminal (persistent, copyable log)
+
+    def log(self, msg: str, level: str | None = None):
+        import html
+        from datetime import datetime
+
+        msg = str(msg)
+        level = level or _infer_level(msg)
+        hexc, _ = _LEVEL_STYLE[level]
+        ts = datetime.now().strftime('%H:%M:%S')
+
+        self._lines.append(
+            f'<span style="color:#6b7280">{ts}</span> '
+            f'<span style="color:{hexc}">{html.escape(msg)}</span>'
+        )
+        self._label.value = '<br>'.join(self._lines)
+
+        if self._echo:  # mirror to terminal via the shared printer
+            printf(msg, level)
+
+    @property
+    def value(self) -> str:
+        return '\n'.join(self._lines)
+
+    @value.setter
+    def value(self, msg: str):
+        self.log(msg)
+
+
+def region_table_html(region_colors: dict[str, str]) -> str:
+    """HTML table of regions to render; each acronym is a ``rdel:<acr>`` link to remove it."""
+    if not region_colors:
+        return 'no regions'
+    rows = ['<tr><th>region</th><th>color</th></tr>']
+    for acr, c in region_colors.items():
+        rows.append(f'<tr><td><a href="rdel:{acr}">{acr} ✕</a></td>'
+                    f'<td><font color="{c}">■</font> {c}</td></tr>')
+    return '<table border=1 cellspacing=0 cellpadding=3>' + ''.join(rows) + '</table>'
+
+
+# atlas regions to render as meshes; identical picker in both modes
+_REGION_COLORS = ['red', 'salmon', 'darkred', 'cyan', 'yellow', 'magenta',
+                  'lime', 'green', 'blue', 'orange', 'white', 'black']
+
+
+class RegionPicker:
+    """Filterable atlas-region picker + colored render list. ``.widgets`` go in the panel;
+    ``.colors`` is the ordered ``{acronym: color}`` map (render order = insertion order)."""
+
+    def __init__(self, structures):
+        from magicgui.widgets import ComboBox, Label, LineEdit, PushButton, Select
+        self._pairs = [(f"{a} — {structures[a]['name']}", a)
+                       for a in sorted(structures.acronym_to_id_map)]
+        self.colors: dict[str, str] = {}
+        self._search = LineEdit(label='filter')
+        self._select = Select(label='regions', choices=self._pairs)
+        self._select.native.setMinimumHeight(240)
+        self._color = ComboBox(label='color', choices=_REGION_COLORS, value='red')
+        self._add = PushButton(text='+ Add region(s)')
+        self._table = Label(value='no regions')
+        self._table.native.setOpenExternalLinks(False)
+
+        self._search.changed.connect(self._apply_filter)
+        self._add.changed.connect(self._add_regions)
+        self._table.native.linkActivated.connect(self._on_link)
+        self._refresh()
+
+    @property
+    def widgets(self) -> list:
+        return [self._search, self._select, self._color, self._add, self._table]
+
+    def _apply_filter(self, *_):
+        q = self._search.value.strip().lower()
+        self._select.choices = [p for p in self._pairs if q in p[0].lower()] if q else list(self._pairs)
+
+    def _refresh(self):
+        self._table.value = region_table_html(self.colors)
+
+    def _add_regions(self, *_):
+        for acr in self._select.value:
+            self.colors[acr] = self._color.value  # add or recolor
+        self._refresh()
+
+    def _on_link(self, href: str):
+        if href.startswith('rdel:'):
+            self.colors.pop(href[len('rdel:'):], None)
+            self._refresh()
+
+
+class SliceReconstructOptions(AbstractParser):
+    """Base for ``probe``/``roi``: shared CLI args + napari/render plumbing."""
+
+    directory: Path | None = argument(
+        '-D', '--directory', default=None,
+        help='folder of serial sections (steps through them; reads transformations/<stem>_transform.json)'
+    )
+
+    raw_image: Path | None = argument(
+        '-I', '--image', default=None, help='single registered histology image (alternative to -D)'
+    )
+
+    transform_dir: Path | None = argument(
+        '--transform-dir', default=None,
+        help='where the *_transform.json live (default: <image-dir>/transformations)'
+    )
+
+    output: Path | None = argument(
+        '-O', '--output', default=None, help='output points csv (default: <dir>/<mode default>)'
+    )
+
+    _IMG_EXT = _IMG_EXT
+
+    def _list_images(self, d: Path) -> list[Path]:
+        return sorted(p for p in Path(d).iterdir() if p.suffix.lower() in self._IMG_EXT)
+
+    def _transform_path(self, img: Path) -> Path:
+        return self._tdir / f'{img.stem}_transform.json'
+
+    def _resolve_paths(self, default_csv: str, *, require_transform: bool = True) -> list[Path]:
+        """Common run() prologue: resolve image(s), transform dir, output csv. Returns the file list.
+
+        ``require_transform=False`` for modes that label before registration exists (roi)."""
+        files = self._list_images(self.directory) if self.directory else []
+        if files and self.raw_image is None:
+            self.raw_image = files[0]
+        if self.raw_image is None:
+            raise ValueError('provide an image via -I/--image or a folder via -D/--directory')
+        base = self.raw_image.parent
+        self._tdir = self.transform_dir or base / 'transformations'
+        self._out = self.output or base / default_csv
+        if require_transform and not self._transform_path(self.raw_image).exists():
+            raise FileNotFoundError(
+                f'no native registration {self._transform_path(self.raw_image)} — '
+                f'register with `regrender register` first')
+        return files
+
+    # --- shared napari helpers --------------------------------------------------
+
+    @staticmethod
+    def make_status_log():
+        """A scrolling terminal-style status: a monospace ``Label`` + its :class:`TerminalLog`.
+        Returns ``(label_widget, TerminalLog)``; ``log.value = msg`` appends a line."""
+        from magicgui.widgets import Label
+        from qtpy.QtCore import Qt
+        from qtpy.QtWidgets import QSizePolicy
+        label = Label(value='')
+        label.native.setStyleSheet(
+            'font-family: Menlo, Consolas, monospace; font-size: 12px; '
+            'background: #11131a; padding: 6px;')  # per-line color comes from TerminalLog HTML
+        label.native.setWordWrap(True)
+        label.native.setTextFormat(Qt.RichText)
+        label.native.setAlignment(Qt.AlignLeft | Qt.AlignTop)  # fill from the top
+        label.native.setMinimumHeight(220)  # roomy console area
+        label.native.setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Expanding)  # grows with the dock
+        return label, TerminalLog(label)
+
+    @staticmethod
+    def make_view_cache():
+        """``get_views(plane, res) -> (reference_view, annotation_view)``, cached (volume load is slow)."""
+        views: dict = {}
+
+        def get_views(plane: str, res: int):
+            key = (plane, res)
+            if key not in views:
+                views[key] = (get_slice_view('reference', plane, resolution=res, check_latest=False),
+                              get_slice_view('annotation', plane, resolution=res, check_latest=False))
+            return views[key]
+
+        return get_views
+
+    @staticmethod
+    def make_hover(viewer, state, structures, highlight_layer):
+        """Region-name text overlay + filled highlight of the atlas region under the cursor.
+        Reads ``state['ann_img']`` / ``state['hover_id']``. Returns the mouse-move callback."""
+        def on_move(_v, event):
+            ann = state.get('ann_img')
+            if ann is None:
+                return
+            y, x = event.position
+            viewer.text_overlay.text = region_name(ann, structures, y, x)
+            rid = (int(ann[int(y), int(x)])
+                   if 0 <= y < ann.shape[0] and 0 <= x < ann.shape[1] else 0)
+            if rid != state.get('hover_id'):
+                state['hover_id'] = rid
+                highlight_layer.data = (ann == rid).astype(float) if rid else np.zeros(ann.shape)
+        return on_move
+
+    def launch_render(self, argv: list[str], status=None, msg: str = ''):
+        """Shell out to a brainrender CLI in a separate window (non-blocking).
+
+        The child inherits our terminal's stdout/stderr, so a crash is visible where regrender
+        was launched. brainrender's ``Scene`` re-checks the atlas version over the network (no
+        timeout, 5 retries) on every launch, stalling the render for minutes on a slow link — so
+        we disable that check in the child before running the CLI."""
+        if status is not None:
+            status.value = msg
+        module, *rest = argv
+        boot = (
+            'import runpy, sys, brainglobe_atlasapi.bg_atlas as b;'
+            'b.BrainGlobeAtlas.check_latest_version = lambda self, *a, **k: None;'
+            f'sys.argv = [{module!r}, *sys.argv[1:]];'
+            f'runpy.run_module({module!r}, run_name="__main__")'
+        )
+        subprocess.Popen([sys.executable, '-c', boot, *rest])
+
+    @staticmethod
+    def header(text):
+        from magicgui.widgets import Label
+        lbl = Label(value=text)
+        lbl.native.setStyleSheet('font-weight: bold; color: #88c0d0; padding-top: 6px;')
+        return lbl
+
+    _CH = {'R': 0, 'G': 1, 'B': 2}
+
+    @classmethod
+    def channel_view(cls, img, channel: str):
+        # show one RGB channel as grayscale (easier to see labels); pixel coords are unchanged
+        if channel == 'merge' or getattr(img, 'ndim', 0) != 3:
+            return img
+        idx = cls._CH.get(channel, 0)
+        return img[..., idx] if idx < img.shape[2] else img
+
+    @staticmethod
+    def srow(*ws):
+        from magicgui.widgets import Container
+        return Container(widgets=list(ws), layout='horizontal', labels=False)
+
+    @staticmethod
+    def add_scroll_dock(viewer, panel, name: str):
+        from qtpy.QtCore import Qt
+        from qtpy.QtWidgets import QScrollArea
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)  # panel fills the dock width; scrolls vertically when tall
+        scroll.setWidget(panel.native)
+        scroll.setMinimumWidth(360)
+        dock = viewer.window.add_dock_widget(scroll, area='right', name=name)
+        # start the dock wider (user can still drag it narrower down to the 360 minimum)
+        try:
+            viewer.window._qt_window.resizeDocks([dock], [460], Qt.Horizontal)
+        except Exception:  # noqa: BLE001 - private API; harmless if it moves/changes
+            pass

regrender/_core.py

@@ -0,0 +1,306 @@
+"""Pure, GUI-free building blocks shared across regrender modes.
+
+Everything here is side-effect-light and unit-testable without napari, so future
+modes (cell annotation, probe tracks, ...) can reuse the same transform/image/atlas
+helpers. The napari front-ends live in the ``main_*`` modules.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, TypedDict
+
+import cv2
+import imageio.v3 as iio
+import numpy as np
+import PIL.Image
+from neuralib.atlas.ccf.matrix import SLICE_DIMENSION_10um
+from neuralib.atlas.typing import PLANE_TYPE
+
+# whole-slide scans routinely exceed Pillow's 0.18 GPixel decompression-bomb cap; the
+# files are our own, not untrusted uploads
+PIL.Image.MAX_IMAGE_PIXELS = None
+
+__all__ = [
+    'read_oriented', 'rotate', 'to_uint8', 'boundary_mask', 'region_name',
+    'estimate_transform', 'save_transform', 'apply_transformation',
+    'plane_point_to_ccf_mm', 'ccf_mm_to_plane_point',
+    'raw_points_to_atlas', 'TransformMeta', 'load_transform',
+]
+
+
+# --- transform meta --------------------------------------------------
+
+class TransformMeta(TypedDict):
+    """Schema of a ``*_transform.json`` — the histology→atlas registration written by
+    ``save_transform`` and consumed by the probe/roi modes. ``rotate``/``flip_lr``/``flip_ud``
+    record the preprocessing so raw points can be replayed into atlas space."""
+    matrix: list[list[float]]
+    """3x3 homography (resized-slice -> atlas-plane pixels)"""
+    plane: PLANE_TYPE
+    """cutting plane, selects the resize dimension"""
+    resolution: int
+    """atlas resolution (um)"""
+    slice_index: int
+    """voxel plane index the slice was registered to"""
+    dw: int
+    """resize width the matrix was fit on (SLICE_DIMENSION_10um[plane])"""
+    dh: int
+    """resize height the matrix was fit on"""
+    rotate: float
+    """rotation (deg) applied before resize/matrix, for replay"""
+    flip_lr: bool
+    """left-right flip applied before rotate, for replay"""
+    flip_ud: bool
+    """up-down flip applied before flip_lr, for replay"""
+    contrast: list[float] | None
+    """(lo, hi) window used for uint8 display, if any"""
+    slice_xy: list[list[float]]
+    """[N, 2] (x, y) points picked on the resized slice"""
+    atlas_xy: list[list[float]]
+    """[N, 2] matched (x, y) points picked on the atlas plane"""
+
+
+def load_transform(path: Path) -> TransformMeta:
+    """Read and parse a ``*_transform.json``."""
+    return json.loads(Path(path).read_text())
+
+
+# --- image preprocessing ---------------------------------------------------
+
+def read_oriented(path: Path, flip_lr: bool = False, flip_ud: bool = False) -> np.ndarray:
+    """read an image, normalize channel-first tiffs to (H, W, C), and apply flips"""
+    img = iio.imread(path)
+    if img.ndim == 3 and img.shape[0] in (3, 4) and img.shape[-1] not in (3, 4):
+        img = np.moveaxis(img, 0, -1)  # (C, H, W) -> (H, W, C)
+    if flip_ud:
+        img = np.flipud(img)
+    if flip_lr:
+        img = np.fliplr(img)
+    return img
+
+
+def rotate(img: np.ndarray, deg: float) -> np.ndarray:
+    """rotate about the image center, keeping the original shape"""
+    if not deg:
+        return img
+    h, w = img.shape[:2]
+    m = cv2.getRotationMatrix2D((w / 2, h / 2), deg, 1.0)
+    return cv2.warpAffine(img, m, (w, h))
+
+
+def to_uint8(img: np.ndarray, contrast: tuple[float, float] | None = None) -> np.ndarray:
+    """map to uint8 using a (lo, hi) contrast window, else full min-max"""
+    img = np.asarray(img, dtype=float)
+    lo, hi = contrast if contrast is not None else (float(img.min()), float(img.max()))
+    return (np.clip((img - lo) / ((hi - lo) or 1.0), 0, 1) * 255).astype(np.uint8)
+
+
+# --- atlas annotation ------------------------------------------------------
+
+def boundary_mask(ann: np.ndarray) -> np.ndarray:
+    """region boundaries = pixels where the annotation id changes vs its right/down neighbour"""
+    b = np.zeros(ann.shape, dtype=float)
+    b[:, :-1] = np.maximum(b[:, :-1], ann[:, :-1] != ann[:, 1:])
+    b[:-1, :] = np.maximum(b[:-1, :], ann[:-1, :] != ann[1:, :])
+    return b
+
+
+def region_name(ann: np.ndarray | None, structures: Any, y: float, x: float) -> str:
+    """acronym/name of the atlas region at (y, x) in the annotation plane, '' if none"""
+    if ann is None or not (0 <= y < ann.shape[0] and 0 <= x < ann.shape[1]):
+        return ''
+    rid = int(ann[int(y), int(x)])
+    if rid == 0:
+        return ''
+    try:
+        s = structures[rid]
+        return f"{s['acronym']} — {s['name']}"
+    except KeyError:
+        return f'id {rid}'
+
+
+# --- transform -------------------------------------------------------------
+
+def estimate_transform(slice_xy: np.ndarray, atlas_xy: np.ndarray, *, affine: bool = False) -> np.ndarray:
+    """Estimate the 3x3 matrix mapping histology (slice) points onto atlas points.
+
+    Matches ``cv2.warpPerspective`` convention: the matrix warps the slice into atlas space.
+
+    :param slice_xy: ``Array[float, [N, 2]]`` (x, y) points on the (resized) histology slice.
+    :param atlas_xy: ``Array[float, [N, 2]]`` matched (x, y) points on the atlas plane.
+    :param affine: estimate an affine (6 DOF) instead of projective (8 DOF) transform.
+    :return: ``Array[float64, [3, 3]]``
+    """
+    slice_xy = np.asarray(slice_xy, dtype=np.float64)
+    atlas_xy = np.asarray(atlas_xy, dtype=np.float64)
+    if slice_xy.shape != atlas_xy.shape:
+        raise ValueError(f'point count mismatch: {slice_xy.shape} vs {atlas_xy.shape}')
+
+    if affine:
+        if len(slice_xy) < 3:
+            raise ValueError('affine transform needs >=3 matched point pairs')
+        m, _ = cv2.estimateAffine2D(slice_xy, atlas_xy)
+        return np.vstack([m, [0, 0, 1]]).astype(np.float64)
+
+    if len(slice_xy) < 4:
+        raise ValueError('projective transform needs >=4 matched point pairs')
+
+    m, _ = cv2.findHomography(slice_xy, atlas_xy)
+
+    return m.astype(np.float64)
+
+
+def save_transform(matrix: np.ndarray, *,
+                   output_dir: Path, name: str,
+                   plane: PLANE_TYPE, resolution: int,
+                   slice_index: int, dw: int, dh: int,
+                   slice_xy: np.ndarray, atlas_xy: np.ndarray,
+                   rotate: float = 0.0, flip_lr: bool = False, flip_ud: bool = False,
+                   contrast: tuple[float, float] | None = None) -> Path:
+    """Save the 3x3 matrix and metadata into a single ``.json``. Returns its path.
+
+    ``rotate``/``flip_lr``/``flip_ud`` record the preprocessing so the result can be
+    reproduced (raw -> flip -> rotate -> resize -> apply matrix) and the session resumed.
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    meta: TransformMeta = {
+        'matrix': np.asarray(matrix, dtype=float).tolist(),
+        'plane': plane,
+        'resolution': resolution,
+        'slice_index': int(slice_index),
+        'dw': int(dw),
+        'dh': int(dh),
+        'rotate': float(rotate),
+        'flip_lr': bool(flip_lr),
+        'flip_ud': bool(flip_ud),
+        'contrast': list(contrast) if contrast is not None else None,
+        'slice_xy': np.asarray(slice_xy, dtype=float).tolist(),
+        'atlas_xy': np.asarray(atlas_xy, dtype=float).tolist(),
+    }
+    js = output_dir / f'{name}_transform.json'
+    js.write_text(json.dumps(meta, indent=2))
+    return js
+
+
+def apply_transformation(img: np.ndarray, m: np.ndarray) -> np.ndarray:
+    h, w = img.shape[:2]
+    return cv2.warpPerspective(img, m, (w, h))
+
+
+# --- probe reconstruction --------------------------------------------------
+
+def plane_point_to_ccf_mm(
+        plane_num: float, x: float, y: float, *,
+        project_index: tuple[int, int, int],
+        resolution: int,
+        bregma_10um: tuple[int, int, int] = (540, 0, 570),
+) -> tuple[float, float, float]:
+    """A clicked atlas-plane pixel ``(x, y)`` on plane number ``plane_num`` -> bregma-relative
+    CCF ``(AP, DV, ML)`` in mm.
+
+    This is the inverse of ``neuralib.atlas.util.allen_to_brainrender_coord``, so a CSV of these
+    points feeds ``ProbeRenderCLI`` (the existing interpolation + brainrender) directly.
+
+    :param plane_num: voxel plane index the pixel sits on (``slice_index`` + tilt offset).
+    :param x: atlas-plane column (the view's ``project_index`` x axis).
+    :param y: atlas-plane row (the view's ``project_index`` y axis).
+    :param project_index: ``view.project_index`` — (plane, x, y) positions within (AP, DV, ML).
+    :param resolution: atlas resolution (µm).
+    :param bregma_10um: bregma in 10µm voxels, AP/DV/ML (``ALLEN_CCF_10um_BREGMA``).
+    """
+    pidx, xidx, yidx = project_index
+    idx = [0.0, 0.0, 0.0]
+    idx[pidx], idx[xidx], idx[yidx] = plane_num, x, y
+    ap, dv, ml = (v * resolution for v in idx)  # voxel -> µm (absolute)
+    bap, bdv, bml = (b * 10 for b in bregma_10um)  # 10µm voxel -> µm
+    return (bap - ap) / 1000, (dv - bdv) / 1000, (bml - ml) / 1000
+
+
+def ccf_mm_to_voxel(
+        ccf: tuple[float, float, float], *,
+        resolution: int = 10,
+        bregma_10um: tuple[int, int, int] = (540, 0, 570),
+) -> tuple[float, float, float]:
+    """Bregma-relative CCF ``(AP, DV, ML)`` mm -> absolute atlas voxel ``(AP, DV, ML)``.
+
+    Same index math as :func:`ccf_mm_to_plane_point` but without the ``project_index`` reorder,
+    so it feeds ``BrainGlobeAtlas.structure_from_coords`` directly (allen space ``ap, si, rl``).
+    """
+    ap_mm, dv_mm, ml_mm = ccf
+    bap, bdv, bml = (b * 10 for b in bregma_10um)  # 10µm voxel -> µm
+    return ((bap - ap_mm * 1000) / resolution,
+            (dv_mm * 1000 + bdv) / resolution,
+            (bml - ml_mm * 1000) / resolution)
+
+
+def shank_distances(pts: dict[tuple[int, str], tuple[float, float, float]]) -> list[tuple[int, float]]:
+    """Per-shank dorsal<->ventral euclidean distance (µm), from a ``{(shank, point): (AP, DV, ML) mm}``
+    map. Only shanks with both points are returned, sorted by shank number."""
+    out = []
+    for s in sorted({k for k, _ in pts}):
+        d, v = pts.get((s, 'dorsal')), pts.get((s, 'ventral'))
+        if d is not None and v is not None:
+            out.append((s, float(np.linalg.norm(np.array(v, float) - np.array(d, float))) * 1000))
+    return out
+
+
+def raw_points_to_atlas(
+        pts_xy: np.ndarray, *,
+        matrix: np.ndarray,
+        raw_shape: tuple[int, int],
+        plane: PLANE_TYPE,
+        rotate_deg: float = 0.0,
+        flip_lr: bool = False,
+        flip_ud: bool = False
+) -> np.ndarray:
+    """Forward-map raw-image ``(x, y)`` pixels into atlas-plane ``(x, y)`` pixels.
+
+    Replays register's preprocessing pipeline (read -> flip -> rotate -> resize-to-dim ->
+    matrix) on points, so ROIs labelled on the original histology land in the same atlas-plane
+    space ``plane_point_to_ccf_mm`` consumes. The matrix was fit on the image resized to
+    ``SLICE_DIMENSION_10um[plane]`` (see ``slice_transform_helper``), so resize happens here too.
+
+    :param pts_xy: ``Array[float, [N, 2]]`` (x, y) on the raw image.
+    :param matrix: 3x3 homography from the saved ``*_transform.json``.
+    :param raw_shape: ``(H, W)`` of the raw image file.
+    :param plane: cutting plane (selects the resize dimension).
+    :param rotate_deg: rotation recorded at registration (same convention as :func:`rotate`).
+    :return: ``Array[float64, [N, 2]]`` atlas-plane (x, y).
+    """
+    pts = np.asarray(pts_xy, dtype=np.float64).reshape(-1, 2)
+    h, w = raw_shape[:2]
+    x, y = pts[:, 0].copy(), pts[:, 1].copy()
+    if flip_lr:
+        x = (w - 1) - x
+    if flip_ud:
+        y = (h - 1) - y
+    if rotate_deg:
+        m = cv2.getRotationMatrix2D((w / 2, h / 2), rotate_deg, 1.0)  # same matrix warpAffine applies
+        xy = m @ np.vstack([x, y, np.ones_like(x)])
+        x, y = xy[0], xy[1]
+    dim = SLICE_DIMENSION_10um[plane]  # (width, height)
+    x = x * (dim[0] / w)
+    y = y * (dim[1] / h)
+    src = np.stack([x, y], axis=1).reshape(-1, 1, 2)
+    return cv2.perspectiveTransform(src, np.asarray(matrix, dtype=np.float64)).reshape(-1, 2)
+
+
+def ccf_mm_to_plane_point(
+        ccf: tuple[float, float, float], *,
+        project_index: tuple[int, int, int],
+        resolution: int,
+        bregma_10um: tuple[int, int, int] = (540, 0, 570),
+) -> tuple[float, float, float]:
+    """Inverse of :func:`plane_point_to_ccf_mm`: bregma-relative CCF ``(AP, DV, ML)`` mm ->
+    ``(plane_num, x, y)`` in atlas voxels. Lets a saved coordinate be re-placed on a slice
+    (the cross belongs on the slice whose ``plane_offset`` at ``(y, x)`` equals ``plane_num``).
+    """
+    ap_mm, dv_mm, ml_mm = ccf
+    bap, bdv, bml = (b * 10 for b in bregma_10um)  # 10µm voxel -> µm
+    idx = [(bap - ap_mm * 1000) / resolution,  # AP, DV, ML voxel indices
+           (dv_mm * 1000 + bdv) / resolution,
+           (bml - ml_mm * 1000) / resolution]
+    pidx, xidx, yidx = project_index
+    return idx[pidx], idx[xidx], idx[yidx]