DeStripe#

from leonardo_toolset import DeStripe
class DeStripe(resample_ratio=3, guided_upsample_kernel=49, hessian_kernel_sigma=1, lambda_masking_mse=1, lambda_tv=1, lambda_hessian=1, inc=16, n_epochs=300, wedge_degree=29, n_neighbors=16, backend='jax', device=None)#

Bases: object

Main class for Leonardo-DeStripe.

This class handles the workflow for stripe removal in data (single volume or multiple ones with opposite illumination or detection simultaneously).

Initialize the DeStripe class with destriping and training parameters.

Parameters

  • resample_ratio (int) – int, optional Downsampling factor along the stripe direction when training the graph neural network.

  • guided_upsample_kernel (int) – int, optional Kernel size for guided upsampling.

  • hessian_kernel_sigma (float) – float, optional Sigma to define Gaussian Hessian kernel.

  • lambda_masking_mse (float) – float, optional Weight for fidelity term in loss.

  • lambda_tv (float) – float, optional Weight for total variation-based regularization term in loss.

  • lambda_hessian (float) – float, optional Weight for Hessian-based regularization term in loss.

  • inc (int) – int, optional Dimension of the latent space in the graph neural network.

  • n_epochs (int) – int, optional Number of epochs to train the graph neural network.

  • wedge_degree (float) – float, optional Angular coverage of the wedge-shaped mask in Fourier.

  • n_neighbors (int) – int, optional Number of neighbors in the graph neural network.

  • backend (str) – str, optional Backend to use (‘jax’ or ‘torch’).

  • device (str) – str, optional Device to use (‘cuda’, ‘cpu’).

train(save_path=None, is_vertical=None, x=None, mask=None, fusion_mask=None, illu_orient=None, angle_offset=None, display=False, display_angle_orientation=False, non_positive=True, allow_stripe_deviation=False, **kwargs)#

Main training workflow for Leonardo-DeStripe (also for Leonardo-DeStripe-Fuse).

Parameters

  • save_path (Optional[str]) – str Absolute path to save the result volume. The file name must end with .tif or .tiff, as the output is currently supported only in TIF/TIFF format.

  • is_vertical (Optional[bool]) – bool Whether the stripes are vertical.

  • x (Optional[Union[str, numpy.ndarray, dask.array.Array]]) – dask.array.Array | np.ndarray | str Input image array or path.

  • mask (Optional[Union[str, numpy.ndarray, dask.array.Array]]) – dask.array.Array | np.ndarray | str Optional mask for the image. Enables human-guided intervention during destriping. In regions where the mask equals 1, the graph neural network will avoid modifying the underlying structures. This is useful when users have prior knowledge about specific regions that should remain untouched (e.g., important anatomical features). If not provided, the network will operate on the entire image.

  • fusion_mask (Optional[Union[numpy.ndarray, dask.array.Array]]) – np.ndarray or dask.array Fusion mask for the input image. This is needed in the Leonardo-DeStripe-Fuse mode, in which multiple images with opposite illumination or detection are jointly destriped. To use this more powerful mode, first run Leonardo-Fuse with save_separate_results=True to generate the necessary intermediate results. The location of the generated fusion mask can then be found in the YAML metadata under save_path/save_folder. For details about the Leonardo-DeStripe-Fuse mode, please refer to the Note below.

  • illu_orient (Optional[str]) – str, optional Illumination orientation in the image space of x. More information please refer to the Note below

  • display (bool) – bool Whether to display destriped results in matplotlib in real-time.

  • display_angle_orientation (bool) – bool Whether to display check for angle orientation.

  • non_positive (bool) – bool Whether the stripes are non-positive only. It only affects post-processing module for sample structure preservation (ill. prior, see manuscript). If illu_orient is not specified, post-processing will be disabled, and this variable will have no effect.

  • allow_stripe_deviation (bool) – bool Whether to enable an extra penalty on stripes during post-processing. When True, stripes will be suppressed more strongly at the potential cost of slightly sacrificing sample details. Set True for slightly tilted/wavy stripes or slow illumination drift; keep False to better preserve fine sample details. If illu_orient is not specified (post-processing disabled), this flag has no effect.

  • **kwargs – Additional keyword arguments for advanced workflows.

  • angle_offset (Optional[list[float]]) –

Returns

The destriped output image or volume.

Return type

np.ndarray

Note

This function supports two modes:

1. Leonardo-DeStripe (default): Provide a single input x and a corresponding illumination angle offset as angle_offset via **kwargs. This is the standard Leonardo-DeStripe mode.

Important

If x is given, you must also provide angle_offset via **kwargs.

2. Compose (multi-view) destriping: For light-sheet datasets with dual-sided illumination, detection, or both, you can instead provide multiple inputs x_0, x_1, … and corresponding offsets angle_offset_0, angle_offset_1, … via **kwargs. These will be jointly destriped and fused. This is the advanced Leonardo-DeStripe-Fuse mode.

Note

Although Leonardo-DeSrtripe(-Fuse) is mainly empowered by a graph a neural network, there is an additional post-processing module to further preserve sample details by using illumination priors. This can be automatically turned on by giving parameter illu_orient (in Leonardo-DeStripe mode) through **kwargs. This parameter specifies the direction of illumination in the image space.

  • Valid options are: "top", "bottom", "left", "right", and dual-side illuminations: "top-bottom", "left-right" (e.g., Ultramicroscope Blaze).

  • In Leonardo-DeStripe-Fuse mode, provide multiple orientations via illu_orient_0, illu_orient_1, … inside **kwargs.

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.

  • 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.