Predictors¶

The Predictors are Python functions that take as input a image (a filename for V1 or a preprocessed image for V2) and a model and returns a post-processed image.

The post-processing is optional for V2. Use return_logit option to return the raw model output.

Model predictors.

Contains 2 versions of predictors and the postprocessing function.

class biom3d.predictors.LoadImgPatch(fname: str, patch_size: tuple[int] = (64, 64, 32), median_spacing: list[float] = [], clipping_bounds: list[float] = [], intensity_moments: list[float] = [])[source]¶

Class to load and preprocess an image for TorchIO-like patch-based segmentation prediction.

Segmentation Predictor V1

Designed to handle image loading, resampling, clipping, normalization, and patch sampling preparation.

Variables:

fname (str) – Filename of the image.
img (numpy.ndarray) – Preprocessed image tensor.
img_shape (tuple[int]) – Original shape of the image.
patch_size (numpy.ndarray) – Patch size for sampling.
median_spacing (numpy.ndarray) – Median spacing of the dataset for resampling.
clipping_bounds (list[float]) – Clipping bounds for intensity.
intensity_moments (list[float]) – Intensity moments for normalization.
spacing (list[float]|tuple[float]) – Original image spacing.

__init__(fname: str, patch_size: tuple[int] = (64, 64, 32), median_spacing: list[float] = [], clipping_bounds: list[float] = [], intensity_moments: list[float] = [])[source]¶

Initialize the LoadImgPatch class.

Parameters:

fname (str) – Path to the image file.
patch_size (tuple of int, default=(64,64,32)) – Size of the patches.
median_spacing (list of float, default=[]) – Median spacing of the dataset to resample the image.
clipping_bounds (list, default=[]) – Bounds for clipping the intensity values. If provided must be [min,max]
intensity_moments (list of float, default=[]) – Mean and variance of the intensity of the images voxels in the masks regions as [mean,std]. These values are used to normalize the image.

get_gridsampler() → GridSampler[source]¶

Prepare image for model prediction and return a TorchIO GridSampler.

Returns:: TorchIO GridSampler object for patch sampling.
Return type:: tio.data.GridSampler

post_process(logit: Tensor) → Tensor[source]¶

Resample the model output back to the original image space after prediction.

Parameters:: logit (torch.Tensor) – Model output tensor to be resampled.
Returns:: Resampled model output tensor.
Return type:: torch.Tensor

biom3d.predictors.load_img_seg(fname: str) → Tensor[source]¶

Load and preprocess a single image for segmentation prediction.

Segmentation Predictor V1

The image is normalized to [0,1], converted to a float PyTorch tensor, and reshaped to a 4D tensor with dimensions (batch=1, channel=1, height, width).

Parameters:: fname (str) – Path to the image file to load.
Returns:: Preprocessed image as a float PyTorch tensor, with shape (1, 1, H, W), ready as input for a model.
Return type:: torch.Tensor

biom3d.predictors.seg_postprocessing(logit: ndarray | Tensor, original_shape: tuple[int], use_softmax: bool = True, force_softmax: bool = False, keep_big_only: bool = False, keep_biggest_only: bool = False, return_logit: bool = False, is_2d: bool = False, **kwargs)[source]¶

Post-process the logit (model output) to obtain the final segmentation mask. Can optionally remove some noise.

Recommended to be used after biom3d.predictors.seg_predict_patch_2.

Parameters:

logit (torch.Tensor or numpy.ndarray) – The raw model output.
original_shape (tuple of int) – Shape to resize the output to.
use_softmax (bool, default=True) – Whether softmax was used for training.
force_softmax (bool, default=False) – Whether sigmoid was used for training and intended to convert to softmax-like output.
keep_big_only (bool, default=False) – Whether to keep the big objects only in the output. An Otsu threshold is used on the object volume distribution.
keep_biggest_only (bool, default=False) – When true keeps the biggest centered object only in the output.
return_logit (bool, optional) – Whether to return the logit. Resampling will be applied before.
is_2d (bool, default=False) – Whether the image is in 2D, only affect resizing.
**kwargs (dict from str to any) – Just here for compatibility.

Raises:

AssertionError – If logit is not a numpy.ndarray or torch.Tensor.

