brkraw 0.5.0rc1__py3-none-any.whl → 0.5.2__py3-none-any.whl

brkraw/cli/commands/convert.py

@@ -6,16 +6,18 @@ Last updated: 2026-01-06
 """
 
 import argparse
+import inspect
 import json
 import logging
 import os
 import re
+import sys
 from pathlib import Path
 from typing import Any, Mapping, Optional, Dict, List, Tuple, Literal, cast, get_args
 
 import numpy as np
-
 from brkraw.cli.utils import load
+from brkraw.cli.hook_args import load_hook_args_yaml, merge_hook_args
 from brkraw.core import config as config_core
 from brkraw.core import layout as layout_core
 from brkraw.resolver import nifti as nifti_resolver
@@ -29,6 +31,8 @@ logger = logging.getLogger("brkraw")
 
 _INVALID_CHARS = re.compile(r"[^A-Za-z0-9._-]+")
 
+_COUNTER_TAG = re.compile(r"\{(?:Counter|counter)\}")
+
 
 def cmd_convert(args: argparse.Namespace) -> int:
     """Convert a scan/reco to NIfTI with optional metadata sidecars.
@@ -77,8 +81,13 @@ def cmd_convert(args: argparse.Namespace) -> int:
     # resolve flags + spaces
     if not args.sidecar:
         args.sidecar = _env_flag("BRKRAW_CONVERT_SIDECAR")
+    if args.no_convert and not args.sidecar:
+        logger.error("--no-convert requires --sidecar.")
+        return 2
     if not args.flip_x:
         args.flip_x = _env_flag("BRKRAW_CONVERT_FLIP_X")
+    if not args.flatten_fg:
+        args.flatten_fg = _env_flag("BRKRAW_CONVERT_FLATTEN_FG")
     if args.space is None:
         args.space = os.environ.get("BRKRAW_CONVERT_SPACE")
     if args.override_subject_type is None:
@@ -138,10 +147,36 @@ def cmd_convert(args: argparse.Namespace) -> int:
     )
 
     try:
-        hook_args_by_name = _parse_hook_args(args.hook_arg or [])
+        render_layout_supports_counter = "counter" in inspect.signature(layout_core.render_layout).parameters
+    except (TypeError, ValueError):
+        render_layout_supports_counter = True
+    try:
+        slicepack_supports_counter = (
+            "counter" in inspect.signature(layout_core.render_slicepack_suffixes).parameters
+        )
+    except (TypeError, ValueError):
+        slicepack_supports_counter = True
+
+    hook_args_by_name: Dict[str, Dict[str, Any]] = {}
+    hook_args_yaml_sources: List[str] = []
+    for env_key in ("BRKRAW_CONVERT_HOOK_ARGS_YAML", "BRKRAW_HOOK_ARGS_YAML"):
+        value = os.environ.get(env_key)
+        if value:
+            hook_args_yaml_sources.extend([part.strip() for part in value.split(",") if part.strip()])
+    hook_args_yaml_sources.extend(args.hook_args_yaml or [])
+    if hook_args_yaml_sources:
+        try:
+            hook_args_by_name = load_hook_args_yaml(hook_args_yaml_sources)
+        except ValueError as exc:
+            logger.error("%s", exc)
+            return 2
+
+    try:
+        hook_args_cli = _parse_hook_args(args.hook_arg or [])
     except ValueError as exc:
         logger.error("%s", exc)
         return 2
+    hook_args_by_name = merge_hook_args(hook_args_by_name, hook_args_cli)
 
     loader = load(args.path, prefix="Loading")
     try:
@@ -155,8 +190,6 @@ def cmd_convert(args: argparse.Namespace) -> int:
     if batch_all and output_is_file:
         logger.error("When omitting --scan-id, --output must be a directory.")
         return 2
-    if not batch_all and args.reco_id is None:
-        args.reco_id = 1
 
     scan_ids = list(loader.avail.keys()) if batch_all else [args.scan_id]
     if not scan_ids:
@@ -196,6 +229,7 @@ def cmd_convert(args: argparse.Namespace) -> int:
             slicepack_suffix = meta_suffix
         
     total_written = 0
