Functions usage
+Parse Image
+To parse tiffiles into numpy arrays you can use the ImageParser.parse_image() function:
-
+
- +ImageParser.parse_image(img_path: str) array +
Load an image from the specified path, process it, and return it as a NumPy array.
+The function reads a TIFF image, squeezes the array to remove single-dimensional entries, +and moves the axis to ensure the array has dimensions (X, Y, channels).
++ +Parameters
+-
+
- img_pathstr
Path to the image file (not the mask).
+
+
+ +Returns
+-
+
- np.ndarray or None
A NumPy array representing the image with shape (X, Y, channels). +Returns None if there is an error reading the image.
+
+
+ +Notes
+This function is designed to handle OME-TIFF images specifically. If the image cannot be read, +the function will print an error message and return None.
++ +Examples
+++>>> img_array = parse_image('path/to/image.ome.tiff') +>>> if img_array is not None: +>>> print("Image shape:", img_array.shape) +
If your tiffiles are not stacks but page based tiffs:
+-
+
- +ImageParser.parse_image_pages(img_path: str) array +
Load a TIFF file with multiple pages and return it as a NumPy array.
+This function reads a multi-page TIFF file, extracts each page as an image, +and combines them into a single NumPy array with dimensions (X, Y, channels).
++ +Parameters
+-
+
- img_pathstr
Path to the TIFF image file.
+
+
+ +Returns
+-
+
- np.ndarray
A NumPy array representing the image with shape (X, Y, channels).
+
+
+ +Examples
+++>>> img_array = parse_image_pages('path/to/image.tiff') +>>> print("Image shape:", img_array.shape) +
Lastly, if you want to extract the channel names from the pages of TIFF use ImageParser.parse_image_pages_namesCH() function.
-
+
- +ImageParser.parse_image_pages_namesCH(img_path) +
Load a TIFF file with multiple pages and retrieve the names of the pages.
+This function reads a multi-page TIFF file, extracts each page as an image, +and retrieves the names of the channels from the page tags. The images are +combined into a single NumPy array with dimensions (X, Y, channels).
++ +Parameters
+-
+
- img_pathstr
Path to the TIFF image file.
+
+
+ +Returns
+-
+
- tuple[np.ndarray, list[str]]
A tuple containing: +- A NumPy array representing the image with shape (X, Y, channels). +- A list of strings representing the names of the channels.
+
+
+ +Notes
+The function looks for ‘PageName’ or ‘ImageDescription’ tags in each page +to determine the channel names. If neither tag is found, the channel name +is not added to the list.
++ +Examples
+++>>> img_array, channel_names = parse_image_pages_namesCH('path/to/image.tiff') +>>> if img_array is not None: +>>> print("Image shape:", img_array.shape) +>>> print("Channel names:", channel_names) +
Preprocessing Image
+In this pipeline there are two main preprocessing functions: saturation of outliers and the normalization.
+To saturate outliers you can use: +.. autofunction:: ImagePreprocessFilters.remove_outliers
+To normalize, PENGUIN uses:
+-
+
- +ImagePreprocessFilters.normalize_channel_cv2_minmax(img: array) array +
Normalize each channel of the image using the OpenCV min-max normalization function.
+This function processes each channel of the input image independently, +normalizing pixel values to the range [0, 1] using OpenCV’s cv2.normalize method.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array with shape (H, W, C), where H is the height, +W is the width, and C is the number of channels.
+
+
+ +Returns
+-
+
- np.ndarray
The image with each channel min-max normalized to the range [0, 1].
+
+
+ +Examples
+++>>> img = np.random.rand(100, 100, 3) * 255 +>>> normalized_img = normalize_channel_cv2_minmax(img) +>>> print(normalized_img.shape) +>>> print(normalized_img.min(), normalized_img.max()) +
+ +Notes
+This normalization ensures that the minimum value of each channel is 0 and +the maximum value is 1.
+
Thresholding
+Thresholding allows to discard background signals, essentially removing signals of low intensity (already normalized).
+To do this, the most straightforward approach is thresholding based on the pixel value, where pixel values below this threshold are set to 0.
+-
+
- +ImagePreprocessFilters.out_ratio2(img: ndarray, th: float = 0.1) ndarray +
Apply thresholding to an image.
+This function sets all pixels below the specified threshold to 0. +The input image should be a single-channel image if thresholding is to be applied per channel.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+- thfloat, optional
The threshold value. All pixel values below this threshold will be set to 0. +Default is 0.1.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image, with all pixels below the threshold set to 0.
+
+
+ +Examples
+++>>> img = np.random.rand(100, 100) +>>> thresholded_img = out_ratio2(img, th=0.2) +>>> print(thresholded_img.min(), thresholded_img.max()) +
+ +Notes
+The function performs element-wise thresholding, so it is suitable for both 2D and 3D arrays.
+
Other thresholding techniques are also available:
+-
+
- +ImagePreprocessFilters.th_otsu(img: ndarray) ndarray +
Apply Otsu’s thresholding to an image based on skimage implementation.
+This function uses Otsu’s method to determine the optimal threshold value and +sets all pixel values below this threshold to 0.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below the threshold set to 0.
+
+
-
+
- +ImagePreprocessFilters.th_isodata(img: ndarray) ndarray +
Apply Isodata thresholding to an image based on skimage implementation.
+This function uses the Isodata method to determine the optimal threshold value and +sets all pixel values below this threshold to 0.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below the threshold set to 0.
+
+
-
+
- +ImagePreprocessFilters.th_li(img: ndarray) ndarray +
Apply Li thresholding to an image based on skimage implementation.
+This function uses the Li method to determine the optimal threshold value and +sets all pixel values below this threshold to 0.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below the threshold set to 0.
+
+
-
+
- +ImagePreprocessFilters.th_yen(img: ndarray) ndarray +
Apply Yen thresholding to an image based on skimage implementation.
+This function uses the Yen method to determine the optimal threshold value and +sets all pixel values below this threshold to 0.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below the threshold set to 0.
+
+
-
+
- +ImagePreprocessFilters.th_triangle(img: ndarray) ndarray +
Apply triangle thresholding to an image based on skimage implementation.
+This function uses the triangle method to determine the optimal threshold value and +sets all pixel values below this threshold to 0.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below the threshold set to 0.
+
+
-
+
- +ImagePreprocessFilters.th_mean(img: ndarray) ndarray +
Apply mean thresholding to an image based on skimage implementation..
+This function uses the mean method to determine the threshold value and +sets all pixel values below this threshold to 0.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below the threshold set to 0.
+
+
-
+
- +ImagePreprocessFilters.th_local(img: ndarray, block_size: int = 3, method: str = 'gaussian') ndarray +
Apply local thresholding to an image based on local +neighborhoods defined by the block size.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array.
+
+- block_sizeint, optional
The size of the local neighborhood for threshold calculation. +Must be an odd number. Default is 3.
+
+- methodstr, optional
The method used for local thresholding. Options include ‘gaussian’, +‘mean’, ‘median’. Default is ‘gaussian’.
+
+
+ +Returns
+-
+
- np.ndarray
The thresholded image with pixels below their local threshold set to 0.
+
+
+ +Examples
+++>>> img = np.random.rand(100, 100) +>>> thresholded_img = th_local(img, block_size=5, method='mean') +>>> print(thresholded_img.min(), thresholded_img.max()) +
+ +Notes
+Local thresholding is useful for images with varying lighting conditions, +as it adjusts the threshold dynamically across the image.
+
Percentile Filter
+In median filters, the center pixel is substituted with the median of the ranked values from its surrounding pixels. They excel in dealing with impulse noise, as such noise usually ranks at the extreme ends of the brightness scale. Percentile filters, akin to median filters, adjust pixel values based on a range of percentiles rather than solely the median (50th percentile). Different markers may benefit from different values of noise reduction, as they may display more or less shot noise.
+To apply percentile filter to each channel:
+-
+
- +ImagePreprocessFilters.percentile_filter(img: ndarray, window_size: int = 3, percentile: int = 50, transf_bool: bool = True, out_ratio: bool = False) ndarray +
Apply a percentile filter ( Scipy implementation) to the image.
++ +Parameters
+-
+
- imgnp.ndarray
The input image as a NumPy array. If different values per channel this should be only the specific channel.
+
+- window_sizeint, optional
The size of the kernel window. Default is 3, creating a 3x3 kernel.
+
+- percentileint, optional
The percentile value to be applied to the array inside the window.
+
+- transf_boolbool, optional
If True, the function will transform the image to boolean values (0 or 1) before applying the filter. +The percentile filter is only applied to determine which pixels are noise and only those are set to 0. +This prevents unnecessary blur by identifying noise and setting those values to zero. +Default is True.
+
+
+ +Returns
+-
+
- np.ndarray
The image filtered with the percentile method.
+
+
+ +Notes
+-
+
The function applies a percentile filter to the input image.
+The kernel used for filtering is a square window of size (window_size, window_size).
+If transf_bool is True, the image is transformed to boolean values (0 or 1) before filtering, +preventing unnecessary blur by identifying noise and setting those values to zero.
+If transf_bool is False, the filter is applied directly to the image.
+
If you want to apply the hybrid median filter, you can check this implementation:
+-
+
- +ImagePreprocessFilters.hybrid_median_filter(img: array, window_size: int = 3, percentile: int = 50, transf_bool=True) array +
Apply a hybrid median filter to the image.
+This function implements a hybrid median filter, which combines the results of percentile filtering +using different shaped kernels (cross, plus, and center pixel) to reduce noise while preserving edges.
++ +Parameters
+-
+
- imgnp.array
The input image as a NumPy array.
+
+- window_sizeint, optional
The size of the kernel window. Default is 3.
+
+- percentileint, optional
The percentile value to be applied to the array inside each kernel.
+
+- transf_boolbool, optional
If True, the function will transform the image to boolean values (0 or 1) before filtering. +This helps identify noise and set those values to zero to prevent unnecessary blur. +Default is True.
+
+
+ +Returns
+-
+
- np.array
The image filtered with the hybrid median filter.
+
+
+ +Notes
+-
+
The hybrid median filter applies percentile filtering using three different shaped kernels: +cross, plus, and center pixel.
+Each kernel is applied to the input image separately, and the results are combined to form a stack of filtered images.
+The final filtered image is obtained by computing the percentile of the stack along the channel axis.
+
Save Images
+Lastly, to save the denoised images one can use ImagePreprocessFilters.save_images() to multitiffs:
-
+
- +ImagePreprocessFilters.save_images(img: array, name: str, ch_last: bool = True) array +
Simple Save a numpy array as a TIFF file.
+This function allows saving a numpy array as a TIFF file. The array can represent an image with multiple channels, +and the function provides an option to specify whether the channels are the last axis of the array.
++ +Parameters
+-
+
- imgnp.array
The input image as a NumPy array.
+
+- namestr
The file path to save the image.
+
+- ch_lastbool, optional
Specifies whether the channels are the last axis of the numpy array. +If True, the array shape is assumed to be (height, width, channels). +If False, the array shape is assumed to be (channels, height, width). +Default is True.
+
+
+ +Returns
+-
+
- np.array
The input image numpy array.
+
+
+ +Notes
+-
+
The function saves the image as a TIFF file using the tifffile library.
+It converts the input array to float32 before saving to ensure compatibility.
+
To save as multipage tiffs with page names as metadata:
+-
+
- +ImagePreprocessFilters.save_images_ch_names(img: array, name: str, ch_last: bool = True, channel_names: list = None) array +
Save a numpy array to a TIFF file with channel names as metadata.
+This function allows saving a numpy array as a TIFF file with optional channel names included as metadata.
++ +Parameters
+-
+
- imgnp.array
The input image as a NumPy array.
+
+- namestr
The file path to save the image.
+
+- ch_lastbool, optional
Specifies whether the channels are the last axis of the numpy array. +If True, the array shape is assumed to be (height, width, channels). +If False, the array shape is assumed to be (channels, height, width). +Default is True.
+
+- channel_nameslist, optional
A list containing channel names for each channel of the image. +If provided, each channel name will be included as metadata in the saved TIFF file. +Default is None.
+
+
+ +Returns
+-
+
- np.array
The input image numpy array.
+
+
+ +Notes
+-
+
The function saves the image as a TIFF file using the tifffile library.
+It converts the input array to float32 before saving to ensure compatibility.
+
And to save the channel names as page names use:
+-
+
- +ImagePreprocessFilters.save_img_ch_names_pages(img: array, name: str, ch_last: bool = True, channel_names: list = None) array +
Save a numpy array as a TIFF file with channel names in the tags of TIFF file pages.
+This function allows saving a numpy array as a multi-page TIFF file. Each page of the TIFF file corresponds +to a channel of the input image, and the function provides an option to specify channel names for each page.
++ +Parameters
+-
+
- imgnp.array
The input image as a NumPy array.
+
+- namestr
The file path to save the image.
+
+- ch_lastbool, optional
Specifies whether the channels are the last axis of the numpy array. +If True, the array shape is assumed to be (height, width, channels). +If False, the array shape is assumed to be (channels, height, width). +Default is True.
+
+- channel_nameslist, optional
A list containing channel names for each channel of the image. +If provided, each TIFF page will have a corresponding channel name in the tags. +Default is None.
+
+
+ +Returns
+-
+
- np.array
The input image numpy array.
+
+
+ +Notes
+-
+
The function saves the image as a multi-page TIFF file using the tifffile library.
+It converts the input array to float32 before saving to ensure compatibility.
+Channel names provided in the channel_names parameter will be included in the tags of TIFF file pages.
+
+
+
+
+