dcccpy 0.1.2__py3-none-any.whl

dcccpy/__init__.py

@@ -0,0 +1,42 @@
+"""Python wrapper for the native DCCCcore executable."""
+
+from .core import (
+    DCCCResult,
+    adad,
+    abetaindex,
+    abetaload,
+    adni_pet_core,
+    centaur,
+    centaurz,
+    centiloid,
+    dccccore_path,
+    fillstates,
+    normalize,
+    parse_metrics,
+    rigid,
+    run,
+    suvr,
+)
+from .runtime import DCCCCORE_VERSION, DCCCcoreDownloadError, DCCCcoreNotFoundError, download_dccccore
+
+__all__ = [
+    "DCCCResult",
+    "DCCCCORE_VERSION",
+    "DCCCcoreDownloadError",
+    "DCCCcoreNotFoundError",
+    "adad",
+    "abetaindex",
+    "abetaload",
+    "adni_pet_core",
+    "centaur",
+    "centaurz",
+    "centiloid",
+    "dccccore_path",
+    "download_dccccore",
+    "fillstates",
+    "normalize",
+    "parse_metrics",
+    "rigid",
+    "run",
+    "suvr",
+]

dcccpy/cli.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import sys
+
+from .core import run
+from .runtime import DCCCcoreDownloadError, DCCCcoreNotFoundError
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        result = run(args, check=False)
+    except (DCCCcoreDownloadError, DCCCcoreNotFoundError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 127
+
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, file=sys.stderr, end="")
+    return result.returncode