+    reserved_paths: set = set()
     for scan_id in scan_ids:
         if scan_id is None:
             continue
@@ -224,79 +258,114 @@ def cmd_convert(args: argparse.Namespace) -> int:
                 ):
                     logger.debug("Skipping scan %s reco %s (selector mismatch).", scan_id, reco_id)
                     continue
-            nii = loader.convert(
-                scan_id,
-                reco_id=reco_id,
-                format=cast(Literal["nifti", "nifti1"], args.format),
-                space=cast(AffineSpace, args.space),
-                override_header=cast(Nifti1HeaderContents, override_header) if override_header else None,
-                override_subject_type=cast(Optional[SubjectType], args.override_subject_type),
-                override_subject_pose=cast(Optional[SubjectPose], args.override_subject_pose),
-                flip_x=args.flip_x,
-                xyz_units=cast(XYZUNIT, args.xyz_units),
-                t_units=cast(TUNIT, args.t_units),
-                hook_args_by_name=hook_args_by_name,
-            )
-            if nii is None:
-                if not batch_all and args.reco_id is not None:
-                    logger.error("No NIfTI output generated for scan %s reco %s.", scan_id, reco_id)
-                    return 2
-                continue
-
-            nii_list = list(nii) if isinstance(nii, tuple) else [nii]
-            try:
-                base_name = layout_core.render_layout(
-                    loader,
-                    scan_id,
-                    layout_entries=layout_entries,
-                    layout_template=layout_template,
-                    context_map=args.context_map,
-                    reco_id=reco_id,
-                )
-            except Exception as exc:
-                logger.error("%s", exc)
-                return 2
-            if args.prefix:
-                base_name = layout_core.render_layout(
-                    loader,
-                    scan_id,
-                    layout_entries=None,
-                    layout_template=args.prefix,
-                    context_map=args.context_map,
-                    reco_id=reco_id,
-                )
-            if batch_all and args.prefix:
-                base_name = f"{base_name}_scan-{scan_id}"
-            if args.reco_id is None and len(reco_ids) > 1:
-                base_name = f"{base_name}_reco-{reco_id}"
-            base_name = _sanitize_filename(base_name)
-
-            slicepack_suffixes = None
-            if len(nii_list) > 1:
-                info = layout_core.load_layout_info(
-                    loader,
+            if args.no_convert:
+                nii_list: List[Any] = []
+                output_count = 1
+            else:
+                nii = loader.convert(
                     scan_id,
-                    context_map=args.context_map,
                     reco_id=reco_id,
+                    format=cast(Literal["nifti", "nifti1"], args.format),
+                    space=cast(AffineSpace, args.space),
+                    override_header=cast(Nifti1HeaderContents, override_header) if override_header else None,
+                    override_subject_type=cast(Optional[SubjectType], args.override_subject_type),
+                    override_subject_pose=cast(Optional[SubjectPose], args.override_subject_pose),
+                    flip_x=args.flip_x,
+                    flatten_fg=args.flatten_fg,
+                    xyz_units=cast(XYZUNIT, args.xyz_units),
+                    t_units=cast(TUNIT, args.t_units),
+                    hook_args_by_name=hook_args_by_name,
                 )
-                slicepack_suffixes = layout_core.render_slicepack_suffixes(
-                    info,
-                    count=len(nii_list),
-                    template=slicepack_suffix,
-                )
-            output_paths = _resolve_output_paths(
-                args.output,
-                base_name,
-                count=len(nii_list),
-                compress=bool(args.compress),
-                slicepack_suffix=slicepack_suffix,
-                slicepack_suffixes=slicepack_suffixes,
+                if nii is None:
+                    if not batch_all and args.reco_id is not None:
+                        logger.error("No NIfTI output generated for scan %s reco %s.", scan_id, reco_id)
+                        return 2
+                    continue
+                nii_list = list(nii) if isinstance(nii, tuple) else [nii]
+                output_count = len(nii_list)
+
+            slicepack_suffixes: Optional[List[str]] = None
+            output_paths: Optional[List[Path]] = None
+            uses_counter_tag = _uses_counter_tag(
+                layout_template=layout_template,
+                layout_entries=layout_entries,
+                prefix_template=args.prefix,
             )
-            if output_paths is None:
+            counter_enabled = bool(uses_counter_tag and render_layout_supports_counter)
+
+            for counter in range(1, 1000):
+                layout_kwargs: Dict[str, Any] = {"counter": counter} if counter_enabled else {}
+                try:
+                    candidate_base_name = layout_core.render_layout(
+                        loader,
+                        scan_id,
+                        layout_entries=layout_entries,
+                        layout_template=layout_template,
+                        context_map=args.context_map,
+                        reco_id=reco_id,
+                        **layout_kwargs,
+                    )
+                except Exception as exc:
+                    logger.error("%s", exc)
+                    return 2
+                if args.prefix:
+                    candidate_base_name = layout_core.render_layout(
+                        loader,
+                        scan_id,
+                        layout_entries=None,
+                        layout_template=args.prefix,
+                        context_map=args.context_map,
+                        reco_id=reco_id,
+                        **layout_kwargs,
+                    )
+                if batch_all and args.prefix:
+                    candidate_base_name = f"{candidate_base_name}_scan-{scan_id}"
+                if args.reco_id is None and len(reco_ids) > 1:
+                    candidate_base_name = f"{candidate_base_name}_reco-{reco_id}"
+                candidate_base_name = _sanitize_filename(candidate_base_name)
+
+                if not counter_enabled and counter > 1:
+                    candidate_base_name = f"{candidate_base_name}_{counter}"
+
+                slicepack_suffixes = None
+                if not args.no_convert and output_count > 1:
+                    info = layout_core.load_layout_info(
+                        loader,
+                        scan_id,
+                        context_map=args.context_map,
+                        reco_id=reco_id,
+                    )
+                    slicepack_suffixes = layout_core.render_slicepack_suffixes(
+                        info,
+                        count=len(nii_list),
+                        template=slicepack_suffix,
+                        **({"counter": counter} if slicepack_supports_counter and counter_enabled else {}),
+                    )
+                output_paths = _resolve_output_paths(
+                    args.output,
+                    candidate_base_name,
+                    count=output_count,
+                    compress=bool(args.compress),
+                    slicepack_suffix=slicepack_suffix,
+                    slicepack_suffixes=slicepack_suffixes,
+                )
+                if output_paths is None:
+                    return 2
+                if len(output_paths) != output_count:
+                    logger.error("Output path count does not match NIfTI outputs.")
+                    return 2
+                if _paths_collide(output_paths, reserved_paths):
+                    continue
+                break
+            else:
+                logger.error("Could not resolve unique output name after many attempts.")
                 return 2
-            if len(output_paths) != len(nii_list):
-                logger.error("Output path count does not match NIfTI outputs.")
+
+            if output_paths is None:
+                logger.error("Output paths could not be resolved.")
                 return 2
+            for path in output_paths:
+                reserved_paths.add(path)
 
             sidecar_meta = None
             if args.sidecar:
@@ -306,15 +375,24 @@ def cmd_convert(args: argparse.Namespace) -> int:
                     context_map=args.context_map,
                 )
 
-            for path, obj in zip(output_paths, nii_list):
-                path.parent.mkdir(parents=True, exist_ok=True)
-                obj.to_filename(str(path))
-                logger.info("Wrote NIfTI: %s", path)
-                total_written += 1
-                if args.sidecar:
+            if args.no_convert:
+                for path in output_paths:
+                    path.parent.mkdir(parents=True, exist_ok=True)
                     _write_sidecar(path, sidecar_meta)
+                    total_written += 1
+            else:
+                for path, obj in zip(output_paths, nii_list):
+                    path.parent.mkdir(parents=True, exist_ok=True)
+                    obj.to_filename(str(path))
+                    logger.info("Wrote NIfTI: %s", path)
+                    total_written += 1
+                    if args.sidecar:
+                        _write_sidecar(path, sidecar_meta)
     if total_written == 0:
-        logger.error("No NIfTI outputs generated.")
+        if args.no_convert:
+            logger.error("No sidecar outputs generated.")
+        else:
+            logger.error("No NIfTI outputs generated.")
         return 2
     return 0
 
@@ -549,6 +627,15 @@ def _expand_output_paths(
     return [base_dir / f"{base}{suffix.format(index=i + 1)}{ext}" for i in range(count)]
 
 
+def _paths_collide(paths: List[Path], reserved: set) -> bool:
+    if len(set(paths)) != len(paths):
+        return True
+    for path in paths:
+        if path in reserved or path.exists():
+            return True
+    return False
+
+
 def _env_flag(name: str) -> bool:
     """Return True when an env var is set to a truthy value.
 
@@ -603,6 +690,25 @@ def _parse_hook_args(values: List[str]) -> Dict[str, Dict[str, Any]]:
     return parsed
 
 
+def _uses_counter_tag(
+    *,
+    layout_template: Optional[str],
+    layout_entries: List[Any],
+    prefix_template: Optional[str],
+) -> bool:
+    if isinstance(layout_template, str) and _COUNTER_TAG.search(layout_template):
+        return True
+    if isinstance(prefix_template, str) and _COUNTER_TAG.search(prefix_template):
+        return True
+    for field in layout_entries or []:
+        if not isinstance(field, Mapping):
+            continue
+        key = field.get("key")
+        if isinstance(key, str) and key.strip() in {"Counter", "counter"}:
+            return True
+    return False
+
+
 def _coerce_scalar(value: str) -> Any:
     if value.lower() in {"true", "false"}:
         return value.lower() == "true"
@@ -673,7 +779,7 @@ def _add_convert_args(
             "-r",
             "--reco-id",
             type=int,
-            help="Reco id to convert (default: 1).",
+            help="Reco id to convert (defaults to all recos when omitted).",
         )
     parser.add_argument(
         "--flip-x",
@@ -711,6 +817,11 @@ def _add_convert_args(
         action="store_true",
         help="Write a JSON sidecar using metadata rules.",
     )
+    parser.add_argument(
+        "--no-convert",
+        action="store_true",
+        help="Skip NIfTI conversion and only write sidecar metadata (requires --sidecar).",
+    )
     parser.add_argument(
         "--context-map",
         dest="context_map",
@@ -722,6 +833,12 @@ def _add_convert_args(
         default=[],
         help="Hook argument in HOOK:KEY=VALUE format (repeatable).",
     )
+    parser.add_argument(
+        "--hook-args-yaml",
+        action="append",
+        default=[],
+        help="YAML file containing hook args mapping (repeatable).",
+    )
     parser.add_argument(
         "--space",
         choices=list(get_args(AffineSpace)),
@@ -742,6 +859,11 @@ def _add_convert_args(
         choices=["nifti", "nifti1"],
         help="Output format (default: nifti).",
     )
+    parser.add_argument(
+        "--flatten-fg",
+        action="store_true",
+        help="Flatten frame-group dimensions to 4D when data is 5D or higher.",
+    )
     parser.add_argument(
         "--no-compress",
         dest="compress",

brkraw/cli/commands/hook.py

@@ -1,6 +1,10 @@
 from __future__ import annotations
 
-from typing import Dict
+import dataclasses
+import importlib
+from pathlib import Path
+import inspect
+from typing import Any, Dict, Mapping
 
 import argparse
 import logging
@@ -8,6 +12,8 @@ import logging
 from brkraw.apps import hook as hook_app
 from brkraw.core import config as config_core
 from brkraw.core import formatter
+from brkraw.specs import hook as converter_core
+import yaml
 
 logger = logging.getLogger("brkraw")
 
@@ -119,7 +125,7 @@ def cmd_install(args: argparse.Namespace) -> int:
 
 def cmd_uninstall(args: argparse.Namespace) -> int:
     try:
-        hook_name, removed = hook_app.uninstall_hook(
+        hook_name, removed, module_missing = hook_app.uninstall_hook(
             args.target,
             root=args.root,
             force=args.force,
@@ -132,6 +138,10 @@ def cmd_uninstall(args: argparse.Namespace) -> int:
         return 2
     removed_count = sum(len(items) for items in removed.values())
     logger.info("Removed %d file(s).", removed_count)
+    if module_missing:
+        logger.info(
+            "Hook module is not installed; removed registry entries only."
+        )
     logger.info("To uninstall the package, run: pip uninstall %s", hook_name)
     return 0
 
@@ -145,8 +155,12 @@ def cmd_docs(args: argparse.Namespace) -> int:
     logger.info("[Hook Docs] %s", hook_name)
     if args.render:
         try:
-            from rich.console import Console
-            from rich.markdown import Markdown
+            import importlib
+
+            console_mod = importlib.import_module("rich.console")
+            markdown_mod = importlib.import_module("rich.markdown")
+            Console = getattr(console_mod, "Console")
+            Markdown = getattr(markdown_mod, "Markdown")
         except Exception:
             logger.warning("rich is not available; printing raw text.")
             print(text)
@@ -158,6 +172,119 @@ def cmd_docs(args: argparse.Namespace) -> int:
     return 0
 
 
+_PRESET_IGNORE_PARAMS = frozenset(
+    {
+        "self",
+        "scan",
+        "scan_id",
+        "reco_id",
+        "format",
+        "space",
+        "override_header",
+        "override_subject_type",
+        "override_subject_pose",
+        "flip_x",
+        "xyz_units",
+        "t_units",
+        "decimals",
+        "spec",
+        "context_map",
+        "return_spec",
+        "hook_args_by_name",
+    }
+)
+
+
+def _infer_hook_preset(entry: Mapping[str, Any]) -> Dict[str, Any]:
+    preset: Dict[str, Any] = {}
+    modules: list[object] = []
+
+    for func in entry.values():
+        if callable(func):
+            mod_name = getattr(func, "__module__", None)
+            if isinstance(mod_name, str) and mod_name:
+                try:
+                    modules.append(importlib.import_module(mod_name))
+                except Exception:
+                    pass
+
+    for module in modules:
+        module_preset = _infer_hook_preset_from_module(module)
+        if module_preset:
+            return dict(sorted(module_preset.items(), key=lambda item: item[0]))
+
+    for func in entry.values():
+        if not callable(func):
+            continue
+        try:
+            sig = inspect.signature(func)
+        except (TypeError, ValueError):
+            continue
+        for param in sig.parameters.values():
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            name = param.name
+            if name in _PRESET_IGNORE_PARAMS:
+                continue
+            if name in preset:
+                continue
+            if param.default is inspect.Parameter.empty:
+                preset[name] = None
+            else:
+                preset[name] = param.default
+    return dict(sorted(preset.items(), key=lambda item: item[0]))
+
+
+def _infer_hook_preset_from_module(module: object) -> Dict[str, Any]:
+    for attr in ("HOOK_PRESET", "HOOK_ARGS", "HOOK_DEFAULTS"):
+        value = getattr(module, attr, None)
+        if isinstance(value, Mapping):
+            return dict(value)
+
+    build_options = getattr(module, "_build_options", None)
+    if callable(build_options):
+        try:
+            options = build_options({})
+        except Exception:
+            return {}
+        if dataclasses.is_dataclass(options):
+            if not isinstance(options, type):
+                return dict(dataclasses.asdict(options))
+            defaults: Dict[str, Any] = {}
+            for field in dataclasses.fields(options):
+                if field.default is not dataclasses.MISSING:
+                    defaults[field.name] = field.default
+                    continue
+                if field.default_factory is not dataclasses.MISSING:  # type: ignore[comparison-overlap]
+                    try:
+                        defaults[field.name] = field.default_factory()  # type: ignore[misc]
+                    except Exception:
+                        defaults[field.name] = None
+                    continue
+                defaults[field.name] = None
+            return defaults
+        if hasattr(options, "__dict__"):
+            return dict(vars(options))
+    return {}
+
+
+def cmd_preset(args: argparse.Namespace) -> int:
+    try:
+        entry = converter_core.resolve_hook(args.target)
+    except LookupError as exc:
+        logger.error("%s", exc)
+        return 2
+    preset = _infer_hook_preset(entry)
+    payload = {"hooks": {args.target: preset}}
+    text = yaml.safe_dump(payload, sort_keys=False)
+    if args.output:
+        Path(args.output).expanduser().write_text(text, encoding="utf-8")
+        logger.info("Wrote preset: %s", args.output)
+        return 0
+    print(text, end="" if text.endswith("\n") else "\n")
+    return 0
+
+
 def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[name-defined]
     hook_parser = subparsers.add_parser(
         "hook",
@@ -204,3 +331,18 @@ def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[na
         help="Render markdown using rich (if installed).",
     )
     docs_parser.set_defaults(hook_func=cmd_docs)
+
+    preset_parser = hook_sub.add_parser(
+        "preset",
+        help="Generate a YAML hook-args preset template.",
+    )
+    preset_parser.add_argument(
+        "target",
+        help="Hook entrypoint name.",
+    )
+    preset_parser.add_argument(
+        "-o",
+        "--output",
+        help="Write the preset YAML to a file instead of stdout.",
+    )
+    preset_parser.set_defaults(hook_func=cmd_preset)

brkraw/cli/commands/session.py

@@ -99,6 +99,7 @@ def cmd_unset(args: argparse.Namespace) -> int:
         "BRKRAW_CONVERT_SPACE",
         "BRKRAW_CONVERT_COMPRESS",
         "BRKRAW_CONVERT_FLIP_X",
+        "BRKRAW_CONVERT_FLATTEN_FG",
         "BRKRAW_CONVERT_OVERRIDE_SUBJECT_TYPE",
         "BRKRAW_CONVERT_OVERRIDE_SUBJECT_POSE",
         "BRKRAW_CONVERT_XYZ_UNITS",
@@ -153,6 +154,7 @@ def cmd_env(_: argparse.Namespace) -> int:
     convert_compress = os.environ.get("BRKRAW_CONVERT_COMPRESS")
     convert_space = os.environ.get("BRKRAW_CONVERT_SPACE")
     convert_flip_x = os.environ.get("BRKRAW_CONVERT_FLIP_X")
+    convert_flatten_fg = os.environ.get("BRKRAW_CONVERT_FLATTEN_FG")
     convert_subject_type = os.environ.get("BRKRAW_CONVERT_OVERRIDE_SUBJECT_TYPE")
     convert_subject_pose = os.environ.get("BRKRAW_CONVERT_OVERRIDE_SUBJECT_POSE")
     convert_xyz_units = os.environ.get("BRKRAW_CONVERT_XYZ_UNITS")
@@ -174,6 +176,7 @@ def cmd_env(_: argparse.Namespace) -> int:
         and convert_compress is None
         and convert_space is None
         and convert_flip_x is None
+        and convert_flatten_fg is None
         and convert_subject_type is None
         and convert_subject_pose is None
         and convert_xyz_units is None
@@ -211,6 +214,8 @@ def cmd_env(_: argparse.Namespace) -> int:
         print(f"BRKRAW_CONVERT_COMPRESS={convert_compress}")
     if convert_flip_x is not None:
         print(f"BRKRAW_CONVERT_FLIP_X={convert_flip_x}")
+    if convert_flatten_fg is not None:
+        print(f"BRKRAW_CONVERT_FLATTEN_FG={convert_flatten_fg}")
     if convert_subject_type is not None:
         print(f"BRKRAW_CONVERT_OVERRIDE_SUBJECT_TYPE={convert_subject_type}")
     if convert_subject_pose is not None:
@@ -306,7 +311,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[na
         help=(
             "Set BRKRAW_CONVERT_<OPTION> as KEY=VALUE (repeatable). "
             "Keys: OUTPUT, PREFIX, SCAN_ID, RECO_ID, SIDECAR, CONTEXT_MAP, "
-            "COMPRESS, SPACE, FLIP_X, OVERRIDE_SUBJECT_TYPE, "
+            "COMPRESS, SPACE, FLIP_X, FLATTEN_FG, OVERRIDE_SUBJECT_TYPE, "
             "OVERRIDE_SUBJECT_POSE, XYZ_UNITS, T_UNITS, HEADER, FORMAT."
         ),
     )