aind-ibl-ephys-alignment-preprocessing 0.4.2__tar.gz → 0.4.4__tar.gz

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.4.4 (2026-08-26)
+
+### Fix
+
+- **resolver**: accept asset names without the modality prefix
+
+## v0.4.3 (2026-08-26)
+
+### Fix
+
+- decide the frame relatively, and never warp onto a header stub
+- take the anatomical size from the caller, not the header stub
+
 ## v0.4.2 (2026-08-25)
 
 ### Fix

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aind-ibl-ephys-alignment-preprocessing
-Version: 0.4.2
+Version: 0.4.4
 Summary: Library to prepare histology and ephys for the IBL ephys alignment GUI
 Project-URL: Repository, https://github.com/AllenNeuralDynamics/aind-ibl-ephys-alignment-preprocessing/
 Project-URL: Issues, https://github.com/AllenNeuralDynamics/aind-ibl-ephys-alignment-preprocessing/issues

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/pyproject.toml

@@ -13,7 +13,7 @@ authors = [
 ]
 classifiers = ["Programming Language :: Python :: 3"]
 readme = "README.md"
-version = "0.4.2"
+version = "0.4.4"
 
 dependencies = [
   "numpy>=1.21.0",

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/src/aind_ibl_ephys_alignment_preprocessing/_async/histology.py

@@ -157,7 +157,7 @@ async def write_registration_channel_images_async(
 
 async def apply_ccf_inverse_tx_then_fix_domain_async(
     ccf_space_img_moving: ANTsImage,
-    pipeline_space_fixed_img: ANTsImage,
+    fixed_img: ANTsImage,
     correct_hist_domain_img: ANTsImage,
     asset_info: AssetInfo,
     limits: Limits,
@@ -165,8 +165,12 @@ async def apply_ccf_inverse_tx_then_fix_domain_async(
     **kwargs: Any,
 ) -> ANTsImage:
     """Async twin of :func:`~...histology.apply_ccf_inverse_tx_then_fix_domain`."""
+    if int(np.prod(fixed_img.shape)) <= 1:
+        raise ValueError(
+            f"fixed_img is a {fixed_img.shape} header stub; ants.apply_transforms would emit a "
+            "single-voxel volume. Build it with ants_warp_domain, not ants_domain_stub."
+        )
     pt_tx_str, pt_tx_inverted = asset_info.point_chain()
-    fixed = pipeline_space_fixed_img if frame.regrid_to_pipeline else correct_hist_domain_img
     interpolator = str(kwargs.get("interpolator", "linear"))
     # ``timed`` is a *sync* context manager, so it cannot share the ``async
     # with``. Nesting it inside the semaphore is also what we want: it then
@@ -175,7 +179,7 @@ async def apply_ccf_inverse_tx_then_fix_domain_async(
         with timed("histology.warp", interpolator=interpolator):
             ccf_img_in_hist_space: ANTsImage = await to_thread_logged(
                 ants.apply_transforms,
-                fixed=fixed,
+                fixed=fixed_img,
                 moving=ccf_space_img_moving,
                 transformlist=pt_tx_str,
                 whichtoinvert=pt_tx_inverted,
@@ -192,7 +196,7 @@ async def transform_ccf_to_image_space_async(
     asset_info: AssetInfo,
     refs: ReferenceVolumes,
     raw_hist_img: ANTsImage,
-    pipeline_hist_domain_img: ANTsImage,
+    fixed_img: ANTsImage,
     outputs: OutputDirs,
     limits: Limits,
     frame: RegistrationFrame,
@@ -201,7 +205,7 @@ async def transform_ccf_to_image_space_async(
     logger.info("[CCF Transform] Starting CCF template -> image space transform")
     ccf_in_hist_img = await apply_ccf_inverse_tx_then_fix_domain_async(
         refs.ccf_25,
-        pipeline_space_fixed_img=pipeline_hist_domain_img,
+        fixed_img=fixed_img,
         correct_hist_domain_img=raw_hist_img,
         asset_info=asset_info,
         limits=limits,
@@ -219,7 +223,7 @@ async def transform_ccf_labels_to_image_space_async(
     asset_info: AssetInfo,
     ref_paths: ReferencePaths,
     raw_hist_img: ANTsImage,
-    pipeline_hist_domain_img: ANTsImage,
+    fixed_img: ANTsImage,
     outputs: OutputDirs,
     limits: Limits,
     frame: RegistrationFrame,
@@ -234,7 +238,7 @@ async def transform_ccf_labels_to_image_space_async(
     unq_vals = np.load(str(ref_paths.ccf_labels_lateralized_25_unq_vals))["unique_labels"]
     ccf_labels_in_hist_img = await apply_ccf_inverse_tx_then_fix_domain_async(
         ccf_labels_lateralized_25,
-        pipeline_space_fixed_img=pipeline_hist_domain_img,
+        fixed_img=fixed_img,
         correct_hist_domain_img=raw_hist_img,
         asset_info=asset_info,
         limits=limits,

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/src/aind_ibl_ephys_alignment_preprocessing/_async/pipeline.py

@@ -101,6 +101,12 @@ async def _create_volumes_async(
     with timed("histology.ants_domain"):
         pipeline_img_ants = ants_warp_domain(pipeline_header, "registration-pipeline", warp_dtype)
         raw_img_ants = ants_domain_stub(base_header, "registration")
+        # The warp's ``fixed`` sets the output grid, so it must be full extent AND in
+        # the frame the transform expects. ``raw_img_ants`` stays a stub: it only
+        # stamps the true header back on after a pipeline-frame warp.
+        ccf_fixed_ants = (
+            pipeline_img_ants if frame.regrid_to_pipeline else ants_warp_domain(base_header, "registration", warp_dtype)
+        )
     logger.info(
         "[Histology] Starting parallel processing: %d additional channel(s), CCF template + labels transforms",
         num_additional,
@@ -121,14 +127,12 @@ async def _create_volumes_async(
             name="process-additional-channels",
         )
         tg.create_task(
-            transform_ccf_to_image_space_async(
-                asset_info, ref_imgs, raw_img_ants, pipeline_img_ants, out, limits, frame
-            ),
+            transform_ccf_to_image_space_async(asset_info, ref_imgs, raw_img_ants, ccf_fixed_ants, out, limits, frame),
             name="transform-ccf-template-to-image",
         )
         tg.create_task(
             transform_ccf_labels_to_image_space_async(
-                asset_info, ref_paths, raw_img_ants, pipeline_img_ants, out, limits, frame
+                asset_info, ref_paths, raw_img_ants, ccf_fixed_ants, out, limits, frame
             ),
             name="transform-ccf-labels-to-image",
         )
@@ -192,15 +196,17 @@ async def run_pipeline_async(config: PipelineConfig, max_workers: int = 40) -> l
     # Decided once, here, and handed to both branches: the volumes and the probe
     # points enter the same image-to-template transform, so they cannot disagree
     # about the frame it expects. The stub is header-only, so this is cheap.
-    raw_img_stub, _, _ = await to_thread_logged(
+    raw_img_stub, pipeline_img_stub, native_size = await to_thread_logged(
         base_and_pipeline_anatomical_stub,
         asset_info.zarr_volumes.registration,
         asset_info.zarr_volumes.metadata,
         asset_info.zarr_volumes.processing,
         opened_zarr=(node, zarr_metadata),
     )
-    reg_frame = resolve_registration_frame(asset_info.registration_dir_path, raw_img_stub)
-    del raw_img_stub
+    reg_frame = resolve_registration_frame(
+        asset_info.registration_dir_path, raw_img_stub, pipeline_img_stub, native_size
+    )
+    del raw_img_stub, pipeline_img_stub
 
     skip_ephys_msg = " (ephys disabled)" if config.skip_ephys else ""
     logger.info(

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/src/aind_ibl_ephys_alignment_preprocessing/co_asset_resolver.py

@@ -10,7 +10,7 @@ Design (verified live against 791094 and 781370 on 2026-07-09):
 
 * **Raw recordings** -- taken from the chosen sorting's ``provenance.data_assets``,
   which names the recording it was produced from. Falls back to a
-  ``name:ecephys_<mouseid>`` search filtered to ``tag:raw`` when a sorting
+  ``name:<mouseid>`` search filtered to ``tag:raw`` when a sorting
   carries no usable provenance, and warns when it does.
 * **SmartSPIM** -- taken from the Neuroglancer image-layer source, which *is* the
   acquisition the tracks were drawn on (unambiguous even when a mouse was imaged
@@ -146,18 +146,22 @@ class AssetResolution:
         return pairs
 
 
-# recording key: "<mouseid>_<date>_<time>" (the identity after the "ecephys_" prefix).
+# recording key: "<mouseid>_<date>_<time>" -- the session identity, which is the
+# whole asset name under the current AIND convention and follows an `ecephys_`
+# prefix under the older one. Both are in use, so the prefix is optional.
 # The suffix is optional because a re-uploaded raw keeps the key and adds to it
 # (`..._corrected`); anchoring the pattern hid those completely.
-_RAW_RE = re.compile(r"^ecephys_(?P<key>\d+_\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2})(?P<suffix>_.+)?$")
+_RAW_RE = re.compile(r"^(?:ecephys_)?(?P<key>\d+_\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2})(?P<suffix>_.+)?$")
 # Suffixes that mark a *derived* product rather than another upload of the raw.
 # Without this the relaxed pattern above would also accept `..._sorted_<ts>`.
-_DERIVED_SUFFIX_RE = re.compile(r"(?:^|_)(sorted|preprocessed|curated|nwb|oversplit|ccg)(?:[_-]|$)", re.IGNORECASE)
-# a well-formed pinned sorted_recording: ecephys_<key>_sorted_<sort_ts>
-_PINNED_RE = re.compile(
-    r"^ecephys_(?P<key>\d+_\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2})_sorted_"
-    r"(?P<ts>\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2})$"
+# `processed` is the behavior sibling of a session: with the modality prefix gone
+# it shares the recording key with the raw, so only the suffix separates them.
+_DERIVED_SUFFIX_RE = re.compile(
+    r"(?:^|_)(sorted|processed|preprocessed|curated|nwb|oversplit|ccg)(?:[_-]|$)", re.IGNORECASE
 )
+# a pinned sorted_recording is `<raw asset name>_sorted_<sort_ts>`, so the base is
+# whatever names the recording -- validated by _RAW_RE rather than re-spelled here.
+_PINNED_RE = re.compile(r"^(?P<base>.+)_sorted_(?P<ts>\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2})$")
 # extract the SmartSPIM acquisition name from an s3 image-source uri
 _SMARTSPIM_RE = re.compile(r"(SmartSPIM_[^/]+?)/")
 
@@ -215,8 +219,10 @@ def parse_pinned(sorted_recording: str) -> tuple[str, str] | None:
     Parameters
     ----------
     sorted_recording : str
-        A pinned sorting name, e.g.
-        ``ecephys_791094_2025-10-08_16-48-57_sorted_2026-04-24_13-43-00``.
+        A pinned sorting name: the raw asset's name plus ``_sorted_<ts>``, e.g.
+        ``ecephys_791094_2025-10-08_16-48-57_sorted_2026-04-24_13-43-00`` or,
+        without the modality prefix,
+        ``823993_2026-04-14_10-56-43_sorted_2026-04-15_12-04-52``.
 
     Returns
     -------
@@ -224,7 +230,12 @@ def parse_pinned(sorted_recording: str) -> tuple[str, str] | None:
         ``(recording_key, sort_timestamp)`` or None if malformed.
     """
     match = _PINNED_RE.match(sorted_recording)
-    return (match.group("key"), match.group("ts")) if match else None
+    if match is None:
+        return None
+    # The base has to name a recording, which also rejects a re-sorting
+    # (`..._sorted_<ts1>_sorted_<ts2>`): its base carries a derived suffix.
+    key = raw_key_of(match.group("base"))
+    return (key, match.group("ts")) if key is not None else None
 
 
 def _prefer_external(assets: list[CandidateAsset]) -> CandidateAsset:
@@ -316,9 +327,10 @@ def sibling_captures(asset: CandidateAsset, pool: list[CandidateAsset]) -> list[
 def raw_key_of(name: str) -> str | None:
     """Return the recording key an asset name denotes, if it names a raw upload.
 
-    ``None`` for anything that is not an ``ecephys_<key>`` asset, and for the
-    derived products that share the prefix (``..._sorted_<ts>`` and friends),
-    which the relaxed :data:`_RAW_RE` would otherwise accept.
+    ``None`` for anything that does not name a recording session, and for the
+    derived products that share the session name (``..._sorted_<ts>``,
+    ``..._processed_<ts>`` and friends), which the relaxed :data:`_RAW_RE` would
+    otherwise accept.
 
     Parameters
     ----------
@@ -377,7 +389,7 @@ def _resolve_raw(
     recording_keys : set[str]
         Recording keys the run needs a raw asset for.
     raw_candidates : list[CandidateAsset]
-        Result of the ``name:ecephys_<mouseid>`` search -- the fallback pool.
+        Result of the ``name:<mouseid>`` search -- the fallback pool.
     sortings : dict[str, CandidateAsset]
         Resolved sortings, keyed by recording key; the provenance source.
     pool : list[CandidateAsset]
@@ -421,7 +433,7 @@ def _resolve_raw(
 
         hits = by_name_key.get(key, [])
         if not hits:
-            warnings.append(f"{key}: no raw recording asset found (name:ecephys_{mouseid})")
+            warnings.append(f"{key}: no raw recording asset found (name:{mouseid})")
             continue
         chosen = _prefer_external(hits)
         if sorting is not None and sorting.source_assets:
@@ -487,7 +499,7 @@ def _resolve_pinned_sortings(
         date = key.split("_", 1)[1].rsplit("_", 1)[0]  # <mouseid>_<date>_<time> -> <date>
         # recording time is optional because sorting asset names sometimes drop it
         fuzzy = re.compile(
-            rf"^ecephys_{re.escape(mouseid)}_{re.escape(date)}"
+            rf"^(?:ecephys_)?{re.escape(mouseid)}_{re.escape(date)}"
             rf"(?:_\d{{2}}-\d{{2}}-\d{{2}})?_sorted_{re.escape(sort_ts)}$"
         )
         hits = [a for a in tagged_all if fuzzy.match(a.name)]
@@ -541,7 +553,7 @@ def resolve(
         User-pinned ``sorted_recording`` names (one per recording, from the
         manifest / bridge config).
     raw_candidates : list[CandidateAsset]
-        Result of ``name:ecephys_<mouseid>`` (state-ready).
+        Result of ``name:<mouseid>`` (state-ready).
     smartspim_candidates : list[CandidateAsset]
         Result of ``name:SmartSPIM_<mouseid>`` (NOT ``tag:<mouseid>`` -- processed
         SmartSPIM assets are sometimes tagged only ``[smartspim, processed]``).

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/src/aind_ibl_ephys_alignment_preprocessing/histology.py

@@ -585,7 +585,7 @@ def process_additional_channels_pipeline(
 
 def apply_ccf_inverse_tx_then_fix_domain(
     ccf_space_img_moving: ANTsImage,
-    pipeline_space_fixed_img: ANTsImage,
+    fixed_img: ANTsImage,
     correct_hist_domain_img: ANTsImage,
     asset_info: AssetInfo,
     frame: RegistrationFrame,
@@ -593,20 +593,23 @@ def apply_ccf_inverse_tx_then_fix_domain(
 ) -> ANTsImage:
     """Resample a CCF-space image into histology space, in the frame the transform expects.
 
-    A pipeline transform expects its input on the anchored geometry, so the
-    resample runs there and the header is relabelled afterwards -- the grid is
-    right, only its declared placement is the pipeline's. When a sidecar
-    documents the transform's own domain there is nothing to relabel: the
-    resample runs on the real histology grid directly.
+    *fixed_img* must already be the full-extent domain for that frame -- the
+    pipeline's anchored geometry when re-gridding, the volume's own otherwise.
+    A pipeline transform's output then carries the anchored header, so it is
+    relabelled afterwards from *correct_hist_domain_img*; the grid is right and
+    only its declared placement is the pipeline's. Honoring a sidecar leaves
+    nothing to relabel.
 
     Parameters
     ----------
     ccf_space_img_moving : ANTsImage
         Image in CCF/template space to move into histology space.
-    pipeline_space_fixed_img : ANTsImage
-        Histology geometry as the pipeline anchors it.
+    fixed_img : ANTsImage
+        Full-extent output domain, in the frame *frame* selected. Its size and
+        pixel type become the output's, so a header stub will not do.
     correct_hist_domain_img : ANTsImage
-        Reference histology image with correct spacing/origin/direction.
+        Carries the volume's true spacing/origin/direction for the relabel. Read
+        for its header only, so a stub is fine.
     asset_info : AssetInfo
         Registration chain paths.
     frame : RegistrationFrame
@@ -618,11 +621,22 @@ def apply_ccf_inverse_tx_then_fix_domain(
     -------
     ANTsImage
         Transformed image on the histology grid.
+
+    Raises
+    ------
+    ValueError
+        If *fixed_img* is a header stub. ``ants.apply_transforms`` takes the
+        output size from ``fixed``, so a 1x1x1 domain silently yields a
+        single-voxel volume rather than failing.
     """
+    if int(np.prod(fixed_img.shape)) <= 1:
+        raise ValueError(
+            f"fixed_img is a {fixed_img.shape} header stub; ants.apply_transforms would emit a "
+            "single-voxel volume. Build it with ants_warp_domain, not ants_domain_stub."
+        )
     pt_tx_str, pt_tx_inverted = asset_info.point_chain()
-    fixed = pipeline_space_fixed_img if frame.regrid_to_pipeline else correct_hist_domain_img
     ccf_space_img_in_hist_space: ANTsImage = ants.apply_transforms(
-        fixed=fixed,
+        fixed=fixed_img,
         moving=ccf_space_img_moving,
         transformlist=pt_tx_str,
         whichtoinvert=pt_tx_inverted,
@@ -667,7 +681,7 @@ def transform_ccf_to_image_space(
     asset_info: AssetInfo,
     refs: ReferenceVolumes,
     raw_hist_img: ANTsImage,
-    pipeline_hist_domain_img: ANTsImage,
+    fixed_img: ANTsImage,
     outputs: OutputDirs,
     frame: RegistrationFrame,
 ) -> None:
@@ -681,8 +695,8 @@ def transform_ccf_to_image_space(
         Reference volumes.
     raw_hist_img : ANTsImage
         Histology image with correct spatial domain.
-    pipeline_hist_domain_img : ANTsImage
-        Histology geometry as the pipeline anchors it.
+    fixed_img : ANTsImage
+        Full-extent output domain in the frame *frame* selected.
     outputs : OutputDirs
         Output directory tree.
     frame : RegistrationFrame
@@ -690,7 +704,7 @@ def transform_ccf_to_image_space(
     """
     ccf_in_hist_img = apply_ccf_inverse_tx_then_fix_domain(
         refs.ccf_25,
-        pipeline_space_fixed_img=pipeline_hist_domain_img,
+        fixed_img=fixed_img,
         correct_hist_domain_img=raw_hist_img,
         asset_info=asset_info,
         frame=frame,
@@ -706,7 +720,7 @@ def transform_ccf_labels_to_image_space(
     asset_info: AssetInfo,
     ref_paths: ReferencePaths,
     raw_hist_img: ANTsImage,
-    pipeline_hist_domain_img: ANTsImage,
+    fixed_img: ANTsImage,
     outputs: OutputDirs,
     frame: RegistrationFrame,
 ) -> None:
@@ -720,8 +734,8 @@ def transform_ccf_labels_to_image_space(
         Reference data paths.
     raw_hist_img : ANTsImage
         Histology image with correct spatial domain.
-    pipeline_hist_domain_img : ANTsImage
-        Histology geometry as the pipeline anchors it.
+    fixed_img : ANTsImage
+        Full-extent output domain in the frame *frame* selected.
     outputs : OutputDirs
         Output directory tree.
     frame : RegistrationFrame
@@ -734,7 +748,7 @@ def transform_ccf_labels_to_image_space(
     unq_vals = np.load(str(ref_paths.ccf_labels_lateralized_25_unq_vals))["unique_labels"]
     ccf_labels_in_hist_img = apply_ccf_inverse_tx_then_fix_domain(
         ccf_labels_lateralized_25,
-        pipeline_space_fixed_img=pipeline_hist_domain_img,
+        fixed_img=fixed_img,
         correct_hist_domain_img=raw_hist_img,
         asset_info=asset_info,
         frame=frame,

{aind_ibl_ephys_alignment_preprocessing-0.4.2 → aind_ibl_ephys_alignment_preprocessing-0.4.4}/src/aind_ibl_ephys_alignment_preprocessing/pipeline.py

@@ -80,13 +80,15 @@ def run_pipeline(config: PipelineConfig) -> list[ProcessResult]:
     # Header-only stubs, and one frame decision for the whole run: every CCF
     # product below enters the same image-to-template transform, so they must all
     # agree on the frame it expects its input in.
-    raw_img_stub, raw_img_stub_buggy, _ = base_and_pipeline_anatomical_stub(
+    raw_img_stub, raw_img_stub_buggy, native_size = base_and_pipeline_anatomical_stub(
         asset_info.zarr_volumes.registration,
         asset_info.zarr_volumes.metadata,
         asset_info.zarr_volumes.processing,
         opened_zarr=(node, zarr_metadata),
     )
-    reg_frame = resolve_registration_frame(asset_info.registration_dir_path, raw_img_stub)
+    reg_frame = resolve_registration_frame(
+        asset_info.registration_dir_path, raw_img_stub, raw_img_stub_buggy, native_size
+    )
 
     raw_img_path, base_header, pipeline_header, warp_dtype = write_registration_channel_images(
         asset_info,
@@ -99,6 +101,12 @@ def run_pipeline(config: PipelineConfig) -> list[ProcessResult]:
     # it is. Neither is read back from disk.
     pipeline_img_ants = ants_warp_domain(pipeline_header, "registration-pipeline", warp_dtype)
     raw_img_ants = ants_domain_stub(base_header, "registration")
+    # The warp's ``fixed`` sets the output grid, so it must be full extent AND in
+    # the frame the transform expects. ``raw_img_ants`` stays a stub: it only
+    # stamps the true header back on after a pipeline-frame warp.
+    ccf_fixed_ants = (
+        pipeline_img_ants if reg_frame.regrid_to_pipeline else ants_warp_domain(base_header, "registration", warp_dtype)
+    )
 
     scratch_root = Path(config.scratch_root) if config.scratch_root is not None else Path(tempfile.mkdtemp())
     scratch_root.mkdir(parents=True, exist_ok=True)
@@ -113,8 +121,8 @@ def run_pipeline(config: PipelineConfig) -> list[ProcessResult]:
         output_voxel_size_um=config.output_voxel_size_um,
         emit_qc=config.emit_qc,
     )
-    transform_ccf_to_image_space(asset_info, ref_imgs, raw_img_ants, pipeline_img_ants, out, reg_frame)
-    transform_ccf_labels_to_image_space(asset_info, ref_paths, raw_img_ants, pipeline_img_ants, out, reg_frame)
+    transform_ccf_to_image_space(asset_info, ref_imgs, raw_img_ants, ccf_fixed_ants, out, reg_frame)
+    transform_ccf_labels_to_image_space(asset_info, ref_paths, raw_img_ants, ccf_fixed_ants, out, reg_frame)
 
     processed_recordings: set[str] = set()
     processed_results: list[ProcessResult] = []

aind_ibl_ephys_alignment_preprocessing-0.4.4/src/aind_ibl_ephys_alignment_preprocessing/registration_frame.py

@@ -0,0 +1,229 @@
+"""Decide which physical frame an image-to-template transform expects its input in.
+
+The SmartSPIM pipeline registers an anatomical volume whose origin comes from an
+undocumented anchoring overlay, so points must be re-gridded onto that anchored
+geometry before the ANTs chain -- the behaviour ``aind_zarr_utils`` exists to
+mimic. Off-pipeline registrations ship a sidecar declaring the domain they were
+actually computed in; there the re-grid is wrong, and the declared domain is what
+must be honored. Getting this backwards is silent: the points still land
+somewhere, and the region names they pick up still read plausibly.
+
+Presence of a sidecar selects the branch, but the *domain it declares* is what is
+used, so a future off-pipeline capsule that adopts the anchored geometry stays
+correct without a change here.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import SimpleITK as sitk
+from aind_ants_transform_sidecar import Domain, load_package
+from aind_registration_utils.domains import ImageDomainAxisAligned, ImageHeader
+
+logger = logging.getLogger(__name__)
+
+#: Sidecar filenames looked for beside the image-to-template affine, in order.
+#: Deliberately narrower than the alignment GUI's list, which also tries
+#: ``<affine stem>.json``: a hard failure on a mismatched domain must not be
+#: reachable by an unrelated JSON that happens to sit next to the transform.
+REGISTRATION_SIDECAR_NAMES = (
+    "ls_to_template_transform_information.json",
+    "transform_information.json",
+)
+
+#: Floor for the plausibility check, in mm. The frame is chosen by which candidate
+#: is *nearer*, so this decides nothing -- it only rejects a sidecar that belongs to
+#: some other volume. Set well above any legitimate resampling disagreement (tens of
+#: microns) and well below the millimetres that separate the two frames.
+DOMAIN_SANITY_MM = 1.0
+
+#: Voxel-scaled companion to :data:`DOMAIN_SANITY_MM`, so a registration run at a
+#: very coarse resolution is not judged against a floor finer than its own grid.
+#: The larger of the two applies.
+DOMAIN_TOLERANCE_VOXELS = 4.0
+
+_AXES = ("L", "P", "S")
+
+
+@dataclass(frozen=True)
+class RegistrationFrame:
+    """Which frame the registration's input points must be expressed in.
+
+    Attributes
+    ----------
+    regrid_to_pipeline : bool
+        Re-grid points onto the pipeline's anchored geometry before the ANTs
+        chain. False when a sidecar shows the transform was trained in the
+        volume's own frame.
+    reason : str
+        Human-readable justification, recorded in logs.
+    sidecar_path : Path or None
+        The sidecar that decided it, when there was one.
+    """
+
+    regrid_to_pipeline: bool
+    reason: str
+    sidecar_path: Path | None = None
+
+
+def find_registration_sidecar(registration_dir: Path) -> Path | None:
+    """Return the transform sidecar in *registration_dir*, or None.
+
+    Parameters
+    ----------
+    registration_dir : Path
+        Directory holding the image-to-template transforms.
+
+    Returns
+    -------
+    Path or None
+        First matching sidecar, or None when the directory has none.
+    """
+    for name in REGISTRATION_SIDECAR_NAMES:
+        candidate = registration_dir / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def resolve_registration_frame(
+    registration_dir: Path,
+    native_image: sitk.Image,
+    pipeline_image: sitk.Image,
+    size_ijk: tuple[int, int, int],
+) -> RegistrationFrame:
+    """Decide whether points need the pipeline re-grid before the ANTs chain.
+
+    The choice is made *relatively* -- which of the two candidate frames the
+    sidecar's declared domain is nearer to -- so no threshold decides it and a
+    mis-sized tolerance cannot pick the wrong frame. The absolute check that
+    follows only asks whether the winner is plausible at all, which is what
+    catches a sidecar paired with a different volume.
+
+    Parameters
+    ----------
+    registration_dir : Path
+        Directory holding the image-to-template transforms.
+    native_image, pipeline_image : sitk.Image
+        The anatomical geometry as the volume's own header gives it, and as the
+        pipeline's anchoring overlay gives it. Only origin, spacing and
+        direction are read.
+    size_ijk : tuple[int, int, int]
+        Voxel counts in SimpleITK (x, y, z) order, shared by both. Required
+        rather than read from the images: these are header-only stubs, and
+        ``AnatomicalHeader.as_sitk_stub`` returns a 1x1x1 image whose own
+        ``GetSize`` would collapse each domain to a point.
+
+    Returns
+    -------
+    RegistrationFrame
+        The decision and why it was made.
+
+    Raises
+    ------
+    ValueError
+        If a sidecar declares no ``moving_domain``, or declares one that matches
+        neither candidate. Neither has a safe recovery: falling back to the
+        re-grid would apply the pipeline's compensation to a transform that is
+        not the pipeline's, which is the original defect.
+    """
+    # A manifest override still gets this branch. Which *asset* holds the
+    # transforms says nothing about which *frame* they were trained in -- a
+    # re-registration run with ``pipeline=True`` would be anchored too -- so the
+    # sidecar is the only evidence, and its absence means the pipeline's
+    # convention. Do not reach for ``has_registration_override`` here.
+    sidecar_path = find_registration_sidecar(registration_dir)
+    if sidecar_path is None:
+        return RegistrationFrame(
+            regrid_to_pipeline=True,
+            reason=f"no transform sidecar in {registration_dir}; assuming a pipeline registration",
+        )
+
+    sidecar = load_package(sidecar_path.read_text())
+    moving = sidecar.moving_domain
+    if moving is None:
+        raise ValueError(
+            f"{sidecar_path} declares no moving_domain. A sidecar means the transform is off-pipeline, "
+            "so the pipeline re-grid would be wrong, but without a domain there is nothing to honor "
+            "instead. Regenerate the sidecar."
+        )
+
+    candidates = {
+        "native": _domain_from_image(native_image, size_ijk),
+        "pipeline": _domain_from_image(pipeline_image, size_ijk),
+    }
+    distances = {name: _bbox_distance(moving, d) for name, d in candidates.items()}
+    winner = min(distances, key=lambda name: distances[name])
+
+    # Both frames describe the same acquisition, so an exact tie means the
+    # anchoring overlay was a no-op and the branches are indistinguishable.
+    tolerance = _sanity_tolerance(moving, candidates[winner])
+    if distances[winner] > tolerance:
+        raise ValueError(
+            f"{sidecar_path} moving_domain matches neither frame of the anatomical image it is paired with.\n"
+            f"  sidecar bbox:  {_format_bbox(moving)}\n"
+            f"  native bbox:   {_format_bbox(candidates['native'])}  (off by {distances['native']:.4g} mm)\n"
+            f"  pipeline bbox: {_format_bbox(candidates['pipeline'])}  (off by {distances['pipeline']:.4g} mm)\n"
+            f"  plausible within {tolerance:.4g} mm\n"
+            "Either the transform was computed on a different volume, or the sidecar is stale."
+        )
+
+    reason = (
+        f"{sidecar_path.name} moving_domain is nearest the {winner} frame "
+        f"(native {distances['native']:.4g} mm, pipeline {distances['pipeline']:.4g} mm; "
+        f"plausible within {tolerance:.4g} mm)"
+    )
+    logger.info("Registration frame: %s", reason)
+    return RegistrationFrame(
+        regrid_to_pipeline=winner == "pipeline",
+        reason=reason,
+        sidecar_path=sidecar_path,
+    )
+
+
+def _domain_from_image(image: sitk.Image, size_ijk: tuple[int, int, int]) -> Domain:
+    """Describe *image*'s physical extent in the sidecar's own vocabulary."""
+    return ImageDomainAxisAligned.from_header(ImageHeader.from_sitk(image, size_ijk)).to_sidecar()
+
+
+def _bbox_distance(left: Domain, right: Domain) -> float:
+    """Largest disagreement between two domains' voxel-center bboxes, in mm.
+
+    Shape is deliberately not compared: the sidecar's grid is the resolution the
+    registration ran at, which legitimately differs from any volume here.
+    """
+    return max(abs(v) for v in _bbox_deltas(left, right).values())
+
+
+def _sanity_tolerance(left: Domain, right: Domain) -> float:
+    """How far apart two domains of the same volume may legitimately sit, in mm.
+
+    Both grids pin voxel 0's *centre* at the origin, so for ``N * s_fine ==
+    n * s_coarse`` the far bounds differ by exactly ``s_coarse - s_fine``, plus up
+    to one coarse voxel when the downsample does not divide evenly -- just under
+    two coarse voxels. This is no longer what picks the frame, so it is set well
+    above that bound; it exists to reject a sidecar belonging to another volume.
+    """
+    coarsest = max(max(left.spacing_LPS), max(right.spacing_LPS))
+    return max(DOMAIN_SANITY_MM, DOMAIN_TOLERANCE_VOXELS * coarsest)
+
+
+def _bbox_deltas(left: Domain, right: Domain) -> dict[str, float]:
+    """Signed per-bound differences between two domains' voxel-center bboxes."""
+    deltas: dict[str, float] = {}
+    for axis in _AXES:
+        lo_l, hi_l = getattr(left.bbox, axis)
+        lo_r, hi_r = getattr(right.bbox, axis)
+        deltas[f"{axis}min"] = lo_l - lo_r
+        deltas[f"{axis}max"] = hi_l - hi_r
+    return deltas
+
+
+def _format_bbox(domain: Domain) -> str:
+    """Render a domain's bbox as ``L [lo, hi] P [...] S [...]``."""
+    return " ".join(
+        f"{axis} [{getattr(domain.bbox, axis)[0]:.4g}, {getattr(domain.bbox, axis)[1]:.4g}]" for axis in _AXES
+    )