dcccpy/core.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from .runtime import DCCCcoreNotFoundError, dccccore_path
+
+
+_NUMBER_RE = r"[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?"
+_METRIC_RE = re.compile(rf"^\s*([A-Za-z][A-Za-z0-9_. /()-]*):\s*({_NUMBER_RE})\s*(?:%.*)?$")
+
+
+@dataclass(frozen=True)
+class DCCCResult:
+    """Completed DCCCcore invocation."""
+
+    args: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+    output: Path | None = None
+    temp_dir: Path | None = None
+    executable: Path | None = None
+    metrics: Mapping[str, float] = field(default_factory=dict)
+
+    @property
+    def command(self) -> tuple[str, ...]:
+        if self.executable is None:
+            return self.args
+        return (str(self.executable), *self.args)
+
+    def check_returncode(self) -> "DCCCResult":
+        if self.returncode:
+            raise subprocess.CalledProcessError(
+                self.returncode,
+                list(self.command),
+                output=self.stdout,
+                stderr=self.stderr,
+            )
+        return self
+
+    def load_output(self):
+        """Load the output image with nibabel."""
+
+        if self.output is None:
+            raise ValueError("This DCCCResult does not have an output path.")
+        try:
+            import nibabel as nib
+        except ImportError as exc:
+            raise ImportError("nibabel is required to load output images.") from exc
+        return nib.load(os.fspath(self.output))
+
+
+def parse_metrics(text: str) -> dict[str, float]:
+    """Parse numeric metric lines from DCCCcore stdout."""
+
+    metrics: dict[str, float] = {}
+    for line in text.splitlines():
+        match = _METRIC_RE.match(line)
+        if not match:
+            continue
+        label = " ".join(match.group(1).strip().split())
+        metrics[label] = float(match.group(2))
+    return metrics
+
+
+def _as_args(args: Sequence[object]) -> list[str]:
+    return [os.fspath(arg) if isinstance(arg, os.PathLike) else str(arg) for arg in args]
+
+
+def run(
+    args: Sequence[object],
+    *,
+    check: bool = True,
+    executable: str | os.PathLike[str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+    env: Mapping[str, str] | None = None,
+    output: str | os.PathLike[str] | None = None,
+) -> DCCCResult:
+    """Run DCCCcore with raw command-line arguments."""
+
+    exe = dccccore_path(executable)
+    str_args = _as_args(args)
+    completed = subprocess.run(
+        [str(exe), *str_args],
+        cwd=os.fspath(cwd) if cwd is not None else None,
+        env={**os.environ, **dict(env or {})},
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    result = DCCCResult(
+        args=tuple(str_args),
+        returncode=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+        output=Path(output) if output is not None else None,
+        executable=exe,
+        metrics=parse_metrics(completed.stdout),
+    )
+    return result.check_returncode() if check else result
+
+
+def _temp_output(suffix: str = ".nii") -> tuple[Path, Path]:
+    temp_dir = Path(tempfile.mkdtemp(prefix="dcccpy-"))
+    return temp_dir / f"output{suffix}", temp_dir
+
+
+def _create_temp_dir(existing: Path | None = None) -> Path:
+    return existing or Path(tempfile.mkdtemp(prefix="dcccpy-"))
+
+
+def _resolve_user_path(path: str | os.PathLike[str]) -> Path:
+    return Path(path).expanduser().resolve(strict=False)
+
+
+def _prepare_input(input: object, temp_dir: Path | None) -> tuple[str, Path | None]:
+    if isinstance(input, (str, os.PathLike)):
+        return os.fspath(_resolve_user_path(input)), temp_dir
+
+    to_filename = getattr(input, "to_filename", None)
+    if callable(to_filename):
+        temp_dir = _create_temp_dir(temp_dir)
+        input_path = temp_dir / "input.nii.gz"
+        to_filename(os.fspath(input_path))
+        return os.fspath(input_path), temp_dir
+
+    raise TypeError(
+        "input must be a filesystem path or a nibabel-like image object with to_filename()."
+    )
+
+
+def _prepare_io(input: object, output: str | os.PathLike[str] | None) -> tuple[str, Path, Path | None]:
+    temp_dir: Path | None = None
+    if output is None:
+        actual_output, temp_dir = _temp_output()
+    else:
+        actual_output = _resolve_user_path(output)
+
+    input_path, temp_dir = _prepare_input(input, temp_dir)
+    return input_path, actual_output, temp_dir
+
+
+def _append_flag(args: list[str], flag: str, enabled: bool) -> None:
+    if enabled:
+        args.append(flag)
+
+
+def _metric_command(
+    subcommand: str,
+    input: object,
+    output: str | os.PathLike[str] | None,
+    *,
+    batch: bool = False,
+    bids: str | None = None,
+    config: str | os.PathLike[str] | None = None,
+    skip_normalization: bool = False,
+    suvr_values: bool = False,
+    debug: bool = False,
+    extra_args: Sequence[object] = (),
+    check: bool = True,
+    executable: str | os.PathLike[str] | None = None,
+) -> DCCCResult:
+    input_path, actual_output, temp_dir = _prepare_io(input, output)
+
+    args = [subcommand, "--input", input_path, "--output", os.fspath(actual_output)]
+    _append_flag(args, "--batch", batch)
+    _append_flag(args, "--skip-normalization", skip_normalization)
+    _append_flag(args, "--suvr", suvr_values)
+    _append_flag(args, "--debug", debug)
+    if bids is not None:
+        args.extend(["--bids", bids])
+    if config is not None:
+        args.extend(["--config", os.fspath(config)])
+    args.extend(_as_args(extra_args))
+
+    result = run(args, check=check, executable=executable, output=actual_output)
+    return DCCCResult(
+        args=result.args,
+        returncode=result.returncode,
+        stdout=result.stdout,
+        stderr=result.stderr,
+        output=actual_output,
+        temp_dir=temp_dir,
+        executable=result.executable,
+        metrics=result.metrics,
+    )
+
+
+def _coerce_metric_kwargs(kwargs: dict[str, object], *, suvr: bool = False) -> dict[str, object]:
+    coerced = dict(kwargs)
+    if "include_suvr" in coerced and "suvr_values" not in coerced:
+        coerced["suvr_values"] = coerced.pop("include_suvr")
+    if "suvr" in coerced and "suvr_values" not in coerced:
+        coerced["suvr_values"] = coerced.pop("suvr")
+    if suvr and "suvr_values" not in coerced:
+        coerced["suvr_values"] = True
+    return coerced
+
+
+def centiloid(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    suvr: bool = False,
+    **kwargs: object,
+) -> DCCCResult:
+    """Run the DCCCcore centiloid command."""
+
+    return _metric_command("centiloid", input, output, **_coerce_metric_kwargs(kwargs, suvr=suvr))
+
+
+def centaur(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    suvr: bool = False,
+    **kwargs: object,
+) -> DCCCResult:
+    return _metric_command("centaur", input, output, **_coerce_metric_kwargs(kwargs, suvr=suvr))
+
+
+def centaurz(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    suvr: bool = False,
+    report_detailed_regions: bool = False,
+    **kwargs: object,
+) -> DCCCResult:
+    coerced = _coerce_metric_kwargs(kwargs, suvr=suvr)
+    extra_args = list(coerced.pop("extra_args", ()))
+    if report_detailed_regions:
+        extra_args.append("--report-detailed-regions")
+    return _metric_command("centaurz", input, output, extra_args=extra_args, **coerced)
+
+
+def abetaindex(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    **kwargs: object,
+) -> DCCCResult:
+    return _metric_command("abetaindex", input, output, **_coerce_metric_kwargs(kwargs))
+
+
+def abetaload(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    **kwargs: object,
+) -> DCCCResult:
+    return _metric_command("abetaload", input, output, **_coerce_metric_kwargs(kwargs))
+
+
+def fillstates(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    tracer: str,
+    suvr: bool = False,
+    **kwargs: object,
+) -> DCCCResult:
+    coerced = _coerce_metric_kwargs(kwargs, suvr=suvr)
+    extra_args = list(coerced.pop("extra_args", ()))
+    extra_args.extend(["--tracer", tracer])
+    return _metric_command("fillstates", input, output, extra_args=extra_args, **coerced)
+
+
+def suvr(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    voi_mask: str | os.PathLike[str],
+    ref_mask: str | os.PathLike[str],
+    **kwargs: object,
+) -> DCCCResult:
+    coerced = _coerce_metric_kwargs(kwargs)
+    extra_args = list(coerced.pop("extra_args", ()))
+    extra_args.extend(["--voi-mask", os.fspath(voi_mask), "--ref-mask", os.fspath(ref_mask)])
+    return _metric_command("suvr", input, output, extra_args=extra_args, **coerced)
+
+
+def adad(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    modality: str | None = None,
+    iterative: bool = False,
+    **kwargs: object,
+) -> DCCCResult:
+    coerced = _coerce_metric_kwargs(kwargs)
+    extra_args = list(coerced.pop("extra_args", ()))
+    if modality is not None:
+        extra_args.extend(["--modality", modality])
+    if iterative:
+        extra_args.append("--iterative")
+    return _metric_command("adad", input, output, extra_args=extra_args, **coerced)
+
+
+def _spatial_command(
+    subcommand: str,
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    *,
+    iterative: bool = False,
+    manual_fov: bool = False,
+    batch: bool = False,
+    bids: str | None = None,
+    extra_args: Sequence[object] = (),
+    check: bool = True,
+    executable: str | os.PathLike[str] | None = None,
+) -> DCCCResult:
+    input_path, actual_output, temp_dir = _prepare_io(input, output)
+
+    args = [subcommand, "--input", input_path, "--output", os.fspath(actual_output)]
+    _append_flag(args, "--iterative", iterative)
+    _append_flag(args, "--manual-fov", manual_fov)
+    _append_flag(args, "--batch", batch)
+    if bids is not None:
+        args.extend(["--bids", bids])
+    args.extend(_as_args(extra_args))
+
+    result = run(args, check=check, executable=executable, output=actual_output)
+    return DCCCResult(
+        args=result.args,
+        returncode=result.returncode,
+        stdout=result.stdout,
+        stderr=result.stderr,
+        output=actual_output,
+        temp_dir=temp_dir,
+        executable=result.executable,
+        metrics=result.metrics,
+    )
+
+
+def normalize(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    **kwargs: object,
+) -> DCCCResult:
+    return _spatial_command("normalize", input, output, **kwargs)
+
+
+def adni_pet_core(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    **kwargs: object,
+) -> DCCCResult:
+    return _spatial_command("adni-pet-core", input, output, **kwargs)
+
+
+def rigid(
+    input: object,
+    output: str | os.PathLike[str] | None = None,
+    **kwargs: object,
+) -> DCCCResult:
+    return _spatial_command("rigid", input, output, **kwargs)

dcccpy/py.typed

@@ -0,0 +1 @@
+

dcccpy/runtime.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import stat
+import sys
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Iterable
+
+
+DCCCCORE_VERSION = "4.2.3"
+RELEASE_REPO = "tctco/DCCCSlicer"
+
+
+class DCCCcoreNotFoundError(FileNotFoundError):
+    """Raised when dcccpy cannot locate a DCCCcore executable."""
+
+
+class DCCCcoreDownloadError(RuntimeError):
+    """Raised when automatic DCCCcore download fails."""
+
+
+def platform_key() -> str:
+    machine = platform.machine().lower()
+    if machine in {"x86_64", "amd64"}:
+        arch = "x86_64"
+    elif machine in {"aarch64", "arm64"}:
+        arch = "arm64"
+    else:
+        arch = machine
+
+    if sys.platform.startswith("linux"):
+        return f"linux-{arch}"
+    if sys.platform == "darwin":
+        return f"macos-{arch}"
+    if sys.platform.startswith("win"):
+        return f"windows-{arch}"
+    return f"{sys.platform}-{arch}"
+
+
+def release_platform(key: str | None = None) -> str:
+    key = key or platform_key()
+    mapping = {
+        "linux-x86_64": "ubuntu-latest-x64",
+        "windows-x86_64": "windows-latest-x64",
+        "macos-arm64": "macos-latest-arm64",
+    }
+    try:
+        return mapping[key]
+    except KeyError as exc:
+        raise DCCCcoreNotFoundError(f"No prebuilt DCCCcore release asset is known for {key}.") from exc
+
+
+def executable_names() -> tuple[str, ...]:
+    return ("DCCCcore.exe", "DCCCcore") if os.name == "nt" else ("DCCCcore",)
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def cache_root() -> Path:
+    explicit = os.environ.get("DCCCPY_CACHE_DIR")
+    if explicit:
+        return Path(explicit).expanduser()
+
+    if sys.platform.startswith("win"):
+        base = os.environ.get("LOCALAPPDATA")
+        if base:
+            return Path(base) / "dcccpy"
+
+    base = os.environ.get("XDG_CACHE_HOME")
+    if base:
+        return Path(base) / "dcccpy"
+
+    return Path.home() / ".cache" / "dcccpy"
+
+
+def runtime_dir(version: str = DCCCCORE_VERSION, key: str | None = None) -> Path:
+    return cache_root() / "dccccore" / version / (key or platform_key())
+
+
+def candidate_executables(base_dirs: Iterable[Path]) -> list[Path]:
+    candidates: list[Path] = []
+    for base in base_dirs:
+        for name in executable_names():
+            candidates.append(base / name)
+    return candidates
+
+
+def _main_package_vendor_dirs() -> list[Path]:
+    vendor_root = package_root() / "vendor" / "dccccore"
+    key = platform_key()
+    return [vendor_root / key, vendor_root]
+
+
+def _runtime_package_dirs() -> list[Path]:
+    try:
+        import dcccpy_linux_runtime
+    except Exception:
+        return []
+
+    root = dcccpy_linux_runtime.dccccore_root()
+    return [Path(root)]
+
+
+def _cached_dirs(version: str = DCCCCORE_VERSION) -> list[Path]:
+    return [runtime_dir(version)]
+
+
+def find_existing_dccccore(version: str = DCCCCORE_VERSION) -> Path | None:
+    for candidate in candidate_executables(_main_package_vendor_dirs()):
+        if candidate.exists():
+            return candidate
+
+    for candidate in candidate_executables(_runtime_package_dirs()):
+        if candidate.exists():
+            return candidate
+
+    for candidate in candidate_executables(_cached_dirs(version)):
+        if candidate.exists():
+            return candidate
+
+    found = shutil.which("DCCCcore")
+    return Path(found) if found else None
+
+
+def auto_download_enabled() -> bool:
+    value = os.environ.get("DCCCPY_AUTO_DOWNLOAD", "1").strip().lower()
+    return value not in {"0", "false", "no", "off"}
+
+
+def release_url(version: str = DCCCCORE_VERSION, repo: str = RELEASE_REPO, platform_name: str | None = None) -> str:
+    platform_name = platform_name or release_platform()
+    asset = f"DCCCcore-{version}-{platform_name}.zip"
+    return f"https://github.com/{repo}/releases/download/v{version}/{asset}"
+
+
+def _safe_extract(zip_file: zipfile.ZipFile, destination: Path) -> None:
+    destination = destination.resolve()
+    for member in zip_file.infolist():
+        target = (destination / member.filename).resolve()
+        if not str(target).startswith(str(destination)):
+            raise DCCCcoreDownloadError(f"Unsafe path in DCCCcore archive: {member.filename}")
+    zip_file.extractall(destination)
+
+
+def _copy_runtime_tree(extracted_root: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if destination.exists():
+        shutil.rmtree(destination)
+    shutil.copytree(extracted_root, destination)
+
+    for candidate in candidate_executables([destination]):
+        if candidate.exists() and os.name != "nt":
+            mode = candidate.stat().st_mode
+            candidate.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def download_dccccore(
+    *,
+    version: str = DCCCCORE_VERSION,
+    repo: str | None = None,
+    key: str | None = None,
+    force: bool = False,
+) -> Path:
+    key = key or platform_key()
+    destination = runtime_dir(version, key)
+    existing = next((path for path in candidate_executables([destination]) if path.exists()), None)
+    if existing is not None and not force:
+        return existing
+
+    repo = repo or os.environ.get("DCCCPY_RELEASE_REPO", RELEASE_REPO)
+    url = os.environ.get("DCCCPY_DCCCCORE_URL") or release_url(
+        version=version,
+        repo=repo,
+        platform_name=release_platform(key),
+    )
+
+    with tempfile.TemporaryDirectory(prefix="dcccpy-runtime-") as temp_name:
+        temp = Path(temp_name)
+        archive = temp / "DCCCcore.zip"
+        try:
+            with urllib.request.urlopen(url) as response, archive.open("wb") as handle:
+                shutil.copyfileobj(response, handle)
+        except Exception as exc:
+            raise DCCCcoreDownloadError(f"Failed to download DCCCcore from {url}") from exc
+
+        extract_dir = temp / "extract"
+        extract_dir.mkdir()
+        try:
+            with zipfile.ZipFile(archive) as zf:
+                _safe_extract(zf, extract_dir)
+        except Exception as exc:
+            raise DCCCcoreDownloadError(f"Failed to extract DCCCcore archive from {url}") from exc
+
+        roots = [path for path in extract_dir.iterdir() if path.is_dir()]
+        if len(roots) != 1:
+            raise DCCCcoreDownloadError(f"Expected one top-level directory in DCCCcore archive, found {len(roots)}.")
+
+        _copy_runtime_tree(roots[0], destination)
+
+    existing = next((path for path in candidate_executables([destination]) if path.exists()), None)
+    if existing is None:
+        raise DCCCcoreDownloadError(f"DCCCcore archive did not contain an executable for {key}.")
+    return existing
+
+
+def dccccore_path(
+    executable: str | os.PathLike[str] | None = None,
+    *,
+    allow_download: bool | None = None,
+    version: str = DCCCCORE_VERSION,
+) -> Path:
+    explicit = executable or os.environ.get("DCCCPY_DCCCCORE")
+    if explicit:
+        path = Path(explicit).expanduser()
+        if path.exists():
+            return path
+        raise DCCCcoreNotFoundError(f"DCCCcore executable does not exist: {path}")
+
+    existing = find_existing_dccccore(version)
+    if existing is not None:
+        return existing
+
+    should_download = auto_download_enabled() if allow_download is None else allow_download
+    if should_download:
+        return download_dccccore(version=version)
+
+    raise DCCCcoreNotFoundError(
+        "Could not find DCCCcore. Install dcccpy[linux-runtime], set DCCCPY_DCCCCORE, "
+        "put DCCCcore on PATH, or enable automatic download with DCCCPY_AUTO_DOWNLOAD=1."
+    )

dcccpy-0.1.2.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: dcccpy
+Version: 0.1.2
+Summary: Python wrapper for the DCCCcore PET biomarker command-line tool
+Author: DCCCSlicer contributors
+License-Expression: CC-BY-NC-ND-4.0
+Project-URL: Homepage, https://github.com/tctco/DCCCSlicer
+Project-URL: Repository, https://github.com/tctco/DCCCSlicer
+Project-URL: Issues, https://github.com/tctco/DCCCSlicer/issues
+Keywords: PET,neuroimaging,centiloid,DCCC,DCCCSlicer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: nibabel>=5
+Provides-Extra: linux-runtime
+Requires-Dist: dcccpy-linux-runtime==0.1.0; extra == "linux-runtime"
+
+# dcccpy
+
+`dcccpy` is a Python wrapper for the `DCCCcore` command-line tool from
+DCCCSlicer. It keeps the native C++ core as the execution engine and provides a
+small Python API for running common PET biomarker workflows.
+
+## Install
+
+The default package is slim:
+
+```bash
+pip install dcccpy
+```
+
+The first call downloads the matching `DCCCcore` release package into the local
+user cache if no native runtime is otherwise available. The slim package also
+installs `nibabel` for image loading and nibabel-style image inputs.
+
+For Linux users who prefer `pip install` to include the native runtime and avoid
+first-run download:
+
+```bash
+pip install "dcccpy[linux-runtime]"
+```
+
+## Python API
+
+```python
+import dcccpy
+
+result = dcccpy.centiloid("amyloid_pet.nii", skip_normalization=True)
+print(result.metrics)
+print(result.output)
+```
+
+The `output` argument is optional for single-image Python calls. When omitted,
+`dcccpy` creates a temporary output NIfTI path and returns it in the result.
+Relative input and output paths are resolved from the current Python working
+directory before `DCCCcore` is invoked.
+
+```python
+result = dcccpy.centiloid("amyloid_pet.nii")
+print(result.output)           # temporary output path
+print(result.metrics.get("fbp"))
+```
+
+The wrapper accepts nibabel-style image objects with `to_filename()`:
+
+```python
+import nibabel as nib
+import dcccpy
+
+image = nib.load("amyloid_pet.nii.gz")
+result = dcccpy.centiloid(image, skip_normalization=True)
+output_image = result.load_output()
+```
+
+Common helpers mirror `DCCCcore` subcommands:
+
+```python
+dcccpy.centiloid("amyloid.nii", suvr=True)
+dcccpy.centaurz("tau.nii", report_detailed_regions=True)
+dcccpy.fillstates("fdg.nii", tracer="fdg")
+dcccpy.normalize("pet.nii", iterative=True)
+dcccpy.run(["centiloid", "--input", "a.nii", "--output", "b.nii"])
+```
+
+Each helper returns `DCCCResult` with:
+
+- `returncode`
+- `stdout` / `stderr`
+- `output`
+- `metrics`, parsed from numeric lines in stdout
+- `load_output()`, which loads the output with nibabel
+
+## Command Line
+
+`dcccpy` also forwards raw arguments to `DCCCcore`:
+
+```bash
+dcccpy --help
+dcccpy centiloid --input amyloid_pet.nii --output result.nii
+```
+
+## Runtime lookup
+
+At runtime, `dcccpy` looks for `DCCCcore` in this order:
+
+1. `DCCCPY_DCCCCORE` environment variable.
+2. A vendored binary inside the installed `dcccpy` wheel.
+3. A binary from `dcccpy-linux-runtime`, installed by `dcccpy[linux-runtime]`.
+4. The local dcccpy cache populated by automatic download.
+5. `DCCCcore` on `PATH`.
+6. Automatic download from GitHub releases, unless disabled.
+
+Useful environment variables:
+
+- `DCCCPY_DCCCCORE`: exact path to a `DCCCcore` executable.
+- `DCCCPY_AUTO_DOWNLOAD=0`: disable first-run automatic download.
+- `DCCCPY_CACHE_DIR`: override the runtime cache directory.
+- `DCCCPY_RELEASE_REPO`: override the GitHub release repository.
+- `DCCCPY_DCCCCORE_URL`: override the release asset URL.
+
+## Runtime Packaging
+
+Release wheels should vendor the matching `DCCCcore` runtime tree before build:
+
+```bash
+python scripts/vendor_dccccore.py --version 4.2.3 --release-platform ubuntu-latest-x64
+python -m build --wheel
+```
+
+The source tree intentionally does not commit the vendored runtime because it
+contains large ONNX model and NIfTI runtime assets.
+
+The preferred distribution layout is:
+
+- `dcccpy`: slim Python package with nibabel; downloads runtime on first use.
+- `dcccpy-linux-runtime`: optional Linux runtime wheel.
+- `dcccpy[linux-runtime]`: installs both packages.
+
+## Packaging note
+
+The Linux `DCCCcore-4.2.3-ubuntu-latest-x64.zip` release asset contains the
+native executable, `libtbb`, ONNX registration/decoupling models, configuration
+files, and NIfTI template/mask assets. That full runtime is the correct unit to
+vendor for a wheel that works immediately after `pip install dcccpy`.
+
+The full Linux runtime wheel is about 167 MB for version 4.2.3, so a public
+PyPI upload may require a file size limit increase unless a future release
+splits a smaller runtime profile from the full `DCCCcore` package.

dcccpy-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+dcccpy/__init__.py,sha256=4idApts9ezIKuaQLtp4t0cbQ7XSAjPgByAKur38M5Lg,769
+dcccpy/cli.py,sha256=sRTu6kOA79KzGYYXKvqWUwQb0RxZnV3B0UkbV4jFoCE,582
+dcccpy/core.py,sha256=6Ic3SQ8EEVJDuNa_LLUGyhdAEF4QEqgQBitjLLfquRU,11013
+dcccpy/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+dcccpy/runtime.py,sha256=BxiVkq-36pVR6Ze-wLtqUOW9G7GeDeA4tHf1v60z7fM,7568
+dcccpy-0.1.2.dist-info/METADATA,sha256=xmZ0ds64GInXcL8acEqaz1I7EbuL7_WT36N7XzlaDZo,4933
+dcccpy-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dcccpy-0.1.2.dist-info/entry_points.txt,sha256=oPy0K-Lgnn7bd_IupKYTRe3Z2K53gJI4Osx7cA92hks,43
+dcccpy-0.1.2.dist-info/top_level.txt,sha256=KeC_Zh9c6znBR8V5IHmeAglErsBEbmfTYSgCxgJkp1U,7
+dcccpy-0.1.2.dist-info/RECORD,,

dcccpy-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dcccpy-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dcccpy = dcccpy.cli:main

dcccpy-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+dcccpy