photon_mosaic.core.zarrrois#

Zarr format for ROI data.

Classes#

ZarrRois

ROI extractor backed by a zarr group on disk.

Functions#

add_rois_to_zarr_group

Save ROI masks and metadata to a zarr group.

Functions

add_rois_to_zarr_group(rois, zarr_group, ...)

Save ROI masks and metadata to a zarr group.

Classes

ZarrRois(zarr_path[, zarr_group_name, ...])

ROI extractor backed by a zarr group on disk.

class photon_mosaic.core.zarrrois.ZarrRois(zarr_path, zarr_group_name='rois', storage_options=None)[source]#

ROI extractor backed by a zarr group on disk.

Parameters:
  • zarr_path (str or Path) – Path to the zarr store.

  • zarr_group_name (str) – Name of the group within the store containing ROI data.

  • storage_options (dict | None) – fsspec storage options for remote zarr stores.

Methods

get_roi_image_masks([roi_ids])

Get the image mask for a specific ROI.

write_rois(rois, folder_path[, overwrite, ...])

Write ROI data to a Zarr store and return a reloaded ROIs.

get_roi_image_masks(roi_ids=None)[source]#

Get the image mask for a specific ROI. The image mask can be binary or weighted and 2D (single plane) or 3D (multi-plane).

Subclasses may return either a dense np.ndarray or a sparse pydata/sparse array (e.g. sparse.GCXS). Each ROI typically occupies only a tiny fraction of the full imaging volume, so a sparse representation avoids the out-of-memory errors a dense array would cause once there are many ROIs over a large (e.g. volumetric) field of view – see photon-mosaic#103. Callers that need actual pixel values (e.g. for plotting) should call .todense() explicitly rather than assume a dense array.

Parameters:

roi_ids (list[int | str] | None) – The IDs of the ROIs.

Returns:

The image mask for the specified ROIs.

Return type:

np.ndarray | sparse.SparseArray

static write_rois(rois, folder_path, overwrite=False, storage_options=None, **kwargs)[source]#

Write ROI data to a Zarr store and return a reloaded ROIs.

Parameters:
  • rois (BaseRois) – ROIs instance to write.

  • folder_path (str | Path) – Output path for the Zarr store.

  • overwrite (bool) – If True, overwrite an existing store at folder_path.

  • storage_options (dict | None) – Optional storage options passed to Zarr I/O.

  • **kwargs – Additional dataset creation options forwarded to add_rois_to_zarr_group() (for example, compression/chunking options).

Returns:

A ZarrRois instance opened from the written store.

Return type:

ZarrRois

Notes

Implemented as a static method so it can be called by BaseRois.save() without instantiating ZarrRois.

This is its only intended use.

photon_mosaic.core.zarrrois.add_rois_to_zarr_group(rois, zarr_group, **kwargs)[source]#

Save ROI masks and metadata to a zarr group.

Parameters:
  • rois (BaseRois) – The ROIs object to save.

  • zarr_group (zarr.hierarchy.Group) – The zarr group to write to.

  • **kwargs (Additional kwargs) – Additional zarr dataset creation options (e.g., compressor).

Return type:

None