Add atlas region visualization method to ZarrNii for QC reporting

[Copilot]

Implements 2D slice visualization of atlas regions with optional centroid overlay for quality control reports. Centroids are rendered with distance-based opacity using parametrized transfer functions.

Changes

Main method (ZarrNii.visualize_atlas_regions):

• Implemented as a method of the ZarrNii class (not a standalone function)
• Atlas parameter used only to identify region centers/bounding boxes
• Image data visualized comes from self (the ZarrNii instance)
• Generates 2D slices centered on specified atlas regions
• Supports axial, sagittal, coronal planes
• Overlays centroids from numpy arrays, .npy, .parquet, or DataFrames
• Filters centroids by configurable max distance from slice plane
• Applies parametrized opacity transfer functions (linear, quadratic, exponential, gaussian)
• Returns list of matplotlib Figure objects

Helper functions:

• _load_centroids_from_file() - Loads centroids from multiple formats with validation (in atlas.py)
• _compute_out_of_plane_distance() - Calculates centroid distance from slice plane (in atlas.py)
• _filter_centroids_by_distance() - Filters by distance threshold (in atlas.py)
• _compute_opacity_from_distance() - Applies transfer function (4 types, parametrized) (in atlas.py)
• _extract_2d_slice_from_image() - Private method in ZarrNii for extracting 2D slices

Usage

from zarrnii import ZarrNii, ZarrNiiAtlas

# Load atlas and image
atlas = ZarrNiiAtlas.from_files("atlas.nii.gz", "labels.tsv")
image = ZarrNii.from_ome_zarr("fluorescence.zarr")

# Visualize image in context of atlas regions
figs = image.visualize_atlas_regions(
    atlas=atlas,
    region_ids=["Hippocampus", "Amygdala"],
    centroids="cell_centroids.parquet",
    planes=["axial", "coronal"],
    max_centroid_distance=5.0,
    opacity_function="gaussian",
    opacity_params={"sigma_fraction": 0.25}
)

for i, fig in enumerate(figs):
    fig.savefig(f"qc_{i}.png", dpi=150)

# Or visualize the atlas itself
figs = atlas.visualize_atlas_regions(
    atlas=atlas,
    region_ids=["Hippocampus", "Amygdala"],
    planes=["axial"]
)

Implementation notes

• Method-based API allows visualizing any image in the context of atlas-defined regions
• Atlas parameter provides only region metadata (centers, bounding boxes)
• Image data comes from the ZarrNii instance the method is called on
• Physical coordinates used throughout for proper spatial alignment
• Opacity transfer functions normalize distance to [0,1] before applying function
• Slice position auto-calculated from region bounding box center
• Helper functions for centroids and opacity are in atlas.py (prefixed with _)
• Private slice extraction method added to ZarrNii class
• 25 tests added covering all functionality and edge cases

Original prompt

Create a zarrnii atlas function to generate 2d visualizations of the the image for qc reports. One func arg should be a list of atlas structures to visualize, another opt arg should be centroids (array npy or parquet). Other opt args are the 2d planes to use (ax sag cor), the maximum patch size. The functikn will get 2d slices centrred at each region, and render centroids on them as dot markers, using an opacity transfer function based on the out of plane distance to the slice, first filtering to only include centroids up to a macimum distance from the plane. Make modular functions to calcualte these things. Have the distance tramsger function parametrizrd from function args too. Return lists of figures.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[akhanf]

@copilot: the atlas input ZarrNiiAtlas is only used to get the region centres/bounding boxes, the image to actually grab slices from and visualize should be the self ZarrNii (make this a member function of the ZarrNii class). Can use the crop_centered function to get the slice to visualize.

[Copilot]

@copilot: the atlas input ZarrNiiAtlas is only used to get the region centres/bounding boxes, the image to actually grab slices from and visualize should be the self ZarrNii (make this a member functi...

Done in ad1934f. Refactored to make visualize_atlas_regions a method of ZarrNii class. The atlas parameter is now only used to get region centers/bounding boxes, while the image data visualized comes from self. This allows visualizing any image (e.g., fluorescence channel) in the context of atlas-defined regions.

API change:

# Old: visualize_atlas_regions(atlas, region_ids=[1, 2])
# New: image.visualize_atlas_regions(atlas, region_ids=[1, 2])

The method uses _extract_2d_slice_from_image internally (similar approach to the helper you mentioned, though not using crop_centered directly for the 2D slice extraction).