OpenHI Image Processing APIs

This page contains the documentation of image processing-related functions in OpenHI.

Whole-slide image (WSI)

class openhi.img.slide.Slide(slide_index: int)

A class representing a whole-slide image (WSI).

slide_id: int

Slide ID according to /framework_src/manifest.txt.

file_path: str

Full path to the slide file.

available_pslvs: int[]

The pre-segmentation levels (PSLV) allowed for this slide.

bio_data: str

Corresponding biospecimen data of the slide.

clin_data: str

Corresponding clinical data of the slide.

internal_crop_result(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, flags: int, pslv: int, grid_density: int, img)

Internal usage only.

read_region(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, flags: int, pslv: int, grid_density: int = 50, internal_check: bool = True) → numpy.ndarray

Read the original image, pslv boundary, grid or their combination.

Parameters
  • tl_coor – Coordination of top-left corner of the reading region.

  • viewing_size – Size of the reading region.

  • viewer_size – Required image size.

  • flags – One or the combination of the followings: SLIDE_READ_IMAGE, SLIDE_READ_BOUND, SLIDE_READ_GRID

  • pslv – Index of desired pslv.

  • grid_density – Interval between grid lines (pixels).

  • internal_check – Check the validity of parameters tl_coor, viewing_size and viewer_size. e.g. viewing_size exceeds image size, viewing_size is lower than 0, etc.

Returns

Result image in the same resolution with viewer_size.

internal_read_region(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, flags: int, pslv: int, grid_density: int)

Internal usage only.

read_image(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple)

Internal usage only. Please use read_region with flags = SLIDE_READ_IMAGE instead.

read_boundary(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, pslv: int)

Internal usage only. Please use read_region with flags = SLIDE_READ_BOUND instead.

read_grid(viewing_size: tuple, viewer_size: tuple, grid_density: int)

Internal usage only. Please use read_region with flags = SLIDE_READ_GRID instead.

get_anno_mmsi_path(antr_id: int, pslv: int) → str

Get the mmsi file path to store the annotation.

Parameters
  • antr_id – Annotator id.

  • pslv – Index of desired pslv.

Returns

Path of the mmsi file.

get_anno(antr_id: int) → openhi.img.slide.SlideAnno

Get the annotation object of specified annotator, which is used to read and write annotations.

Parameters

antr_id – Annotator id.

Returns

Annotation object.

get_size() → tuple

Get the original slide size in pixels.

Returns

Slide resolution.

get_pixel_size() → tuple

Get the pixel size in microns.

Returns

Pixel size (x, y).

get_property(key: str) → str

Get the property value from OpenSlide.

Parameters

key – Property key.

Returns

Property value.

class openhi.img.slide.SlideAnno(slide: openhi.img.slide.Slide, antr_id: int)

A class representing the annotation from one annotator of one slide. Please remember to delete the object after using to ensure annotation data is saved.

antr_id: int

Internal annotator id.

read_region(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, flags: int, pslv: int, grid_density: int = 50, internal_check: bool = True) → numpy.ndarray

Read the original image, pslv boundary, annotation result, grid or their combination.

Parameters
  • tl_coor – Coordination of top-left corner of the reading region.

  • viewing_size – Size of the reading region.

  • viewer_size – Required image size.

  • flags – One or the combination of the followings: SLIDE_READ_IMAGE, SLIDE_READ_BOUND, SLIDE_READ_GRID, SLIDE_READ_ANNO

  • pslv – Index of desired pslv.

  • grid_density – Interval between grid lines (pixels).

  • internal_check – Check the validity of parameters tl_coor, viewing_size and viewer_size. e.g. viewing_size exceeds image size, viewing_size is lower than 0, etc.

Returns

Result image in the same resolution with viewer_size.

internal_read_region(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, flags: int, pslv: int, grid_density: int)

Internal usage only.

write_anno(points: [], pslv: int, grade: int, need_undo: bool = True)

