feat: deprecate auto-metadata helpers, bump to 0.15.0 (C8)

Final commit of the asset-centric API redesign branch. Marks the four
auto-discovery convenience helpers as deprecated (they have clean
``Asset``-based replacements with no internal use), bumps the version,
and documents the redesign in the CHANGELOG.

Deprecated (DeprecationWarning, will be removed in a future release):
- ``neuroglancer_to_ccf_auto_metadata``
- ``swc_data_to_ccf_auto_metadata``
- ``indices_to_ccf_auto_metadata``
- ``ccf_to_indices_auto_metadata``

Each warning message names the precise ``Asset.from_*().transform(...)``
replacement.

The lower-level free functions (``zarr_to_sitk`` / ``zarr_to_ants`` /
``zarr_to_sitk_stub`` / ``mimic_pipeline_zarr_to_anatomical_stub`` /
``neuroglancer_to_ccf`` / ``ccf_to_indices``) are NOT deprecated this
release: they are still called internally by the new ``Asset`` façade
and the transform-graph edges. Deprecating them would generate
spurious warnings from internal use. They will be deprecated once
``Asset`` calls are routed away from them in a future commit.

A pyproject ``filterwarnings`` entry suppresses the new
DeprecationWarnings inside our own test suite — the legacy paths are
still exercised as regression coverage for the deprecation cycle.

Version: 0.14.0 → 0.15.0. Stays on 0.x per the agreed BC plan.

All 173 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: galenlynch

CHANGELOG.md

@@ -1,3 +1,68 @@
+## v0.15.0 (2026-04-28)
+
+### Feat
+
+- New asset-centric API. The package's recommended entry point is now
+  `Asset` (with `Asset.from_zarr`, `Asset.from_root`,
+  `Asset.from_neuroglancer`, plus a no-I/O `Asset(zarr_uri, metadata,
+  processing)` constructor). A single `Asset` instance opens its Zarr
+  exactly once and resolves transform-chain paths exactly once,
+  regardless of how many methods participate in a workflow.
+- `Points` + `Space` make coordinate spaces first-class. Five spaces
+  are recognised: `ZARR_INDICES`, `LS_SCALED_MM`, `LS_ANATOMICAL_MM`,
+  `LS_PIPELINE_ANATOMICAL_MM`, `CCF_MM`. `Asset.transform(points,
+  to=Space.X)` walks a small graph of named edges to project them.
+  Every previous combination of `*_to_ccf` / `ccf_to_*` /
+  `*_to_indices` is now expressible as one `transform` call.
+- `Origin` value type replaces the legacy
+  `(set_origin, set_corner, set_corner_lps)` triple on the image
+  builders: `Origin.default()`, `Origin.at(point)`,
+  `Origin.at_corner(code, lps_point)`.
+- `Points.from_neuroglancer` and `Points.from_swc` provide one-line
+  conversion from NG state and raw SWC arrays into the package's
+  canonical representation.
+
+### Refactor
+
+- The package source is reorganised into focused subpackages:
+  `io/` (Zarr opening, metadata parsing, processing-JSON parsing,
+  transform-chain resolution, URI helpers), `domain/` (overlay
+  protocol, selector, concrete overlays), `formats/` (Neuroglancer
+  and SWC readers), and the new top-level modules `asset.py`,
+  `points.py`, `image.py`, `origin.py`. The legacy modules
+  (`zarr.py`, `neuroglancer.py`, `pipeline_domain_selector.py`,
+  `pipeline_transformed.py`) keep working as re-export shims and
+  continue to pass all existing tests.
+- The SimpleITK and ANTs pipeline-overlay paths (~320 LOC of
+  duplication) collapse into a single type-dispatching
+  `apply_pipeline_overlays` plus a small pure helper
+  (`_to_ants_convention`) that encodes the level > 0 spacing-reverse
+  + opposite-corner origin recompute. The level > 0 ANTs math is now
+  pinned by dedicated regression tests.
+
+### Deprecations
+
+The following auto-discovery convenience helpers emit
+`DeprecationWarning` and will be removed in a future release. Each
+points to its `Asset`-based replacement:
+
+- `mimic_pipeline_zarr_to_anatomical_stub` (still callable but
+  superseded by `Asset(...).stub(pipeline=True)`; not warned this
+  release because of internal use).
+- `neuroglancer_to_ccf_auto_metadata` →
+  `Asset.from_neuroglancer(ng).transform(Points.from_neuroglancer(ng), to=Space.CCF_MM)`
+- `swc_data_to_ccf_auto_metadata` →
+  `Asset.from_root(uri).transform(Points.from_swc(...), to=Space.CCF_MM)`
+- `indices_to_ccf_auto_metadata` →
+  `Asset.from_zarr(uri).transform(Points(idx, Space.ZARR_INDICES), to=Space.CCF_MM)`
+- `ccf_to_indices_auto_metadata` →
+  `Asset.from_zarr(uri).transform(Points(ccf, Space.CCF_MM), to=Space.ZARR_INDICES)`
+
+The lower-level free functions in `pipeline_transformed` and `zarr`
+(e.g. `neuroglancer_to_ccf`, `ccf_to_indices`, `zarr_to_sitk`,
+`zarr_to_sitk_stub`, `mimic_pipeline_zarr_to_anatomical_stub`) are
+unchanged for now and remain part of the package surface.
+
 ## v0.14.0 (2026-02-11)
 
 ### Feat

pyproject.toml

@@ -13,7 +13,7 @@ authors = [
 ]
 classifiers = ["Programming Language :: Python :: 3"]
 readme = "README.md"
