FUSE_det#

from leonardo_toolset import FUSE_det
class FUSE_det(require_precropping=True, precropping_params=[], resample_ratio=2, window_size=[5, 59], poly_order=[2, 2], n_epochs=50, require_segmentation=True, skip_illuFusion=True, device=None, registration_params=None)#

Bases: object

Main class for Leonardo-Fuse (along detection).

This class handles the workflow for fusion in data with dual-sided detection (or mimicked by rotation) and/or dual-sided illumination.

Initialize the FUSE_det class with training and registration parameters (if needed).

Parameters

  • require_precropping (bool) – bool Whether to perform pre-cropping before training. If True, the model will automatically estimate a bounding box warping the foreground region based on which to estimate the fusion boundary.

  • precropping_params (list[int, int, int, int]) – list of int Manually define pre-cropping regions as [x_start, x_end, y_start, y_end]. regions outside will be considered as background and will not be considered for estimating the fusion boundary.

  • resample_ratio (int) – int Downsampling factor when estimating fusion boundaries.

  • window_size (list[int, int]) – list of int The size of the Savitzky-Golay filter window as [z, xy]. z is the window size along the depth (z-axis), and xy is the window size along the x/y plane.

  • poly_order (list[int, int]) – list of int Polynomial order for the Savitzky-Golay filter in [z, xy] directions.

  • n_epochs (int) – int Number of optimization epochs for estimating fusion boundary.

  • require_segmentation (bool) – bool Whether segmentation is required as part of the fusion pipeline.

  • skip_illuFusion (bool) – bool Whether to skip Leonardo-Fuse (along illumination). If True, the model will look for necessary files under save_path and save_folder (as provided in the train() function). If the files are found, FUSE_illu will be skipped; otherwise, it will be executed.

  • device (str) – str Target computation device, e.g., ‘cuda’ or ‘cpu’. If None, defaults to available GPU.

  • registration_params – dict, optional Optional dictionary to specify registration behavior. Valid keys include: - use_exist_reg (bool): Whether to use existing registration results. - require_reg_finetune (bool): Whether to perform fine-tuning registration. - axial_downsample (int): Downsampling factor along the axial direction. - lateral_downsample (int): Downsampling factor along the lateral direction. - skip_refine_registration (bool): Whether to skip fine registration (only for Leonardo-Fuse with downsample).

train(require_registration, require_flipping_along_illu_for_dorsaldet, require_flipping_along_det_for_dorsaldet, data_path='', sparse_sample=False, top_illu_ventral_det_data=None, bottom_illu_ventral_det_data=None, top_illu_dorsal_det_data=None, bottom_illu_dorsal_det_data=None, left_illu_ventral_det_data=None, right_illu_ventral_det_data=None, left_illu_dorsal_det_data=None, right_illu_dorsal_det_data=None, ventral_det_data=None, dorsal_det_data=None, save_path='', save_folder='', save_separate_results=False, z_spacing=None, xy_spacing=None, left_right=None, xy_downsample_ratio=None, z_downsample_ratio=None, display=True)#

Main training workflow for Leonardo-Fuse (along detection).

This function supports fusion of light sheet data acquired with dual-sided detection (or mimicked by physical rotation) and/or dual-sided illumination.

Input fields should be populated accordingly:

  • If fusion is required only along the detection axis (i.e., no illumination-side fusion is required), provide ventral_det_data and dorsal_det_data only.

  • If fusion along the illumination axis is also required:

    • For light sheet systems with top–bottom illumination (in the image space), use top_illu_* and bottom_illu_*.

    • For systems with left–right illumination (in the image space), use left_illu_* and right_illu_*.

Parameters

  • require_registration (bool) – bool Whether registration is needed.

  • require_flipping_along_illu_for_dorsaldet (bool) – bool Whether to flip the data with dorsal detection along the illumination axis. This is required to ensure alignment with the ventral view.

  • require_flipping_along_det_for_dorsaldet (bool) – bool Whether to flip the data with dorsal detection along the detection (z) axis. This is required to ensure alignment with the ventral view.

  • data_path (str) – str, optional Root directory to prepend when input data is provided as a relative path (str). Ignored if inputs are arrays or lists of absolute paths.

  • top_illu_ventral_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Top illumination, ventral detection data. Can be: - A 3D array (Dask or NumPy), - A single file path (str), relative to data_path.

  • bottom_illu_ventral_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Bottom illumination, ventral detection data. See top_illu_ventral_det_data for supported formats.

  • top_illu_dorsal_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Top illumination, dorsal detection data. See top_illu_ventral_det_data for supported formats.

  • bottom_illu_dorsal_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Bottom illumination, dorsal detection data. See top_illu_ventral_det_data for supported formats.

  • left_illu_ventral_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Left illumination, ventral detection data.

  • right_illu_ventral_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Right illumination, ventral detection data. See top_illu_ventral_det_data for supported formats.

  • left_illu_dorsal_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Left illumination, dorsal detection data. See top_illu_ventral_det_data for supported formats.

  • right_illu_dorsal_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str]]) – dask.array.Array | np.ndarray | str Right illumination, dorsal detection data. See top_illu_ventral_det_data for supported formats.

  • ventral_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str, list[str]]]) – dask.array.Array | np.ndarray | str | list[str] Ventral detection data. Can be: - A 3D array (Dask or NumPy), - A single path (str), relative to data_path, - A list of absolute file paths (list[str]), treated as an image sequence.

  • dorsal_det_data (Optional[Union[dask.array.Array, numpy.ndarray, str, list[str]]]) – dask.array.Array | np.ndarray | str | list[str] Dorsal detection data. See ventral_det_data for supported formats and restrictions.

  • save_path (str) – str Root path where output results will be saved.

  • save_folder (str) – str Name of the subfolder under save_path to save output files.

  • save_separate_results (bool) – bool, optional Whether to save the fusion map as float32 files. Set to True only if you plan to run Leonardo-DeStripe-Fuse afterward.

  • z_spacing (Optional[float]) – float Voxel spacing along the axial (z) direction. Required only if require_registration is True.

  • xy_spacing (Optional[float]) – float Voxel spacing along the lateral (xy) plane. Required only if require_registration is True.

  • left_right (Optional[bool]) – bool Whether the illumination direction is horizontal (True) or vertical (False) in the image space. Only relevant when ventral_det_data and dorsal_det_data are used.

  • xy_downsample_ratio (Optional[int]) – int, optional Downsampling factor applied in the lateral (xy) plane in big data mode.

  • z_downsample_ratio (Optional[int]) – int, optional Downsampling factor applied along the axial (z) direction in big data mode.

  • display (bool) – bool, optional Whether to visualize intermediate or final results using matplotlib.

  • sparse_sample – bool Whether the specimen is mainly sparse structures. If True, the fusion algorithm will adjust segmentation behavior.

Returns

The fused output image.

Return type

np.ndarray

Notes

  • Input format: All input volumes must be in (Z, X, Y) format. Inputs must not contain channel dimensions. If your data includes channels (e.g., shape (Z, X, Y, C) or (T, C, Z, X, Y)), please extract the relevant channel first.

  • Big data mode: This mode is automatically enabled when z_downsample_ratio > 1 or xy_downsample_ratio > 1. It is currently only supported when ventral_det_data and dorsal_det_data are provided. Four-view illumination fusion is not yet supported in big data mode.

  • File compatibility: .tif files are reliably supported. Some .ome.tif files may cause issues depending on your bioio version. In such cases, please load the file manually and pass a np.ndarray instead.