Slide Module

slide.py: Contains the Slide and Annotations classes.

Slide class: Wrapper around openslide.OpenSlide with annotation overlay and mask generation. Annotations class: Parses annotation files from QuPath, ImageJ, and ASAP.

class pyslyde.slide.Slide(filename, mag=0, annotations=None, annotations_path=None, labels=None, source=None)[source]

Bases: OpenSlide

Whole Slide Image (WSI) object that enables annotation overlay as a wrapper around openslide.OpenSlide. Generates annotation mask.

mag

Magnification level.

Type:

int

dims

Dimensions of the WSI.

Type:

tuple

name

Name of the slide file.

Type:

str

draw_border

Whether to generate border based on annotations.

Type:

bool

_border

List of border coordinates [(x1, y1), (x2, y2)].

Type:

list

MAG_FACTORS: Dict[int, int] = {0: 1, 1: 2, 2: 4, 3: 8, 4: 16, 5: 32}
MASK_SIZE: Tuple[int, int] = (2000, 2000)
__init__(filename, mag=0, annotations=None, annotations_path=None, labels=None, source=None)[source]

Open a whole-slide image.

property slide_mask: ndarray

Get the slide mask as an RGB array.

generate_mask(size=None, labels=None)[source]

Generate a mask representation of annotations.

Parameters:

  • size (tuple, optional) – Dimensions of the mask.

  • labels (list, optional) – List of labels to include in the mask.

Returns:

Single-channel mask with integer for each class.

Return type:

np.ndarray

static resize_border(dim, factor=1, threshold=None, operator='=>')[source]

Resize and redraw annotation border. Useful to trim WSI and mask to a specific size.

Parameters:

  • dim (int) – Dimension to resize.

  • factor (int) – Border increments.

  • threshold (int, optional) – Minimum/maximum size.

  • operator (str) – Threshold limit operator.

Returns:

New border dimension.

Return type:

int

get_border(space=100)[source]

Generate border around max/min annotation points.

Parameters:

space (int) – Gap between max/min annotation point and border.

Returns:

Border dimensions [(x1, y1), (x2, y2)].

Return type:

list

detect_components(level_dims=6, num_component=None, min_size=None)[source]

Find the largest section on the slide.

Parameters:

  • level_dims (int) – Level of downsampling.

  • num_component (int, optional) – Number of components to keep.

  • min_size (int, optional) – Minimum size of component.

Returns:

(List of images with contours, list of border coordinates)

Return type:

tuple

generate_region(mag=0, x=None, y=None, x_size=None, y_size=None, scale_border=False, factor=1, threshold=None, operator='=>')[source]

Extract a specific region of the slide.

Parameters:

  • mag (int) – Magnification level.

  • x (int or tuple, optional) – Minimum x coordinate or (x_min, x_max).

  • y (int or tuple, optional) – Minimum y coordinate or (y_min, y_max).

  • x_size (int, optional) – Width of the region.

  • y_size (int, optional) – Height of the region.

  • scale_border (bool) – Whether to resize the border.

  • factor (int) – Factor for resizing.

  • threshold (int, optional) – Threshold for resizing.

  • operator (str) – Operator for threshold.

Returns:

(Extracted region as RGB ndarray, mask)

Return type:

tuple

save(path, size=(2000, 2000), mask=False)[source]

Save a thumbnail of the slide as an image file.

Parameters:

  • path (str) – Path to save the image.

  • size (tuple) – Size of the thumbnail.

  • mask (bool) – Whether to save the mask instead of the image.

class pyslyde.slide.Annotations(path, source, labels=None, encode=False)[source]

Bases: object

Parses annotation files in XML or JSON format and returns a dictionary containing x, y coordinates for each region of interest (ROI).

Parameters:

  • path (str or list) – Path(s) to annotation file(s).

  • source (str) – Annotation source type (e.g., ‘qupath’, ‘imagej’, ‘asap’).

  • labels (list, optional) – List of ROI names.

  • encode (bool) – Whether to encode labels as integers.

__init__(path, source, labels=None, encode=False)[source]
property keys: List[str | int]
property values: List[List[List[List[int]]]]
property annotations: Dict[str | int, List[List[List[int]]]] | None
property class_key: Dict[str, int]
property numbers: Dict[str, int]
filter_labels(labels)[source]

Remove labels from annotations.

Parameters:

labels (list) – Label list to keep.

Returns:

Filtered annotation dictionary.

Return type:

dict

rename_labels(names)[source]

Rename annotation labels.

Parameters:

names (dict) – Mapping from current labels to new labels.

encode_keys()[source]

Encode labels as integer values.

Returns:

Annotations with integer keys.

Return type:

dict

df()[source]

Return a DataFrame of annotations.

Returns:

DataFrame of annotations.

Return type:

pd.DataFrame

save(save_path)[source]

Save annotations as a CSV file.

