Segmentation

Module Documentation

This module handles tumor segmentation of HE-stained whole-slide images (WSIs) using configurable segmentation models in ONNX format. It processes WSIs by dividing them into tiles, applying the segmentation model to each tile, and reconstructing the full segmentation mask for the entire WSI.

Primary Functions

cubats.slide_collection.segmentation.run_tumor_segmentation(input_path: str, model_path: str, tile_size: Tuple[int, int], output_path: str | None = None, normalization: bool = False, inversion: bool = False, plot_results: bool = False)[source]

Run the segmentation pipeline on the given input path using the specified model.

Performs segmentation on a single HE stained WSI or all HE stained WSIs in a directory using the specified model. The segmentation results are saved as .TIFF in the output directory, as well as a . PNG thumbnail. If no output directory is provided, the results are saved in the same directory as the input. Optionally, a thumbnail of the segmentation results can be plotted on the original image and saved.

Parameters:

  • input_path (str) – The path to the input file or directory.

  • model_path (str) – The path to the ONNX model file.

  • tile_size (Tuple[int, int]) – The size of each tile for segmentation.

  • output_path (Union[str, None], optional) – The path to the output directory. If not provided, the output will be saved in the same directory as the input. Defaults to None.

  • normalization (bool, optional) – Whether to normalize the input tiles. Depends on the model provided. Defaults to False.

  • inversion (bool, optional) – Whether to invert the segmentation output. Depends on the model provided. Defaults to False.

  • plot_results (bool, optional) – Whether to plot the segmentation results. Defaults to False.

Raises:

  • FileNotFoundError – If the input path or output path does not exist.

  • ValueError – If the output path is not a directory or the model path is invalid.

Returns:

None

Internal Functions

cubats.slide_collection.segmentation._segment_file(file_path, model, tile_size, model_input_size, output_path, normalization, inversion, plot_results)[source]

Performs tumor detection and segmentation on a single WSI file.

Segments a (WSI) file into tiles, applies a tumor segmentation model onto each tile. The resulting tiles are reconstructed into a single image and saved as a .TIFF file. A thumbnail of the segmentation results is saved as a .PNG file. Optionally, the segmentation results can be plotted onto the original image and saved.

Parameters:

  • file_path (str) – The path to the WSI file.

  • model – The segmentation model.

  • tile_size (tuple) – The size of each tile in pixels.

  • model_input_size (tuple) – The input size of the model.

  • output_path (str) – The path to save the segmented image.

  • normalization (bool) – Whether to normalize the input tiles.

  • inversion (bool) – Whether to invert the segmentation output.

  • plot_results (bool) – Whether to plot the segmentation results on the original image.

Returns:

None

cubats.slide_collection.segmentation._segment_tile(tile: Tensor, model, resizing: bool, inversion: bool, original_size) → <module 'PIL.Image' from '/home/runner/work/CuBATS/CuBATS/.venv/lib/python3.11/site-packages/PIL/Image.py'>[source]

Segments a given tile using a pre-trained model and returns the segmented tile as a PIL Image.

Parameters:

  • tile (torch.Tensor) – The input tile to be segmented. Expected shape is (1, C, H, W).

  • model – The pre-trained segmentation model.

  • resizing (bool) – Whether input has been resized to the model’s input size. Consequentially resizing the output

  • necessary. (is)

  • inversion (bool) – Whether to invert the segmentation output, depending on model type.

  • original_size (tuple) – The original size of the tile before resizing.

Returns:

The segmented tile as a binary mask in PIL Image format.

Return type:

Image

cubats.slide_collection.segmentation._plot_segmentation_on_tissue(file_path, output_path)[source]

Plots the segmentation results on the original image and saves the result as a thumbnail.

Parameters:

  • file_path (str) – The path to the original WSI file.

  • output_path (str) – The path to save the thumbnail.

Returns:

None