Moth API

At the moment moth contains the QuPathTilingProject class to extract, import and merge tiles from a QuPath project.

Additionally, moth contains the MaskParameter class to specify the parameters for mask interactions.

MaskParameter

class moth.projects.MaskParameter(img_id: int, location: tuple[int, int], downsample_level: int = 0, multichannel: bool = False, downsample_level_power_of: int | None = None)

Parameter for mask generation and saving

Parameters:

• img_id (int) – Id of image from which the tile annotation mask will be extracted

• location (tuple[int, int]) – (x, y) coordinates for the top left pixel in the tile pixel location without downsampling

• downsample_level (int, optional) – Level for downsampling, by default 0

• multichannel (bool, optional) – True: create binary images [num_channels, height, width] False: create labeled image [height, width], by default False

• downsample_level_power_of (Optional[int], optional) – Compute custom downsample factor with this value to the power of the downsample_level, by default None

QuPathTilingProject

class moth.projects.QuPathTilingProject(path, mode='r')

Load or create a new QuPath project

Parameters:

• path (Union[str, Path]) – Path to project.qpproj file, or its parent directory

• mode (Literal['r', 'r+', 'w', 'w+', 'a', 'a+', 'x', 'x+']) –

  ‘r’ –> readonly, error if not there

  ’r+’ –> read/write, error if not there

  ’a’ = ‘a+’ –> read/write, create if not there, append if there

  ’w’ = ‘w+’ –> read/write, create if not there, truncate if there

  ’x’ = ‘x+’ –> read/write, create if not there, error if there

property path_classes: Tuple[QuPathPathClass, ...]

return path_classes stored in the project

get_tile(img_id, location, size, downsample_level=0, *, ret_array=False)

Get tile starting at (x,y) (slide level 0) with given size

Parameters:

• img_id (int) – Id of image from which a tile will be generated

• location (tuple[int, int]) –

  (x, y) coordinates for the top left pixel in the tile

  pixel location without downsampling

• size (tuple[int, int]) – (width, height) for the tile

• downsample_level (int, optional) – Level for downsampling, by default 0

• ret_array (bool, optional) – True: return tile as array False: return as PIL Image, by default False

Returns:

Requested tile as PIL Image

Return type:

Union[Image, NDArray[np.int_]]

get_tile_annotation(img_id, location, size, class_filter=None)

Get tile annotations between (x,y) and (x + width, y + height)

Parameters:

• img_id (int) – Id of image from which the tile annotations will be extracted

• location (tuple[int, int]) –

  (x, y) coordinates for the top left pixel in the tile

  pixel location without downsampling

• size (tuple[int, int]) – (width, height) for the tile

• class_filter (Optional[list[Union[int, str]]], optional) – List of annotation class names or id’s to filter by

Returns:

List of annotations (polygon, annotation_class) in tile

Return type:

list[tuple[Polygon, str]]

get_tile_annotation_mask(mask_params, size, *, class_filter=None)

Get tile annotations mask between (x,y) and (x + width, y + height)

Parameters:

• mask_params (MaskParameter) – Parameter for mask generation

• size (tuple[int, int]) – (width, height) for the tile

• class_filter (Optional[list[Union[int, str]]], optional) – list of annotation class names or id’s to filter by, by default None

Returns:

mask [height, width] with an annotation class for each pixel

or binary_mask[num_class, height, width] for multichannel

background class is ignored for multichannel

Return type:

NDArray[np.int32]

save_mask_annotations(annotation_mask, mask_params)

Saves a mask as annotations to QuPath

Parameters:

• annotation_mask (Union[NDArray[np.uint], NDArray[np.int_]]) – Mask [height, width] with an annotation class for each pixel or [num_class, height, width] for multichannel. Background class is ignored for multichannel

• mask_params (MaskParameter) – Parameter for mask import

Return type:

None

merge_near_annotations(img_id, max_dist)

Merge nearby annotations with equivalent annotation class

Parameters:

• img_id (int) – Id of the image where annotations will be merged

• max_dist (Union[float, int]) – Maximum distance up to which the annotations are merged

Return type:

None

get_downsample_factor(downsample_level, *, img_id=None, base=None)

Get downsample factor for a downsample_level. Either for a given image or computed for a given base value to the power of the downsample_level

Parameters:

• downsample_level (int) – Level for downsampling

• img_id (Optional[int], optional) – Id of the image, by default None

• base (Optional[int], optional) – Compute custom downsample factor with the given base to the power of the downsample_level, by default None

Returns:

Downsample factor

Return type:

float

Raises:

• ValueError – Either img_id or power_of is required to get downsample factor

• ValueError – Requested downsample level is not available for the image