stitch

Contains 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 = None, reader_type=<class 'scportrait.tools.stitch._utils.filereaders.FilePatternReaderRescale'>, orientation: dict | None = None, plot_QC: bool = True, overwrite: bool = False, cache: str | None = None)

Class for stitching of image tiles to assemble a mosaic.

Parameters:

input_dirstr

Directory containing the input image tiles.

slidenamestr

Name of the slide.

outdirstr

Output directory to save the stitched mosaic.

stitching_channelstr

Name of the channel to be used for stitching.

patternstr

File pattern to match the image tiles.

overlapfloat, optional

Overlap between adjacent image tiles (default is 0.1).

max_shiftfloat, optional

Maximum allowed shift during alignment (default is 30).

filter_sigmaint, optional

Sigma value for Gaussian filter applied during alignment (default is 0).

do_intensity_rescalebool 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_rangetuple or dictionary, optional

If all channels should be rescaled to the same range pass a tuple with the percentiles for rescaleing (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_orderlist, optional

Order of channels in the generated output mosaic. If none (default value) the order of the channels is left unchanged.

reader_typeclass, optional

Type of reader to use for reading image tiles (default is FilePatternReaderRescale).

orientationdict, optional

Dictionary specifiying which dimensions of the slide to flip (default is {‘flip_x’: False, ‘flip_y’: True}).

plot_QCbool, optional

Flag to indicate whether to plot quality control (QC) figures (default is True).

overwritebool, optional

Flag to indicate whether to overwrite the output directory if it already exists (default is False).

cachestr, optional

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

create_cache()

Create a temporary cache directory for storing intermediate files during stitching.

clear_cache()

Clear the temporary cache directory.

initialize_outdir()

Initialize the output directory for saving the stitched mosaic.

get_channel_info()

Get information about the channels in the image tiles.

setup_rescaling()

Setup image rescaling based on the specified rescale_range.

reorder_channels()

Reorder the channels in the mosaic based on the specified channel_order.

initialize_reader()

Initialize the reader for reading image tiles.

save_positions()

Save the positions of the aligned image tiles.

generate_thumbnail(scale=0.05)

Generate a thumbnail of the stitched mosaic.

Parameters:

scalefloat, optional

Scale factor for the thumbnail (default is 0.05).

initialize_aligner()

Initialize the aligner for aligning the image tiles.

Returns:

alignerEdgeAligner

Initialized EdgeAligner object.

plot_qc()

Plot quality control (QC) figures for the alignment.

perform_alignment()

Perform alignment of the image tiles.

initialize_mosaic()

Initialize the mosaic object for assembling the image tiles.

Returns:

mosaicMosaic

Initialized Mosaic object.

assemble_mosaic()

Assemble the image tiles into a mosaic.

stitch()

Perform the stitching process.

write_tif(export_xml=True)

Write the assembled mosaic as TIFF files.

Parameters:

export_xmlbool, optional

Flag to indicate whether to export an XML file for the TIFF files (default is True). This XML file is compatible with loading the generarted TIFF files into BIAS.

write_ome_zarr(downscaling_size=4, n_downscaling_layers=4, chunk_size=(1, 1024, 1024))

Write the assembled mosaic as an OME-Zarr file.

Parameters:

downscaling_sizeint, optional

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

n_downscaling_layersint, optional

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

chunk_sizetuple, optional

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=None)

Write the assembled mosaic as a SpatialData object.

Parameters:

scale_factorslist, optional

List of scale factors for the generated SpatialData object (default is [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 = None, channel_order: list[str] | None = None, overwrite: bool = False, reader_type=<class 'scportrait.tools.stitch._utils.filereaders.FilePatternReaderRescale'>, orientation=None, cache: str | None = 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_dirstr

Directory containing the input image tiles.

slidenamestr

Name of the slide.

outdirstr

Output directory to save the stitched mosaic.

stitching_channelstr

Name of the channel to be used for stitching.

patternstr

File pattern to match the image tiles.

overlapfloat, optional

Overlap between adjacent image tiles (default is 0.1).

max_shiftfloat, optional

Maximum allowed shift during alignment (default is 30).

filter_sigmaint, optional

Sigma value for Gaussian filter applied during alignment (default is 0).

do_intensity_rescalebool 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_rangetuple or dictionary, optional

If all channels should be rescaled to the same range pass a tuple with the percentiles for rescaleing (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_orderlist, optional

Order of channels in the generated output mosaic. If none (default value) the order of the channels is left unchanged.

reader_typeclass, optional

Type of reader to use for reading image tiles (default is FilePatternReaderRescale).

orientationdict, optional

Dictionary specifiying which dimensions of the slide to flip (default is {‘flip_x’: False, ‘flip_y’: True}).

plot_QCbool, optional

Flag to indicate whether to plot quality control (QC) figures (default is True).

overwritebool, optional

Flag to indicate whether to overwrite the output directory if it already exists (default is False).

cachestr, optional

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

threadsint, optional

Number of threads to use for parallel processing (default is 20).

initialize_aligner()

Initialize the aligner for aligning the image tiles.

Returns:

alignerParallelEdgeAligner

Initialized ParallelEdgeAligner object.

initialize_mosaic()

Initialize the mosaic object for assembling the image tiles.

Returns:

mosaicMosaic

Initialized Mosaic object.

assemble_mosaic()

Assemble the image tiles into a mosaic.

write_tif_parallel(export_xml=True)

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

Parameters:

export_xml (bool, optional) – Flag to indicate whether to export an XML file for the TIFF files (default is True). This XML file is compatible with loading the generarted TIFF files into BIAS.