InstanSeg¶

from instanseg import InstanSeg

class InstanSeg(model_type='brightfield_nuclei', device=None, image_reader='auto', verbosity=1, channels_last=True)¶

Main class for running InstanSeg.

Parameters:

model_type (Union[str, Module]) – The type of model to use. If a string is provided, the model will be downloaded. If the model is not public, it will look for a model in your bioimageio folder. If an nn.Module is provided, this model will be used.
device (Optional[str]) – The device to run the model on. If None, the device will be chosen automatically.
image_reader (str) – The image reader to use. Options are “auto”, “tiffslide”, “skimage.io”, “bioio”, “AICSImageIO”. If “auto”, will use the first available reader.
verbosity (int) – The verbosity level. 0 is silent, 1 is normal, 2 is verbose.
channels_last (bool) – On CUDA, run the model in channels_last (NHWC) memory format for faster convolution/batch-norm. Ignored on non-CUDA devices. Set to False for bit-for-bit reproducibility with the channels-first path.

read_image(image_str, processing_method='auto')¶

Read an image file from disk.

Parameters:

image_str (str) – The path to the image.
processing_method – The processing method to use. Options are “auto”, “small”, “medium”, “wsi”. If “auto”, the method will be chosen based on the size of the image.

Returns:

The image array if it can be safely read (or the path to the image if it cannot) and the pixel size in microns.

Return type:

Union[Tuple[str, float], Tuple[ndarray, float]]

read_pixel_size(image_str)¶

Read the pixel size from an image on disk.

Parameters:: image_str (str) – The path to the image.
Returns:: The pixel size in microns.
Return type:: float

read_slide(image_str)¶

Read a whole slide image from disk.

Parameters:: image_str (str) – The path to the image.

eval(image, pixel_size=None, save_output=False, save_overlay=False, save_geojson=False, processing_method='auto', **kwargs)¶

Evaluate the input image or list of images using the InstanSeg model.

Parameters:

image (Union[str, List[str]]) – The path to the image, or a list of such paths.
pixel_size (Optional[float]) – The pixel size in microns.
save_output (bool) – Controls whether the output is saved to disk (see save_output()).
save_overlay (bool) – Controls whether the output is saved to disk as an overlay (see save_output()).
save_geojson (bool) – Controls whether the geojson output labels are saved to disk (see save_output()).
processing_method (str) – The processing method to use. Options are “auto”, “small”, “medium”, “wsi”. If “auto”, the method will be chosen based on the size of the image.
kwargs – Passed to other eval methods, e.g. eval_small_image(), eval_medium_image() or eval_whole_slide_image().

Returns:

A torch.Tensor of outputs if the input is a path to a single image, or a list of such outputs if the input is a list of paths, or None if the input is a whole slide image.

Return type:

Union[Tensor, List[Tensor], None]

save_output(image_path, labels, image_array=None, save_output=True, save_overlay=False, save_geojson=False)¶

Save the output of InstanSeg to disk.

Parameters:

image_path (str) – The path to the image, and where outputs will be saved.
labels (Tensor) – The output labels.
image_array (Optional[ndarray]) – The image in array format. Required to save overlay.
save_output (bool) – Save the labels to disk.
save_overlay – Save the labels overlaid on the image.
save_geojson – Save the labels as a GeoJSON feature collection.

eval_small_image(image, pixel_size=None, normalise=True, return_image_tensor=True, target='all_outputs', rescale_output=True, **kwargs)¶

Evaluate a small input image using the InstanSeg model.

Parameters:

image (Tensor) – The input image(s) to be evaluated.
pixel_size (Optional[float]) – The pixel size of the image, in microns. If not provided, it will be read from the image metadata.
normalise (bool) – Controls whether the image is normalised.
return_image_tensor (bool) – Controls whether the input image is returned as part of the output.
target (str) – Controls what type of output is given, usually “all_outputs”, “nuclei”, or “cells”.
rescale_output (bool) – Controls whether the outputs should be rescaled to the same coordinate space as the input (useful if the pixel size is different to that of the InstanSeg model being used).
kwargs – Passed to pytorch.

Returns:

A tensor corresponding to the output targets specified, as well as the input image if requested. Tensors are returned on the device they were computed on (self.inference_device for small images); call .cpu() if host memory is needed.

Return type:

Union[Tensor, Tuple[Tensor, Tensor]]

eval_medium_image(image, pixel_size=None, normalise=True, tile_size=512, batch_size=1, return_image_tensor=True, normalisation_subsampling_factor=1, target='all_outputs', rescale_output=True, **kwargs)¶

Evaluate a medium input image using the InstanSeg model. The image will be split into tiles, and then inference and object merging will be handled internally.

Parameters:

image (Tensor) – The input image(s) to be evaluated.
pixel_size (Optional[float]) – The pixel size of the image, in microns. If not provided, it will be read from the image metadata.
normalise (bool) – Controls whether the image is normalised.
tile_size (int) – The width/height of the tiles that the image will be split into.
batch_size (int) – The number of tiles to be run simultaneously.
return_image_tensor (bool) – Controls whether the input image is returned as part of the output.
normalisation_subsampling_factor (int) – The subsampling or downsample factor at which to calculate normalisation parameters.
target (str) – Controls what type of output is given, usually “all_outputs”, “nuclei”, or “cells”.
rescale_output (bool) – Controls whether the outputs should be rescaled to the same coordinate space as the input (useful if the pixel size is different to that of the InstanSeg model being used).
kwargs – Passed to pytorch.

Returns:

Return type:

Union[Tensor, Tuple[Tensor, Tensor]]

eval_whole_slide_image(image, pixel_size=None, normalise=True, normalisation_subsampling_factor=1, tile_size=512, overlap=80, detection_size=20, save_geojson=False, use_otsu_threshold=False, **kwargs)¶

Evaluate a whole slide input image using the InstanSeg model. This function uses slideio to read an image and then segments it using the instanseg model. The segmentation is done in a tiled manner to avoid memory issues.

Parameters:

image (str) – The input image to be evaluated.
pixel_size (Optional[float]) – The pixel size of the image, in microns. If not provided, it will be read from the image metadata.
normalise (bool) – Controls whether the image is normalised.
tile_size (int) – The width/height of the tiles that the image will be split into.
overlap (int) – The overlap (in pixels) between tiles.
detection_size (int) – The expected maximum size of detection objects.
batch_size – The number of tiles to be run simultaneously.
normalisation_subsampling_factor (int) – The subsampling or downsample factor at which to calculate normalisation parameters.
use_otsu_threshold (bool) – bool = False. Whether to use an otsu threshold on the image thumbnail to find the tissue region.
kwargs – Passed to pytorch.

Returns:

Returns a zarr file with the segmentation. The zarr file is saved in the same directory as the image with the same name but with the extension .zarr.

display(image, instances, normalise=True)¶

Return the output of an InstanSeg model overlaid on the input. See save_image_with_label_overlay() for more details and return types.

Parameters:

image (torch.tensor) – The input image.
instances (Tensor) – The output labels.

Return type:

ndarray