brkraw 0.5.2__py3-none-any.whl → 0.5.5__py3-none-any.whl

brkraw/apps/loader/helper.py

@@ -1,19 +1,25 @@
-"""Internal helper functions for BrukerLoader.
-
-Last updated: 2025-12-30
-"""
-
 from __future__ import annotations
 
 from types import MethodType
 from functools import partial
 import inspect
-from typing import TYPE_CHECKING, Optional, Tuple, Union, Any, Mapping, cast, List, Dict, Literal
+from typing import (
+    TYPE_CHECKING, 
+    cast, 
+    Optional,
+    Tuple, 
+    Union, 
+    Any, 
+    Mapping, 
+    List, 
+    Dict
+)
 from pathlib import Path
 from warnings import warn
 import logging
 
 import numpy as np
+from numpy.typing import NDArray
 from nibabel.nifti1 import Nifti1Image
 
 from ...core.config import resolve_root
@@ -21,22 +27,38 @@ from ...core.parameters import Parameters
 from ...specs.remapper import load_spec, map_parameters, load_context_map, apply_context_map
 from ...specs.rules import load_rules, select_rule_use
 from ...dataclasses import Reco, Scan, Study
-from .types import ScanLoader
 from ...specs import hook as converter_core
 from ...resolver import affine as affine_resolver
 from ...resolver import image as image_resolver
 from ...resolver import fid as fid_resolver
 from ...resolver import nifti as nifti_resolver
 from ...resolver.helpers import get_file
-
+from .types import (
+    ScanLoader, 
+    ConvertType, 
+    GetDataobjType, 
+    GetAffineType
+)
 if TYPE_CHECKING:
     from ...resolver.nifti import Nifti1HeaderContents
