photon_mosaic.core.binaryrois#

Binary folder format for ROI data.

Classes#

BinaryRois

ROI extractor that loads image masks from a .npy file on disk.

BinaryFolderRois

ROI extractor that loads from a folder containing masks, metadata, and provenance.

Classes

BinaryFolderRois(folder_path)

ROI extractor that loads from a folder saved by BaseRois.save().

BinaryRois(file_path, sampling_frequency, ...)

ROI extractor backed by .npy or .npz files on disk.

class photon_mosaic.core.binaryrois.BinaryRois(file_path, sampling_frequency, roi_ids, shape)[source]#

ROI extractor backed by .npy or .npz files on disk.

Parameters:
  • file_path (str or Path) – Path to the file containing image masks (num_rois, height, width[, planes]) – .npy for a dense array, .npz for a sparse pydata/sparse array.

  • sampling_frequency (float) – Sampling frequency of the ROIs in Hz.

  • roi_ids (ArrayLike) – Array of ROI IDs.

  • shape (tuple) – Shape of the ROI masks (height, width[, planes]).

Methods

get_roi_image_masks([roi_ids])

Get the image mask for a specific ROI.

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

class photon_mosaic.core.binaryrois.BinaryFolderRois(folder_path)[source]#

ROI extractor that loads from a folder saved by BaseRois.save().

The folder must contain: - roi_image_masks.npy (dense) or roi_image_masks.npz (sparse) — the mask data - roi_ids.npy — the ROI IDs - metadata.json — sampling_frequency and shape - binary.json — provenance file (written by BaseRois.save())

Optionally: - properties/ folder with per-ROI property .npy files - annotations.json with annotations

Parameters:

folder_path (str or Path) – Path to the folder.

Methods

write_rois(rois, folder_path[, overwrite])

Write ROI data as binary into a folder and return a reloaded ROIs.

static write_rois(rois, folder_path, overwrite=False)[source]#

Write ROI data as binary into a folder 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.

Returns:

A BinaryFolderRois instance.

Return type:

BinaryFolderRois

Notes

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

This is its only intended use.