Parameters:

save_path (str) – Path to save the annotations.

Slide Class

class pyslyde.slide.Slide(filename, mag=0, annotations=None, annotations_path=None, labels=None, source=None)[source]

Bases: OpenSlide

Whole Slide Image (WSI) object that enables annotation overlay as a wrapper around openslide.OpenSlide. Generates annotation mask.

mag

Magnification level.

Type:

int

dims

Dimensions of the WSI.

Type:

tuple

name

Name of the slide file.

Type:

str

draw_border

Whether to generate border based on annotations.

Type:

bool

_border

List of border coordinates [(x1, y1), (x2, y2)].

Type:

list

MAG_FACTORS: Dict[int, int] = {0: 1, 1: 2, 2: 4, 3: 8, 4: 16, 5: 32}
MASK_SIZE: Tuple[int, int] = (2000, 2000)
__init__(filename, mag=0, annotations=None, annotations_path=None, labels=None, source=None)[source]

Open a whole-slide image.

mag: int
dims: Tuple[int, int]
name: str
annotations: 'Annotations' | None
property slide_mask: ndarray

Get the slide mask as an RGB array.

generate_mask(size=None, labels=None)[source]

Generate a mask representation of annotations.

Parameters:

  • size (tuple, optional) – Dimensions of the mask.

  • labels (list, optional) – List of labels to include in the mask.

Returns:

Single-channel mask with integer for each class.

Return type:

np.ndarray

static resize_border(dim, factor=1, threshold=None, operator='=>')[source]

Resize and redraw annotation border. Useful to trim WSI and mask to a specific size.

Parameters:

  • dim (int) – Dimension to resize.

  • factor (int) – Border increments.

  • threshold (int, optional) – Minimum/maximum size.

  • operator (str) – Threshold limit operator.

Returns:

New border dimension.

Return type:

int

get_border(space=100)[source]

Generate border around max/min annotation points.

Parameters:

space (int) – Gap between max/min annotation point and border.

Returns:

Border dimensions [(x1, y1), (x2, y2)].

Return type:

list

detect_components(level_dims=6, num_component=None, min_size=None)[source]

Find the largest section on the slide.

Parameters:

  • level_dims (int) – Level of downsampling.

  • num_component (int, optional) – Number of components to keep.

  • min_size (int, optional) – Minimum size of component.

Returns:

(List of images with contours, list of border coordinates)

Return type:

tuple

generate_region(mag=0, x=None, y=None, x_size=None, y_size=None, scale_border=False, factor=1, threshold=None, operator='=>')[source]

Extract a specific region of the slide.

Parameters:

  • mag (int) – Magnification level.

  • x (int or tuple, optional) – Minimum x coordinate or (x_min, x_max).

  • y (int or tuple, optional) – Minimum y coordinate or (y_min, y_max).

  • x_size (int, optional) – Width of the region.

  • y_size (int, optional) – Height of the region.

  • scale_border (bool) – Whether to resize the border.

  • factor (int) – Factor for resizing.

  • threshold (int, optional) – Threshold for resizing.

  • operator (str) – Operator for threshold.

Returns:

(Extracted region as RGB ndarray, mask)

Return type:

tuple

save(path, size=(2000, 2000), mask=False)[source]

Save a thumbnail of the slide as an image file.

Parameters:

  • path (str) – Path to save the image.

  • size (tuple) – Size of the thumbnail.

  • mask (bool) – Whether to save the mask instead of the image.

Annotations Class

class pyslyde.slide.Annotations(path, source, labels=None, encode=False)[source]

Bases: object

Parses annotation files in XML or JSON format and returns a dictionary containing x, y coordinates for each region of interest (ROI).

Parameters:

  • path (str or list) – Path(s) to annotation file(s).

  • source (str) – Annotation source type (e.g., ‘qupath’, ‘imagej’, ‘asap’).

  • labels (list, optional) – List of ROI names.

  • encode (bool) – Whether to encode labels as integers.

__init__(path, source, labels=None, encode=False)[source]
property keys: List[str | int]
property values: List[List[List[List[int]]]]
property annotations: Dict[str | int, List[List[List[int]]]] | None
property class_key: Dict[str, int]
property numbers: Dict[str, int]
filter_labels(labels)[source]

Remove labels from annotations.

Parameters:

labels (list) – Label list to keep.

Returns:

Filtered annotation dictionary.

Return type:

dict

rename_labels(names)[source]

Rename annotation labels.

Parameters:

names (dict) – Mapping from current labels to new labels.

encode_keys()[source]

Encode labels as integer values.

Returns:

Annotations with integer keys.

Return type:

dict

df()[source]

Return a DataFrame of annotations.

Returns:

DataFrame of annotations.

Return type:

pd.DataFrame

save(save_path)[source]

Save annotations as a CSV file.

Parameters:

save_path (str) – Path to save the annotations.