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