-version = "0.14.0"
+version = "0.15.0"
 
 dependencies = [
   "aind-anatomical-utils>=0.4",
@@ -73,6 +73,14 @@ ignore-words-list = "nd"
 [tool.pytest.ini_options]
 addopts = "--strict-markers --tb=short --cov=src --cov-report=term-missing --cov-fail-under=0"
 testpaths = ["tests"]
+# Suppress DeprecationWarnings emitted by our own legacy free functions —
+# the test suite still exercises them as regression coverage for the
+# 0.15 → 0.16 deprecation cycle. Drop this filter once the legacy paths
+# are removed.
+filterwarnings = [
+    "ignore::DeprecationWarning:aind_zarr_utils.pipeline_transformed",
+    "ignore::DeprecationWarning:aind_zarr_utils.zarr",
+]
 
 [tool.interrogate]
 ignore-init-method = true

src/aind_zarr_utils/pipeline_transformed.py

@@ -16,6 +16,7 @@
 from __future__ import annotations
 
 import os
+import warnings
 from typing import TYPE_CHECKING, Any, TypeVar
 
 import numpy as np
@@ -837,7 +838,26 @@ def ccf_to_indices_auto_metadata(
     --------
     >>> ccf_pts = {"layer1": np.array([[5000, 6000, 7000]])}
     >>> indices_pts = ccf_to_indices_auto_metadata(ccf_pts, zarr_uri)
+
+    .. deprecated:: 0.15
+        Use :class:`~aind_zarr_utils.asset.Asset` instead::
+
+            asset = Asset.from_zarr(zarr_uri)
+            indices = asset.transform(
+                Points(ccf_points, Space.CCF_MM),
+                to=Space.ZARR_INDICES,
+            ).values
+
+        This shim will be removed in a future release.
     """
+    warnings.warn(
+        "ccf_to_indices_auto_metadata is deprecated; use "
+        "Asset.from_zarr(zarr_uri).transform(Points(ccf_points, Space.CCF_MM),"
+        " to=Space.ZARR_INDICES) instead. This shim will be removed in a "
+        "future release.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     alignment_zarr_uri, metadata, processing_data = alignment_zarr_uri_and_metadata_from_zarr_or_asset_pathlike(
         a_zarr_uri=zarr_uri
     )
@@ -895,7 +915,26 @@ def neuroglancer_to_ccf_auto_metadata(
     ------
     ValueError
         If no image sources can be found in ``neuroglancer_data``.
+
+    .. deprecated:: 0.15
+        Use :class:`~aind_zarr_utils.asset.Asset` instead::
+
+            asset = Asset.from_neuroglancer(neuroglancer_data)
+            ccf = asset.transform(
+                Points.from_neuroglancer(neuroglancer_data),
+                to=Space.CCF_MM,
+            )
+
+        This shim will be removed in a future release.
     """
+    warnings.warn(
+        "neuroglancer_to_ccf_auto_metadata is deprecated; use "
+        "Asset.from_neuroglancer(ng).transform(Points.from_neuroglancer(ng),"
+        " to=Space.CCF_MM) instead. This shim will be removed in a future "
+        "release.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     if asset_uri is None:
         image_sources = get_image_sources(neuroglancer_data, remove_zarr_protocol=True)
         # Get first image source in dict
@@ -1056,7 +1095,30 @@ def swc_data_to_ccf_auto_metadata(
     -------
     dict[str, NDArray]
         Mapping neuron ID → (N, 3) array of anatomical CCF coordinates in LPS.
+
+    .. deprecated:: 0.15
+        Use :class:`~aind_zarr_utils.asset.Asset` instead::
+
+            asset = Asset.from_root(asset_uri)
+            ccf = asset.transform(
+                Points.from_swc(
+                    swc_point_dict,
+                    axis_order=swc_point_order,
+                    units=swc_point_units,
+                ),
+                to=Space.CCF_MM,
+            )
+
+        This shim will be removed in a future release.
     """
+    warnings.warn(
+        "swc_data_to_ccf_auto_metadata is deprecated; use "
+        "Asset.from_root(asset_uri).transform(Points.from_swc(swc_point_dict, "
+        "axis_order=..., units=...), to=Space.CCF_MM) instead. This shim "
+        "will be removed in a future release.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     zarr_uri, metadata, processing_data = alignment_zarr_uri_and_metadata_from_zarr_or_asset_pathlike(
         asset_uri=asset_uri
     )
@@ -1126,7 +1188,26 @@ def indices_to_ccf_auto_metadata(
     ...     indices,
     ...     zarr_uri="s3://aind-open-data/dataset_123/image.zarr"
     ... )
+
+    .. deprecated:: 0.15
+        Use :class:`~aind_zarr_utils.asset.Asset` instead::
+
+            asset = Asset.from_zarr(zarr_uri)
+            ccf = asset.transform(
+                Points(annotation_indices, Space.ZARR_INDICES),
+                to=Space.CCF_MM,
+            )
+
+        This shim will be removed in a future release.
     """
+    warnings.warn(
+        "indices_to_ccf_auto_metadata is deprecated; use "
+        "Asset.from_zarr(zarr_uri).transform(Points(annotation_indices, "
+        "Space.ZARR_INDICES), to=Space.CCF_MM) instead. This shim will be "
+        "removed in a future release.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     alignment_zarr_uri, metadata, processing_data = alignment_zarr_uri_and_metadata_from_zarr_or_asset_pathlike(
         a_zarr_uri=zarr_uri
     )