-    from .types import SubjectType, SubjectPose, XYZUNIT, TUNIT, AffineReturn, AffineSpace
+    from .types import (
+        SubjectType, 
+        SubjectPose, 
+        XYZUNIT, 
+        TUNIT,
+        Dataobjs,
+        Affines,
+        AffineSpace,
+        ConvertedObj,
+        Metadata
+    )
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 __all__ = [
+    "resolve_reco_id",
     "resolve_data_and_affine",
+    "resolve_converter_hook",
     "search_parameters",
     "get_dataobj",
     "get_affine",
@@ -55,7 +77,7 @@ def make_dir(names: List[str]):
     return _dir
 
 
-def _resolve_reco_id(
+def resolve_reco_id(
     scan: Union["Scan", "ScanLoader"],
     reco_id: Optional[int],
 ) -> Optional[int]:
@@ -79,7 +101,7 @@ def _resolve_reco_id(
 
 
 def resolve_data_and_affine(
-    scan: Union["Scan", "ScanLoader"],
+    scan: "Scan",
     reco_id: Optional[int] = None,
     *,
     affine_decimals: int = 6,
@@ -92,6 +114,9 @@ def resolve_data_and_affine(
         affine_decimals: Decimal rounding applied to resolved affines.
     """
     scan = cast(ScanLoader, scan)
+    scan.get_fid = MethodType(fid_resolver.resolve, scan)
+    scan.image_info = {}
+    scan.affine_info = {}
 
     reco_ids = [reco_id] if reco_id is not None else list(scan.avail.keys())
     if not reco_ids:
@@ -108,7 +133,7 @@ def resolve_data_and_affine(
             )
             continue
         try:
-            image_info = image_resolver.resolve(scan, rid)
+            image_info = image_resolver.resolve(scan, rid, load_data=False)
         except Exception as exc:
             logger.warning(
                 "Failed to resolve image data for scan %s reco %s: %s",
@@ -122,6 +147,7 @@ def resolve_data_and_affine(
             affine_info = affine_resolver.resolve(
                 scan, rid, decimals=affine_decimals, unwrap_pose=False,
             )
+
         except Exception as exc:
             logger.warning(
                 "Failed to resolve affine for scan %s reco %s: %s",
@@ -131,15 +157,65 @@ def resolve_data_and_affine(
             )
             affine_info = None
 
-        if hasattr(scan, "image_info"):
-            scan.image_info[rid] = image_info
-        else:
-            setattr(scan, "image_info", {rid: image_info})
-        if hasattr(scan, "affine_info"):
-            scan.affine_info[rid] = affine_info
+        scan.image_info[rid] = image_info
+        scan.affine_info[rid] = affine_info
+
+def _load_rules(base):
+    try:
+        rules = load_rules(root=base, validate=False)
+    except Exception:
+        rules = {}
+    return rules
+
+
+def resolve_converter_hook(
+    scan: "Scan",
+    base: Path,
+    *,
+    affine_decimals: int = 6,
+):
+    scan = cast(ScanLoader, scan)
+    rules = _load_rules(base)
+    if rules:
+        try:
+            hook_name = select_rule_use(
+                scan,
+                rules.get("converter_hook", []),
+                base=base,
+                resolve_paths=False,
+            )
+        except Exception as exc:
+            logger.debug(
+                "Converter hook rule selection failed for scan %s: %s",
+                getattr(scan, "scan_id", "?"),
+                exc,
+                exc_info=True,
+            )
+            hook_name = None
+    
+        if isinstance(hook_name, str):
+            try:
+                entry = converter_core.resolve_hook(hook_name)
+            except Exception as exc:
+                logger.warning(
+                    "Converter hook %r not available: %s",
+                    hook_name,
+                    exc,
+                )
+                entry = None
+            if entry:
+                logger.debug("Applying converter hook: %s", hook_name)
+                scan._converter_hook_name = hook_name
+                apply_converter_hook(
+                    scan,
+                    entry,
+                    affine_decimals=affine_decimals,
+                )
+            else:
+                logger.debug("Converter hook %r resolved to no entry.", hook_name)
         else:
-            setattr(scan, "affine_info", {rid: affine_info})
-    scan.get_fid = MethodType(fid_resolver.resolve, scan)
+            logger.debug("No converter hook selected for scan %s.", getattr(scan, "scan_id", "?"))
+    scan._hook_resolved = True
 
 
 def search_parameters(
@@ -242,7 +318,7 @@ def search_parameters(
         if scan_id is None:
             warn("To search from Study object, specifying <scan_id> is required.")
             return None
-        scan = self.get_scan(scan_id)
+        scan = cast(ScanLoader, self.get_scan(scan_id))
         scan_hits = search_node(scan)
         if reco_id is None:
             reco_hits = search_recos(scan)
@@ -281,10 +357,10 @@ def search_parameters(
 
 
 def _finalize_affines(
-    affines: list[np.ndarray],
+    affines: List[NDArray],
     num_slice_packs: int,
     decimals: Optional[int],
-) -> AffineReturn:
+) -> Affines:
     if num_slice_packs == 1:
         affine = affines[0]
         if decimals is not None:
@@ -298,38 +374,73 @@ def _finalize_affines(
 
 
 def get_dataobj(
-    self: Union["Scan", "ScanLoader"],
+    self: "ScanLoader",
     reco_id: Optional[int] = None,
-    **_: Any,
-) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]:
+    **kwargs: Dict[str, Any]
+) -> Dataobjs:
     """Return reconstructed data for a reco, split by slice pack if needed.
 
     Args:
         self: Scan or ScanLoader instance.
-    reco_id: Reco identifier to read (defaults to the first available).
+        reco_id: Reco identifier to read (defaults to the first available).
+        cycle_index: Optional cycle start index (last axis), reads all cycles when None.
+        cycle_count: Optional number of cycles to read from cycle_index; reads to end when None.
+            Ignored when the dataset reports <= 1 total cycle.
 
     Returns:
         Single ndarray when one slice pack exists; otherwise a tuple of arrays.
         Returns None when required metadata is unavailable.
     """
-    if not hasattr(self, "image_info") or not hasattr(self, "affine_info"):
-        return None
-    self = cast(ScanLoader, self)
-    resolved_reco_id = _resolve_reco_id(self, reco_id)
+    cycle_index = cast(Optional[int], kwargs.get('cycle_index'))
+    cycle_count = cast(Optional[int], kwargs.get('cycle_count'))
+    resolved_reco_id = resolve_reco_id(self, reco_id)
     if resolved_reco_id is None:
         return None
+    
     affine_info = self.affine_info.get(resolved_reco_id)
+    if affine_info is None:
+        logger.warning(
+            "affine_info is not available for scan %s",
+            getattr(self, "scan_id", "?")
+        )
+        return None
     image_info = self.image_info.get(resolved_reco_id)
-    if affine_info is None or image_info is None:
+    if image_info is None:
+        logger.warning(
+            "image_info is not available for scan %s",
+            getattr(self, "scan_id", "?")
+        )
         return None
 
-    num_slices = affine_info["num_slices"]
-    dataobj = image_info["dataobj"]
+    # Normalize cycle arguments if provided.
+    cycle_args_requested = cycle_index is not None or cycle_count is not None
+    if cycle_index is None and cycle_count is not None:
+        cycle_index = 0
+
+    # If the dataset has <= 1 cycle, ignore cycle slicing to avoid block reads.
+    if cycle_args_requested:
+        total_cycles = int(image_info["num_cycles"])
+        if total_cycles <= 1:
+            cycle_index = None
+            cycle_count = None
+            cycle_args_requested = False
+
+    if cycle_args_requested or image_info.get("dataobj") is None:
+        image_info = image_resolver.resolve(
+            self,
+            resolved_reco_id,
+            load_data=True,
+            cycle_index=cycle_index,
+            cycle_count=cycle_count,
+        )
+        self.image_info[resolved_reco_id] = image_info
 
+    num_slices = affine_info["num_slices"]
+    dataobj = cast(dict, image_info).get("dataobj")
     slice_pack = []
     slice_offset = 0
     for _num_slices in num_slices:
-        _dataobj = dataobj[:, :, slice(slice_offset, slice_offset + _num_slices)]
+        _dataobj = cast(NDArray, dataobj)[:, :, slice(slice_offset, slice_offset + _num_slices)]
         slice_offset += _num_slices
         slice_pack.append(_dataobj)
 
@@ -339,7 +450,7 @@ def get_dataobj(
 
 
 def get_affine(
-    self: Union["Scan", "ScanLoader"],
+    self: "ScanLoader",
     reco_id: Optional[int] = None,
     *,
     space: AffineSpace = "subject_ras",
@@ -347,7 +458,7 @@ def get_affine(
     override_subject_pose: Optional["SubjectPose"] = None,
     decimals: Optional[int] = None,
     **kwargs: Any,
-) -> AffineReturn:
+) -> Affines:
     """
     Return affine(s) for a reco in the requested coordinate space.
 
@@ -379,7 +490,7 @@ def get_affine(
         return None
 
     self = cast("ScanLoader", self)
-    resolved_reco_id = _resolve_reco_id(self, reco_id)
+    resolved_reco_id = resolve_reco_id(self, reco_id)
     if resolved_reco_id is None:
         return None
 
@@ -427,7 +538,7 @@ def get_affine(
     return _apply_affine_post_transform(result, kwargs=kwargs)
 
 
-def _apply_affine_post_transform(affines: AffineReturn, *, kwargs: Mapping[str, Any]) -> AffineReturn:
+def _apply_affine_post_transform(affines: Affines, *, kwargs: Mapping[str, Any]) -> Affines:
     """Apply optional flips/rotations to affines right before returning.
 
     These transforms are applied in world space and do not depend on output
@@ -458,7 +569,7 @@ def _apply_affine_post_transform(affines: AffineReturn, *, kwargs: Mapping[str,
     if not (flip_x or flip_y or flip_z or rad_x or rad_y or rad_z):
         return affines
 
-    def apply_one(a: np.ndarray) -> np.ndarray:
+    def apply_one(a: NDArray) -> NDArray:
         out = np.asarray(a, dtype=float)
         if flip_x or flip_y or flip_z:
             out = affine_resolver.flip_affine(out, flip_x=flip_x, flip_y=flip_y, flip_z=flip_z)
@@ -473,53 +584,148 @@ def _apply_affine_post_transform(affines: AffineReturn, *, kwargs: Mapping[str,
 
 def get_nifti1image(
     self: Union["Scan", "ScanLoader"],
+    reco_id: int,
+    dataobjs: Tuple[NDArray, ...],
+    affines: Tuple[NDArray, ...],
+    *,
+    xyz_units: XYZUNIT = "mm",
+    t_units: TUNIT = "sec",
+    override_header: Optional[Nifti1HeaderContents] = None,
+) -> ConvertedObj:
+    """Return NIfTI image(s) for a reco.
+
+    Args:
+        self: Scan or ScanLoader instance.
+        reco_id: Reco identifier to read (defaults to the first available).
+        xyz_units: Spatial units for NIfTI header.
+        t_units: Temporal units for NIfTI header.
+        override_header: Optional header values to apply.
+
+    Returns:
+        Output object(s) supporting to_filename(). Returns None when required
+        metadata is unavailable.
+    """
+    self = cast(ScanLoader, self)
+
+    image_info = self.image_info.get(reco_id)
+    if image_info is None:
+        return None
+
+    if dataobjs is None or affines is None:
+        return None
+
+    niiobjs = []
+    for i, dataobj in enumerate(dataobjs):
+        affine = affines[i]
+        niiobj = Nifti1Image(dataobj, affine)
+        nifti1header_contents = nifti_resolver.resolve(
+            image_info, xyz_units=xyz_units, t_units=t_units
+        )
+        if override_header:
+            for key, value in override_header.items():
+                if value is not None:
+                    nifti1header_contents[key] = value
+        niiobj = nifti_resolver.update(niiobj, nifti1header_contents)
+        niiobjs.append(niiobj)
+
+    if len(niiobjs) == 1:
+        return niiobjs[0]
+    return tuple(niiobjs)
+
+
+def convert(
+    self: "ScanLoader",
     reco_id: Optional[int] = None,
     *,
     space: AffineSpace = "subject_ras",
     override_header: Optional[Nifti1HeaderContents] = None,
     override_subject_type: Optional[SubjectType] = None,
     override_subject_pose: Optional[SubjectPose] = None,
-    flip_x: bool = False,
     flatten_fg: bool = False,
-    xyz_units: XYZUNIT = "mm",
-    t_units: TUNIT = "sec",
     hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
-) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
-    """Return NIfTI image(s) for a reco.
-
+    **kwargs: Any,
+) -> ConvertedObj:
+    """Convert a reco to output object(s).
+    
     Args:
-        self: Scan or ScanLoader instance.
-        reco_id: Reco identifier to read (defaults to the first available).
         space: Output affine space ("raw", "scanner", "subject_ras").
         override_header: Optional header values to apply.
         override_subject_type: Subject type override for subject-view wrapping.
         override_subject_pose: Subject pose override for subject-view wrapping.
-        flip_x: If True, set NIfTI header x-flip flag.
-        xyz_units: Spatial units for NIfTI header.
-        t_units: Temporal units for NIfTI header.
-
+        flatten_fg: If True, flatten foreground dimensions.
+        hook_args_by_name: Optional hook args mapping (split per helper signature).
+        flatten_fg: If True, flatten foreground dimensions.
     Returns:
         Single NIfTI image when one slice pack exists; otherwise a tuple of
         images. Returns None when required metadata is unavailable.
     """
-
     if not all(
         hasattr(self, attr) for attr in ["image_info", "affine_info", "get_dataobj", "get_affine"]
     ):
         return None
-
+    
     self = cast(ScanLoader, self)
-    resolved_reco_id = _resolve_reco_id(self, reco_id)
+    resolved_reco_id = resolve_reco_id(self, reco_id)
+    logger.debug("Resolved reco_id = %s", resolved_reco_id)
     if resolved_reco_id is None:
         return None
+
+    hook_name = getattr(self, "_converter_hook_name", None)
+    if isinstance(hook_name, str) and hook_name:
+        logger.debug(
+            "Convert starting for scan %s reco %s with hook %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            hook_name,
+        )
+    else:
+        logger.debug(
+            "Convert starting for scan %s reco %s (no hook)",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+        )
+    
     hook_kwargs = _resolve_hook_kwargs(self, hook_args_by_name)
-    data_kwargs = _filter_hook_kwargs(self.get_dataobj, hook_kwargs)
+
+    # Merge explicit **kwargs (CLI/user) with hook kwargs. Explicit kwargs win.
+    merged_kwargs: Dict[str, Any] = dict(hook_kwargs) if hook_kwargs else {}
+    merged_kwargs.update(kwargs)
+
+    data_kwargs = _filter_hook_kwargs(self.get_dataobj, merged_kwargs)
+    # flip_* are affine-only options; never pass them to get_dataobj.
+    for key in ("flip_x", "flip_y", "flip_z"):
+        data_kwargs.pop(key, None)
+    
+    convert_kwargs = {key: value for key, value in merged_kwargs.items() if key not in data_kwargs}
     if data_kwargs:
+        logger.debug(
+            "Calling get_dataobj for scan %s reco %s with args %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            data_kwargs,
+        )
         dataobjs = self.get_dataobj(resolved_reco_id, **data_kwargs)
     else:
+        logger.debug(
+            "Calling get_dataobj for scan %s reco %s (no args)",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+        )
         dataobjs = self.get_dataobj(resolved_reco_id)
-    affine_kwargs = _filter_hook_kwargs(self.get_affine, hook_kwargs)
+
+    affine_kwargs = _filter_hook_kwargs(self.get_affine, merged_kwargs)
+    convert_kwargs = {
+        key: value
+        for key, value in convert_kwargs.items()
+        if key not in affine_kwargs
+    }
     if affine_kwargs:
+        logger.debug(
+            "Calling get_affine for scan %s reco %s with args %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            affine_kwargs,
+        )
         affines = self.get_affine(
             resolved_reco_id,
             space=space,
@@ -528,77 +734,62 @@ def get_nifti1image(
             **affine_kwargs,
         )
     else:
+        logger.debug(
+            "Calling get_affine for scan %s reco %s (no args)",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+        )
         affines = self.get_affine(
             resolved_reco_id,
             space=space,
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
         )
-    image_info = self.image_info.get(resolved_reco_id)
-
-    if dataobjs is None or affines is None or image_info is None:
+    
+    if dataobjs is None or affines is None:
         return None
-
-    if not isinstance(dataobjs, tuple) and not isinstance(affines, tuple):
+    
+    if not isinstance(dataobjs, tuple):
         dataobjs = (dataobjs,)
+    if not isinstance(affines, tuple):
         affines = (affines,)
-
-    niiobjs = []
+    
+    dataobjs = list(dataobjs)
     for i, dataobj in enumerate(dataobjs):
         if flatten_fg and dataobj.ndim > 4:
             spatial_shape = dataobj.shape[:3]
             flattened = int(np.prod(dataobj.shape[3:]))
-            dataobj = dataobj.reshape((*spatial_shape, flattened), order="A")
-        affine = affines[i]
-        niiobj = Nifti1Image(dataobj, affine)
-        nifti1header_contents = nifti_resolver.resolve(
-            image_info, flip_x=flip_x, xyz_units=xyz_units, t_units=t_units
-        )
-        if override_header:
-            for key, value in override_header.items():
-                if value is not None:
-                    nifti1header_contents[key] = value
-        niiobj = nifti_resolver.update(niiobj, nifti1header_contents)
-        niiobjs.append(niiobj)
-
-    if len(niiobjs) == 1:
-        return niiobjs[0]
-    return tuple(niiobjs)
+            dataobjs[i] = dataobj.reshape((*spatial_shape, flattened), order="A")
+    dataobjs = tuple(dataobjs)
 
+    converter_func = getattr(self, "converter_func", None)
+    if isinstance(converter_func, ConvertType):
+        hook_call_kwargs = _filter_hook_kwargs(converter_func, convert_kwargs)
+        logger.debug(
+            "Calling converter hook for scan %s reco %s with args %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            hook_call_kwargs,
+        )
+        return converter_func(
+            dataobj=dataobjs,
+            affine=affines,
+            **hook_call_kwargs,
+        )
 
-def convert(
-    self: Union["Scan", "ScanLoader"],
-    reco_id: Optional[int] = None,
-    *,
-    format: Literal["nifti", "nifti1"] = "nifti",
-    space: AffineSpace = "subject_ras",
-    override_header: Optional[Nifti1HeaderContents] = None,
-    override_subject_type: Optional[SubjectType] = None,
-    override_subject_pose: Optional[SubjectPose] = None,
-    flip_x: bool = False,
-    flatten_fg: bool = False,
-    xyz_units: XYZUNIT = "mm",
-    t_units: TUNIT = "sec",
-    hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
-) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
-    """Convert a reco to a selected output format."""
-    if format not in {"nifti", "nifti1"}:
-        raise ValueError(f"Unsupported format: {format}")
+    nifti1image_kwargs = {
+        "override_header": override_header,
+        **kwargs,
+    }
+    nifti1image_kwargs = _filter_hook_kwargs(get_nifti1image, nifti1image_kwargs)
     return get_nifti1image(
         self,
-        reco_id,
-        space=space,
-        override_header=override_header,
-        override_subject_type=override_subject_type,
-        override_subject_pose=override_subject_pose,
-        flip_x=flip_x,
-        flatten_fg=flatten_fg,
-        xyz_units=xyz_units,
-        t_units=t_units,
-        hook_args_by_name=hook_args_by_name,
+        reco_id=resolved_reco_id,
+        dataobjs=dataobjs,
+        affines=affines,
+        **nifti1image_kwargs,
     )
 
-
 def _resolve_hook_kwargs(
     scan: Union["Scan", "ScanLoader"],
     hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]],
@@ -608,6 +799,12 @@ def _resolve_hook_kwargs(
     hook_name = getattr(scan, "_converter_hook_name", None)
     if not isinstance(hook_name, str) or not hook_name:
         return {}
+    logger.debug(
+        "Resolving hook args for scan %s hook %s (available: %s)",
+        getattr(scan, "scan_id", "?"),
+        hook_name,
+        sorted(hook_args_by_name.keys()),
+    )
     values = hook_args_by_name.get(hook_name)
     if values is None:
         seen: set[str] = set()
@@ -643,7 +840,12 @@ def _resolve_hook_kwargs(
                 )
                 values = candidate_values
                 break
-    return dict(values) if isinstance(values, Mapping) else {}
+    resolved = dict(values) if isinstance(values, Mapping) else {}
+    if resolved:
+        logger.debug("Resolved hook args for %s: %s", hook_name, resolved)
+    else:
+        logger.debug("No hook args resolved for %s.", hook_name)
+    return resolved
 
 
 def _filter_hook_kwargs(func: Any, hook_kwargs: Mapping[str, Any]) -> Dict[str, Any]:
@@ -724,7 +926,7 @@ def get_metadata(
     spec: Optional[Union[Mapping[str, Any], str, Path]] = None,
     context_map: Optional[Union[str, Path]] = None,
     return_spec: bool = False,
-):
+) -> Metadata:
     """Resolve metadata using a remapper spec.
 
     Args:
@@ -739,7 +941,7 @@ def get_metadata(
         return_spec is True, returns (metadata, spec_info).
     """
     scan = cast(ScanLoader, self)
-    resolved_reco_id = _resolve_reco_id(scan, reco_id)
+    resolved_reco_id = resolve_reco_id(scan, reco_id)
     if resolved_reco_id is None:
         if return_spec:
             return None, None
@@ -785,6 +987,17 @@ def apply_converter_hook(
     """Override scan conversion helpers using a converter hook."""
     converter_core.validate_hook(converter_hook)
     plugin = dict(converter_hook)
+    logger.debug(
+        "Binding converter hook for scan %s: %s",
+        getattr(scan, "scan_id", "?"),
+        sorted(plugin.keys()),
+    )
+    if "get_dataobj" in plugin and not isinstance(plugin["get_dataobj"], GetDataobjType):
+        raise TypeError("Converter hook 'get_dataobj' must match GetDataobjType.")
+    if "get_affine" in plugin and not isinstance(plugin["get_affine"], GetAffineType):
+        raise TypeError("Converter hook 'get_affine' must match GetAffineType.")
+    if "convert" in plugin and not isinstance(plugin["convert"], ConvertType):
+        raise TypeError("Converter hook 'convert' must match ConvertType.")
     scan._converter_hook = plugin
     if "get_dataobj" in plugin:
         scan.get_dataobj = MethodType(plugin["get_dataobj"], scan)
@@ -794,4 +1007,11 @@ def apply_converter_hook(
             get_affine = partial(get_affine, decimals=affine_decimals)
         scan.get_affine = MethodType(get_affine, scan)
     if "convert" in plugin:
-        scan.convert = MethodType(plugin["convert"], scan)
+        scan.converter_func = MethodType(plugin["convert"], scan)
+    else:
+        scan.converter_func = None
+    logger.debug(
+        "Converter hook bound for scan %s (hook=%s)",
+        getattr(scan, "scan_id", "?"),
+        getattr(scan, "_converter_hook_name", None),
+    )