stitch

stitch#

Functions to assemble tiled images into fullscale mosaics. Uses out-of-memory computation for the assembly of larger than memory image mosaics.

class scportrait.tools.stitch._stitch.Stitcher(input_dir: str, slidename: str, outdir: str, stitching_channel: str, pattern: str, overlap: float = 0.1, max_shift: float = 30, filter_sigma: int = 0, do_intensity_rescale: bool | str = True, rescale_range: tuple = (1, 99), channel_order: list[str] = None, reader_type='FilePatternReaderRescale', orientation: dict = None, plot_QC: bool = True, overwrite: bool = False, cache: str = None)#

Class for stitching of image tiles to assemble a mosaic.

Parameters:

  • input_dir (str) – Directory containing the input image tiles.

  • slidename (str) – Name of the slide.

  • outdir (str) – Output directory to save the stitched mosaic.

  • stitching_channel (str) – Name of the channel to be used for stitching.

  • pattern (str) – File pattern to match the image tiles.

  • overlap (float, optional) – Overlap between adjacent image tiles (default is 0.1).

  • max_shift (float, optional) – Maximum allowed shift during alignment (default is 30).

  • filter_sigma (int, optional) – Sigma value for Gaussian filter applied during alignment (default is 0).

  • do_intensity_rescale (bool or "full_image", optional) – Flag to indicate whether to rescale image intensities (default is True). Alternatively, set to “full_image” to rescale the entire image.

  • rescale_range (tuple or dict, optional) – If all channels should be rescaled to the same range pass a tuple with the percentiles for rescaling (default is (1, 99)). Alternatively, a dictionary can be passed with the channel names as keys and the percentiles as values if each channel should be rescaled to a different range.

  • channel_order (list, optional) – Order of channels in the generated output mosaic. If none (default value) the order of the channels is left unchanged.

  • reader_type (class, optional) – Type of reader to use for reading image tiles (default is FilePatternReaderRescale).

  • orientation (dict, optional) – Dictionary specifying which dimensions of the slide to flip (default is {‘flip_x’: False, ‘flip_y’: True}).

  • plot_QC (bool, optional) – Flag to indicate whether to plot quality control (QC) figures (default is True).

  • overwrite (bool, optional) – Flag to indicate whether to overwrite the output directory if it already exists (default is False).

  • cache (str, optional) – Directory to store temporary files during stitching (default is None). If set to none this directory will be created in the outdir.

get_stitching_information()#

Print information about the configuration of the stitching process.

save_positions()#

Save the positions of the aligned image tiles.

generate_thumbnail(scale: float | None = 0.05) → None#

Generate a thumbnail of the stitched mosaic.

Parameters:

scale – Scale factor for the thumbnail.

plot_qc()#

Plot quality control (QC) figures for the alignment.

stitch()#

Generate the stitched mosaic.

write_tif(export_xml: bool = True) → None#

Write the assembled mosaic as TIFF files.

Parameters:

export_xml – Whether to export an XML file for the TIFF files. This XML file is compatible with loading the generated TIFF files into BIAS.

Returns:

The assembled mosaic are written to file as TIFF files in the specified output directory.

write_ome_zarr(downscaling_size: int = 4, n_downscaling_layers: int = 4, chunk_size: tuple[int, int, int] = (1, 1024, 1024)) → None#

Write the assembled mosaic as an OME-Zarr file.

Parameters:

  • downscaling_size – Downscaling factor for generating lower resolution layers (default is 4).

  • n_downscaling_layers – Number of downscaling layers to generate (default is 4).

  • chunk_size – Chunk size for the generated OME-Zarr file (default is (1, 1024, 1024)).

write_thumbnail()#

Write the generated thumbnail as a TIFF file.

write_spatialdata(scale_factors: list[int] | None = None) → None#

Write the assembled mosaic as a SpatialData object.

Parameters:

scale_factors – List of scale factors for the generated SpatialData object. Defaults to [2, 4, 8]. The scale factors are used to generate downsampled versions of the image for faster visualization at lower resolutions.

class scportrait.tools.stitch._stitch.ParallelStitcher(input_dir: str, slidename: str, outdir: str, stitching_channel: str, pattern: str, overlap: float = 0.1, max_shift: float = 30, filter_sigma: int = 0, do_intensity_rescale: bool = True, rescale_range: tuple = (1, 99), plot_QC: bool = True, WGAchannel: str = None, channel_order: list[str] = None, overwrite: bool = False, reader_type='FilePatternReaderRescale', orientation=None, cache: str = None, threads: int = 20)#

Class for parallel stitching of image tiles and generating a mosaic. For applicable steps multi-threading is used for faster processing.

Parameters:

  • input_dir (str) – Directory containing the input image tiles.

  • slidename (str) – Name of the slide.

  • outdir (str) – Output directory to save the stitched mosaic.

  • stitching_channel (str) – Name of the channel to be used for stitching.

  • pattern (str) – File pattern to match the image tiles.

  • overlap (float, optional) – Overlap between adjacent image tiles (default is 0.1).

  • max_shift (float, optional) – Maximum allowed shift during alignment (default is 30).

  • filter_sigma (int, optional) – Sigma value for Gaussian filter applied during alignment (default is 0).

  • do_intensity_rescale (bool or "full_image", optional) – Flag to indicate whether to rescale image intensities (default is True). Alternatively, set to “full_image” to rescale the entire image.

  • rescale_range (tuple or dict, optional) – If all channels should be rescaled to the same range pass a tuple with the percentiles for rescaling (default is (1, 99)). Alternatively, a dictionary can be passed with the channel names as keys and the percentiles as values if each channel should be rescaled to a different range.

  • channel_order (list, optional) – Order of channels in the generated output mosaic. If none (default value) the order of the channels is left unchanged.

  • reader_type (class, optional) – Type of reader to use for reading image tiles (default is “FilePatternReaderRescale”).

  • orientation (dict, optional) – Dictionary specifying which dimensions of the slide to flip (default is {‘flip_x’: False, ‘flip_y’: True}).

  • plot_QC (bool, optional) – Flag to indicate whether to plot quality control (QC) figures (default is True).

  • overwrite (bool, optional) – Flag to indicate whether to overwrite the output directory if it already exists (default is False).

  • cache (str, optional) – Directory to store temporary files during stitching (default is None). If set to none this directory will be created in the outdir.

  • threads (int, optional) – Number of threads to use for parallel processing (default is 20).

write_tif_parallel(export_xml: bool = True)#

Parallelized version of the write_tif method to write the assembled mosaic as TIFF files.

Parameters:

export_xml – Whether to export an XML file for the TIFF files. This XML file is compatible with loading the generarted TIFF files into BIAS.