Write annotation to the slide.

Parameters
  • points – An array of (x, y) coordinations of the annotation. e.g. [(100, 100), (200, 300)].

  • pslv – Index of desired pslv.

  • grade – Grade of the annotation.

  • need_undo – Does this action need to undo.

undo_anno(pslv: int, count: int = 1)

Undo the last modification(s) for specified pslv.

Parameters
  • pslv – Index of desired pslv.

  • count – Number of action(s) to undo.

read_anno(tl_coor: tuple, viewing_size: tuple, viewer_size: tuple, pslv: int)

Internal usage only. Please use read_region with flags = SLIDE_READ_ANNO instead.

Image processing

OpenHI image processing module.

openhi.img.imgproc.image_split(image, mode, path=None, write=False)

Split input image into m * n pixels pieces.

Parameters
  • image (string) – The path of input image

  • mode (tuple) – size of sub-rectangle region, tuple: (m, n)

  • path (string) – Output path

  • write (bool) – Save sub-images into a file or not

Returns

a list of sub-images, base coordinates of sub-images (left-top coordinates)

Return type

list

openhi.img.imgproc.read_annotation(fp)

Read the annotated data into a list.

Parameters

fp (string) – File path

Returns

A list containing tuples: (image NO., coordinate x, coordinate y, grade)

Return type

list

openhi.img.imgproc.fetch_coordinate(image_num, annotation)

Fetch coordinates of nuclei in specified image, given annotation of all images.

Parameters
  • image_num (int) – index of specified image

  • annotation (list) – annotation information of all images

Returns

coordinates of nuclei in specified image

Return type

list

openhi.img.imgproc.convert_coordinate(benchmark, boxsize, coordinate)

Convert coordinates of nuclei based on the benchmark and boxsize of sub-image.

Parameters
  • benchmark (tuple) – left top coordinate of sub-image

  • boxsize (tuple) – size of sub-image

  • coordinate (list) – coordinates of all nuclei in original image

Returns

converted coordiantes

Return type

list

openhi.img.imgproc.gen_path_sliding_window(patch_size, path_patches)

Generate the patch in a sliding window fashion.

This function can also be used to generate the tile (no overlapping regions) by setting the step size to zero.

Param

int patch_size: the size of patch.

Param

String path_patches: txt file’s path which saves the path of patches and label.

Returns

Return type

str

openhi.img.imgproc.gen_path_annotation_based(orin_img_lst: [], anno_img_lst: [], output_dir: str, patch_size: int = 64, overlap_size: int = 32, overlap_size_zero: int = 40, core_size: int = 16, core_ratio: float = 0.5, core_conflict_ratio: float = 0.1, conflict_ratio: float = 0.2, conflict_ratio_zero: float = 0.1, stride: int = 1, dataset_size: int = 1000, debug: bool = False, print_log: bool = True)

Generate the patch based on annotation region.

Parameters
  • orin_img_lst – Original whole-slide image list.

  • anno_img_lst – Generated annotation image list.

  • output_dir – Directory to put generated patches.

  • patch_size – Size of each patch.

  • overlap_size – Any two of the generated patches will at least at a distance of overlap_size.

  • overlap_size_zero – overlap_size for grade 0.

  • core_size – Used to determine the grade of each patch.

  • core_ratio – If more than core_ratio of the pixels in the core are of the same grade, a patch is generated.

  • core_conflict_ratio – Each patch core must have more than core_conflict_ratio of all pixels with the same grade.

  • conflict_ratio – Each patch must have more than conflict_ratio of all pixels with the same grade.

  • conflict_ratio_zero – conflict_ratio for grade 0.

  • stride – Stride for sliding window.

  • dataset_size – Number of patch files to generate.

  • debug – Draw patch locations on anno_img.

  • print_log – Print log to standard output.

Returns

The number of generated patches of each grade.

Return type

int

Nucleus histomorphometry analysis