NucleusInstanceSegmentor

class NucleusInstanceSegmentor(model, batch_size=8, num_workers=0, weights=None, *, device='cpu', verbose=True)[source]

NucleusInstanceSegmentor is segmentation engine to run models like hovernet.

Deprecated since version 2.1.0: NucleusInstanceSegmentor will be removed in a future release. Use MultiTaskSegmentor instead.

NucleusInstanceSegmentor inherits MultiTaskSegmentor as it is a special case of MultiTaskSegmentor with a single task.

Parameters:

  • model (str | ModelABC) – A PyTorch model instance or name of a pretrained model from TIAToolbox. The user can request pretrained models from the toolbox model zoo using the list of pretrained models available at this link By default, the corresponding pretrained weights will also be downloaded. However, you can override with your own set of weights using the weights parameter. Default is None.

  • batch_size (int) – Number of image patches processed per forward pass. Default is 8.

  • num_workers (int) – Number of workers for data loading. Default is 0.

  • weights (str | Path | None) –

    Path to model weights. If None, default weights are used.

    >>> engine = NucleusInstanceSegmentor(
...    model="pretrained-model",
...    weights="/path/to/pretrained-local-weights.pth"
... )

  • device (str) – Device to run the model on (e.g., “cpu”, “cuda”). Default is “cpu”.

  • verbose (bool) – Whether to enable verbose logging. Default is True.

images

Input image patches or WSI paths.

Type:

list[str | Path] | np.ndarray

masks

Optional tissue masks for WSI processing. These are only utilized when patch_mode is False. If not provided, then a tissue mask will be automatically generated for whole slide images.

Type:

list[str | Path] | np.ndarray

patch_mode

Whether input is treated as patches (True) or WSIs (False).

Type:

bool

model

Loaded PyTorch model.

Type:

ModelABC

ioconfig

IO configuration for patch extraction and resolution.

Type:

ModelIOConfigABC

return_labels

Whether to include labels in the output.

Type:

bool

return_predictions_dict

This dictionary helps keep track of which tasks require predictions in the output.

Type:

dict

input_resolutions

Resolution settings for model input. Supported units are level, power and mpp. Keys should be “units” and “resolution” e.g., [{“units”: “mpp”, “resolution”: 0.25}]. Please see WSIReader for details.

Type:

list[dict]

patch_input_shape

Shape of input patches (height, width). Patches are at requested read resolution, not with respect to level 0, and must be positive.

Type:

tuple[int, int]

stride_shape

Stride used during patch extraction. Stride is at requested read resolution, not with respect to level 0, and must be positive. If not provided, stride_shape=patch_input_shape.

Type:

tuple[int, int]

labels

Optional labels for input images. Only a single label per image is supported.

Type:

list | None

drop_keys

Keys to exclude from model output.

Type:

list

output_type

Format of output (“dict”, “zarr”, “annotationstore”).

Type:

str

output_locations

Coordinates of output patches used during WSI processing.

Type:

list | None

Examples: >>> # list of 2 image patches as input >>> wsis = [‘path/img.svs’, ‘path/img.svs’] >>> mtsegmentor = MultiTaskSegmentor(model=”hovernetplus-oed”) >>> output = mtsegmentor.run(wsis, patch_mode=False)

>>> # array of list of 2 image patches as input
>>> image_patches = [np.ndarray, np.ndarray]
>>> mtsegmentor = MultiTaskSegmentor(model="hovernetplus-oed")
>>> output = mtsegmentor.run(image_patches, patch_mode=True)

>>> # list of 2 image patch files as input
>>> data = ['path/img.png', 'path/img.png']
>>> mtsegmentor = MultiTaskSegmentor(model="hovernet_fast-pannuke")
>>> output = mtsegmentor.run(data, patch_mode=False)

>>> # list of 2 image tile files as input
>>> tile_file = ['path/tile1.png', 'path/tile2.png']
>>> mtsegmentor = MultiTaskSegmentor(model="hovernet_fast-pannuke")
>>> output = mtsegmentor.run(tile_file, patch_mode=False)

>>> # list of 2 wsi files as input
>>> wsis = ['path/wsi1.svs', 'path/wsi2.svs']
>>> mtsegmentor = MultiTaskSegmentor(model="hovernet_fast-pannuke")
>>> output = mtsegmentor.run(wsis, patch_mode=False)

Initialize NucleusInstanceSegmentor.

Parameters:

  • model (str | ModelABC) – A PyTorch model instance or name of a pretrained model from TIAToolbox. If a string is provided, the corresponding pretrained weights will be downloaded unless overridden via weights.

  • batch_size (int) – Number of image patches processed per forward pass. Default is 8.

  • num_workers (int) – Number of workers for data loading. Default is 0.

  • weights (str | Path | None) – Path to model weights. If None, default weights are used.

  • device (str) – Device to run the model on (e.g., “cpu”, “cuda”). Default is “cpu”.

  • verbose (bool) – Whether to enable verbose logging. Default is True.

Methods