Returns:

The post-processed segmentation mask or logit.

Return type:

numpy.ndarray

biom3d.predictors.seg_predict(img_path: str, model: Module, return_logit: bool = False) → ndarray[source]¶

Run a prediction on given image.

Segmentation Predictor V1

Load an image from a given path, run model prediction, and return either the binarized segmentation mask or raw logits.

Parameters:

img_path (str) – Path to the image file to predict.
model (torch.nn.Module) – The PyTorch segmentation model.
return_logit (bool, default=False) – If True, returns the raw model logits without post-processing.

Returns:

Segmentation mask (binary values 0 or 255) or raw logits.

Return type:

numpy.ndarray

biom3d.predictors.seg_predict_old(img: Tensor, model: Module, return_logit: bool = False) → ndarray[source]¶

For one image path, load the image, compute the model prediction, return the prediction.

Segmentation Predictor V0

Parameters:

img (torch.Tensor) – Image as a tensor.
model (torch.nn.Module) – The segmentation model.
return_logit (bool, optional) – If True, return the raw logit instead of the post-processed output.

Returns:

The predicted segmentation mask or logit.

Return type:

numpy.ndarray

biom3d.predictors.seg_predict_patch(img_path: str, model: Module, return_logit: bool = False, patch_size: tuple[int] = None, tta: bool = False, median_spacing: list[float] = [], clipping_bounds: list[float] = [], intensity_moments: list[float] = [], use_softmax: bool = False, force_softmax: bool = False, num_workers: int = 4, enable_autocast: bool = True, keep_biggest_only: bool = False) → ndarray[source]¶

For one image path, load the image, compute the model prediction, return the prediction.

Segmentation Predictor V1-TorchIO

Parameters:

img_path (str) – Path to the image file.
model (torch.nn.Module) – The segmentation model.
return_logit (bool, default=False) – If True, return the raw logit instead of the post-processed output.
patch_size (tuple of int, default=None) – Size of the patches for processing.
tta (bool, default=False) – If True, apply test time augmentation.
median_spacing (list of float, default=[]) – Median spacing of the dataset to resample the image.
clipping_bounds (list, default=[]) – Bounds for clipping the intensity values. If provided must be [min,max]
intensity_moments (list of float, default=[]) – Mean and variance of the intensity of the images voxels in the masks regions as [mean,std]. These values are used to normalize the image.
use_softmax (bool, default=False) – Flag for softmax processing.
force_softmax (bool, default=False) – Flag to output a softmax-like output even if the model output is sigmoid-like.
num_workers (int, default=4) – Number of workers for data loading.
enable_autocast (bool, default=True) – Enable mixed precision.
keep_biggest_only (bool, default=False) – If True, keep only the biggest volume in the output.

Returns:

The predicted segmentation mask or logit.

Return type:

numpy.ndarray

biom3d.predictors.seg_predict_patch_2(img: ndarray, original_shape: tuple[int], model: Module, patch_size: tuple[int], conserve_size: bool = False, tta: bool = False, num_workers: int = 4, enable_autocast: bool = True, use_softmax: bool = True, keep_biggest_only: bool = False, **kwargs) → ndarray[source]¶

For one image, compute the model prediction, return the predicted logit.

Segmentation Predictor V2

Image are supposed to be preprocessed already, which is doable using biom3d.preprocess.seg_preprocessor.

Parameters:

img (numpy.ndarray) – The preprocessed image to predict.
original_shape (tuple of int) – Original shape of the image.
model (torch.nn.Module) – The segmentation model.
patch_size (tuple of int) – Size of the patch used during training.
conserve_size (bool, default=False) – Force the logit to be the same size as the input. May be used if intended to not use post-processing.
tta (bool, default=False) – Test time augmentation.
num_workers (int, default=4) – Number of workers.
enable_autocast (bool, default=True) – Whether to use half-precision.
use_softmax (bool, default=True) – [DEPRECATED!] Whether softmax activation has been used for training.
keep_biggest_only (bool, default=True) – [DEPRECATED!] When true keeps the biggest object only in the output image.
**kwargs (dict from str to any) – Just here for compatibility.

Returns:

The predicted segmentation mask or logit.

Return type:

numpy.ndarray