biapy.data.pre_processing

Pre-processing utilities for image and mask data in deep learning workflows.

This module provides pre-processing functions for instance segmentation, detection mask creation, self-supervised learning data generation, semantic segmentation probability maps, and general image processing operations such as resizing, blurring, edge detection, histogram matching, and CLAHE. It supports both 2D and 3D data formats and integrates with BiaPy configuration objects for flexible data pipelines.

biapy.data.pre_processing.cellpose_diameter_from_areas(areas, is_3d: bool = False) → float

Compute the Cellpose-style median cell diameter (pixels) from a list of per-object areas (voxel counts).

Each object’s equivalent diameter is 2*sqrt(area/pi) in 2D (so the median equals Cellpose’s median(sqrt(counts))/(sqrt(pi)/2)) or the sphere-equivalent 2*(3V/4pi)^(1/3) in 3D. This is the shared core of cellpose_diameter_stats(); it is also used to combine per-object counts accumulated patch by patch (Zarr/H5).

Parameters:

• areas (array-like) – Per-object voxel counts (background excluded).

• is_3d (bool, optional) – Whether the data is 3-D.

Returns:

Median object diameter in pixels, or 0.0 when no object is present.

Return type:

float

biapy.data.pre_processing.cellpose_diameter_stats(instance_labels: ndarray[tuple[int, ...], dtype[_ScalarType_co]], is_3d: bool = False) → Dict

Compute the Cellpose-style median cell diameter (pixels) of an instance-label image.

Mirrors Cellpose’s utils.diameters (see cellpose_diameter_from_areas()). In 3D the sphere-equivalent diameter is used (no in-plane/anisotropy correction; prefer an explicit PROBLEM.INSTANCE_SEG.CELLPOSE.DIAMETER for strongly anisotropic 3D data).

Parameters:

• instance_labels (Numpy array) – Instance-label image, optionally with a trailing channel axis. E.g. (y, x), (y, x, 1), (z, y, x) or (z, y, x, 1).

• is_3d (bool, optional) – Whether the data is 3-D.

Returns:

{"diameter": float, "n_objects": int}. diameter is 0.0 when no foreground is present.

Return type:

dict

biapy.data.pre_processing.save_cellpose_diameter_stats(stats: Dict, channels_dir: str, split: str)

Write per-image Cellpose diameter stats to a per-rank JSON shard.

The JSON is written to the parent of channels_dir (not inside it), because BiaPy expects the instance-channels folder to contain only images. The split ("train"/"val"/ "test") is encoded in the filename so the train/val/test shards do not collide when their channel folders share a parent. Per-rank shards avoid write races when the channels are created with several processes; they are merged back by load_cellpose_diameter_stats().

Parameters:

• stats (dict) – Mapping of image basename -> {"diameter": float, "n_objects": int}.

• channels_dir (str) – Directory where the instance-channel masks (flows) are stored. The JSON goes to its parent.

• split (str) – Data split the stats belong to ("train", "val" or "test"); encoded in the filename.

biapy.data.pre_processing.load_cellpose_diameter_stats(channels_dir: str, split: str) → Dict

Load and merge the per-image Cellpose diameter JSON shard(s) written during channel creation.

The shards are read from the parent of channels_dir and filtered by split (matching how save_cellpose_diameter_stats() writes them).

Parameters:

• channels_dir (str) – Directory where the instance-channel masks (flows) are stored. The cellpose_diameters_ {split}_rank*.json shard(s) are looked up in its parent.

• split (str) – Data split to load ("train", "val" or "test").

Returns:

Mapping of image basename -> diameter (pixels). Empty if no JSON is found.

Return type:

dict

biapy.data.pre_processing.save_embedseg_grid_size(grid_size: int, channels_dir: str)

Persist the EmbedSeg coordinate GRID_SIZE in the parent of channels_dir (like the Cellpose diameter stats), so it is carried from training to inference and both share one scale.

biapy.data.pre_processing.load_embedseg_grid_size(channels_dir: str) → int | None

Load the GRID_SIZE JSON written by save_embedseg_grid_size(), or None if absent.

biapy.data.pre_processing.set_embedseg_grid_size(cfg: CfgNode) → int | None

Resolve the EmbedSeg coordinate grid size (PROBLEM.INSTANCE_SEG.EMBEDSEG.GRID_SIZE).

If the config value is > 0 it is used as-is. Otherwise (-1, the default) the canonical grid is the dataset’s max image dimension rounded up to a multiple of 8 – mirroring EmbedSeg’s n_x = n_y – computed once from the train/val/test images and cached to a JSON next to the training instance-channel folder (via save_embedseg_grid_size()) so training and inference stay consistent, exactly like the Cellpose diameter. Returns None for non-EmbedSeg workflows.

biapy.data.pre_processing.set_cellpose_diameters(cfg: CfgNode, Y_train, Y_val=None)

Attach the per-image Cellpose diameter (pixels) to each GT DatasetFile.

For the Cellpose/Omnipose flow workflow this lets the train generator rescale every patch by DIAM_MEAN / diameter so cells become ~``DIAM_MEAN`` pixels (mirroring Cellpose’s diameter normalization). The per-image diameter is always taken from the cellpose_diameters*.json written when the instance channels were created — PROBLEM.INSTANCE_SEG.CELLPOSE.DIAMETER is NOT used here (it only drives the test-time input rescale), matching Cellpose, which measures the diameter of each training image from its labels. When the validation set is split from train (DATA.VAL.FROM_TRAIN) no val JSON exists, so the val files fall back to the train stats (matched by basename). Files without a known diameter are left unscaled.

Parameters:

• cfg (YACS CN object) – Configuration.

• Y_train (BiaPyDataset) – Training GT dataset whose DatasetFile entries get .diameter set (in place).

• Y_val (BiaPyDataset, optional) – Validation GT dataset (same treatment).

Returns:

Representative diameter (median across training files), or None when no diameter is available. Useful for logging and as the test-time fallback prior.

Return type:

float or None

biapy.data.pre_processing.create_instance_channels(cfg: CfgNode, data_type: str = 'train')

Create training and validation new data with appropiate channels based on PROBLEM.INSTANCE_SEG.DATA_CHANNELS for instance segmentation.

Parameters:

• cfg (YACS CN object) – Configuration.

• data_type (str, optional) – Wheter to create training or validation instance channels.

biapy.data.pre_processing.instances_to_flows(vol: ndarray[tuple[int, ...], dtype[_ScalarType_co]], resolution: List[float | int] = [1, 1, 1], niter: int | str = 'auto', gradient_type: str = 'cellpose') → Tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None]

Compute the Cellpose/Omnipose flow components from an instance label map.

gradient_type="cellpose": per-cell heat diffusion from the cell centre (the pixel closest to the per-axis mean), then the normalized gradient of that potential – matching Cellpose’s dynamics.masks_to_flows_cpu.

gradient_type="omnipose": normalized gradient of the per-cell Euclidean distance transform.

Shared by the training-target generator (labels_into_channels()) and the data generator, which regenerates the flows from the augmented labels so the image and the flow target stay consistent under augmentations that resample geometry (see pair_base_data_generator.PairBaseDataGenerator.apply_transform).

Parameters:

• vol (2D/3D Numpy array) – Instance label map (0 = background), e.g. (y, x) or (z, y, x).

• resolution (list of int/float, optional) – Voxel spacing (z, y, x). Only the last vol.ndim entries are used.

• niter (int or “auto”, optional) – Diffusion steps per cell (Cellpose only). "auto" uses Cellpose’s counts: 2*(h+w+4) in 2D and 6*(d+h+w+3) in 3D.

• gradient_type (str, optional) – Either "cellpose" or "omnipose".

Returns:

• Gv, Gh (Numpy arrays) – Y and X flow components (unit vectors inside cells, 0 in background).

• Gz (Numpy array or None) – Z flow component in 3D, None in 2D.

biapy.data.pre_processing.unique_labels_fast(a: ndarray)

Find the unique labels in an integer array a in [0, K] in O(n) time and O(K) space.

Parameters:

a (ndarray) – Input array of integers.

Returns:

Array of unique labels.

Return type:

ndarray

biapy.data.pre_processing.instance_channel_needs_regen(ch: str, channel_extra_opts: Dict = {}) → bool

Whether a channel’s GT must be recomputed from the augmented labels (vs. warped).

Directional channels are always corrupted by warping; distance channels only when they keep absolute (unnormalized) values, since per-cell normalization makes them scale-invariant. Everything else (binary masks, per-instance-normalized D, embedding labels) warps safely.

biapy.data.pre_processing.channel_physical_offsets(mode: List[str], channel_extra_opts: Dict = {}) → Dict[str, int]

Compute the physical start channel index of each instance-segmentation data channel.

Most channels occupy a single channel, but some expand: 'R' into nrays channels and 'A' into the number of requested affinities. 'E_sigma'/'E_seediness' are extra embedding targets that are not materialised as their own channels here, so they are skipped. The returned offsets are the cumulative widths of the preceding channels, so a channel placed after an expanded block (e.g. the virtual 'I' after 'R') gets its true position rather than its index in mode — matching how labels_into_channels() allocates the array.

Parameters:

• mode (list of str) – Ordered channel names. E.g. ['Db', 'R', 'I'].

• channel_extra_opts (dict, optional) – Per-channel options, used to read R['nrays'] and the A affinity lists.

Returns:

offsets – Physical start channel index of each entry in mode (last occurrence wins if repeated).

Return type:

dict of str -> int

biapy.data.pre_processing.labels_into_channels(instance_labels: ndarray[tuple[int, ...], dtype[_ScalarType_co]], mode: List[str] = ['I', 'C'], channel_extra_opts: Dict = {}, resolution: List[float | int] = [1, 1, 1], save_dir: str | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Convert input semantic or instance segmentation data masks into different binary channels to train an instance segmentation problem.

Parameters:

• instance_labels (3D/4D Numpy array) – Instance labels to be used to extract the channels from. E.g. (200, 1000, 1000, 1)

• mode (List, optional) –

  Operation mode. Possible values: C, BC, BCM, BCD, BD, BCDv2, Dv2, BDv2 and BP.

  • ‘B’ stands for ‘Binary segmentation’, containing each instance region without the contour.

  • ‘C’ stands for ‘Contour’, containing each instance contour.

  • ‘D’ stands for ‘Distance’, each instance containing its distance to its own boundary, normalized per instance to [0, 1], and the background set to -1.

  • ‘M’ stands for ‘Mask’, contains the B and the C channels, i.e. the foreground mask. Is simply achieved by binarizing input instance masks.

  • ‘Dv2’ stands for ‘Distance V2’, which is an updated version of ‘D’ channel calculating background distance as well.

  • ‘P’ stands for ‘Points’ and contains the central points of an instance (as in Detection workflow)

  • ‘A’ stands for ‘Affinities” and contains the affinity values for each dimension

• channel_extra_opts (dict, optional) – Additional options for each output channel (e.g., {“I”: {“erosion”: 1}}).

• resolution (Tuple of int/float) – Resolution of the data, in (z,y,x) to calibrate coordinates. E.g. [30,8,8].

• save_dir (str, optional) – Path to store samples of the created array just to debug it is correct.

Returns:

new_mask – Instance representations. The shape will be as the input instance_labels but with the amount of channels requested. E.g. (200, 1000, 1000, 3)

Return type:

3D/4D Numpy array

biapy.data.pre_processing.norm_channel(channel: ndarray[tuple[int, ...], dtype[_ScalarType_co]], vol: ndarray[tuple[int, ...], dtype[_ScalarType_co]], instances: list[int]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Normalize a channel based on instance masks.

Parameters:

• channel (NDArray) – The channel to normalize (e.g. db_channel).

• vol (NDArray) – Instance mask volume, same shape as channel.

• instances (list[int]) – List of instance IDs in vol. Background (0) will be ignored.

Returns:

Normalized channel, same shape as input.

Return type:

NDArray

biapy.data.pre_processing.slice_from_props(props_tbl: DataFrame | dict, i: int, ndim: int) → tuple[slice, ...]

Get a slice representation from the properties table for a specific instance.

Parameters:

• props_tbl (pd.DataFrame | dict) – The properties table containing region properties.

• i (int) – The index of the instance in the properties table.

• ndim (int) – The number of dimensions (2 or 3).

Returns:

A tuple of slice objects representing the bounding box of the instance.

Return type:

tuple[slice, …]

biapy.data.pre_processing.unet_border_weight_map(instances: ndarray, w0: float = 10.0, sigma: float = 5.0, apply_only_background: bool = True, resolution: List[float | int] | None = None) → ndarray

U-Net border-aware weight map (Ronneberger et al. 2015) for 2D or 3D labels.

Parameters:

• instances (np.ndarray, shape (H, W) or (D, H, W), dtype int) – 0/background for background, 1..N (or any ints != background) are instance ids.

• w0 (float) – Border weight magnitude.

• sigma (float) – Spatial decay (in same units as resolution).

• apply_only_background (bool) – If True, apply the exponential term only on background (as in the paper).

• resolution (List[int|float] | None) – Voxel spacing along each axis (z,y,x) or (y,x). If None, isotropic spacing of 1 is assumed.

Returns:

w – Border weight map.

Return type:

np.ndarray, same shape as instances, dtype float32

biapy.data.pre_processing.touching_mask_nd(labels: ndarray[tuple[int, ...], dtype[_ScalarType_co]], connectivity: int = 1) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Create a binary mask of touching pixels/voxels for an N-D labeled instance mask.

Parameters:

• labels (NDArray) – N-D array of instance labels (0 = background, 1..N = instances).

• connectivity (int, optional) – Neighborhood connectivity passed to generate_binary_structure. 1 = 6-neigh for 3D / 4-neigh for 2D, 2 = 18-neigh for 3D / 8-neigh for 2D, 3 = 26-neigh for 3D (if ndim==3).

Returns:

touch – Binary mask with 1 where a voxel touches at least one different instance.

Return type:

NDArray

biapy.data.pre_processing.generate_rays(n_rays: int, ndim: int, jitter: bool = False, seed: int = 0)

Unit directions in R^ndim. - 2D: uniform angles on circle -> (R,2) [dx,dy] - 3D: Fibonacci sphere -> (R,3) [dx,dy,dz]

Parameters:

• n_rays (int) – Number of rays to generate.

• ndim (int) – Dimensionality (2 or 3).

• jitter (bool, optional) – Whether to add jitter to 3D rays (default: False).

• seed (int, optional) – Random seed for jitter (default: 0).

Returns:

rays – Unit vectors along which to compute distances.

Return type:

(n_rays, 2) or (n_rays, 3) Numpy array

biapy.data.pre_processing.radial_distances(labels: ndarray[tuple[int, ...], dtype[_ScalarType_co]], rays: ndarray[tuple[int, ...], dtype[_ScalarType_co]], max_dist: float | None = None, spacing: Sequence[float] | None = None) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Compute radial distances from each foreground pixel to the instance boundary along specified rays.

Parameters:

• labels (NDArray) – 2D or 3D array of instance labels (0 = background, 1..N = instances).

• rays ((n_rays, 2) or (n_rays, 3) Numpy array) – Unit vectors along which to compute distances. Expected in Cartesian order [x,y] or [x,y,z] as returned by generate_rays.

• max_dist (float, optional) – Maximum distance to cap at. If None, no capping is done.

• spacing (sequence of float, optional) – Physical spacing of the data in axis order [y,x] for 2D or [z,y,x] for 3D. If None, assumes isotropic spacing of 1.0.

Returns:

D – Array of shape (H, W, n_rays) or (D, H, W, n_rays) with distances in physical units. Background pixels have distance 0 in all rays.

Return type:

NDArray

biapy.data.pre_processing.euler_integration(flow: ndarray[tuple[int, ...], dtype[_ScalarType_co]], coords: ndarray[tuple[int, ...], dtype[_ScalarType_co]], n_steps: int = 200, dt: float = 1.0, suppressed: bool = True)

Euler integration of flow field starting at coords.

Parameters:

• flow ((2, H, W) or (3, D, H, W) Numpy array) – Flow field (y,x) or (z,y,x).

• coords ((N, 2) or (N, 3) Numpy array) – Starting coordinates (y,x) or (z,y,x) in index space.

• n_steps (int) – Number of integration steps.

• dt (float) – Integration step size.

• suppressed (bool) – Whether to use time-suppressed integration (dt/(t+1)) or not (constant dt).

Returns:

pos – Final positions after integration.

Return type:

(N, 2) or (N, 3) Numpy array

biapy.data.pre_processing.synapse_channel_creation(data_info: Dict, zarr_data_information: Dict, savepath: str, mode: List[str] = ['F_pre', 'F_post'], channel_extra_opts: Dict[str, Dict] = {}, verbose: bool = False)

Create different channels that represent a synapse segmentation problem to train an instance segmentation problem.

This function is only prepared to read an H5/Zarr file that follows CREMI data format.

Parameters:

• data_info (dict) – All patches that can be extracted from all the Zarr/H5 samples in data_path. Keys created are:

  • "filepath": path to the file where the patch was extracted.

  • "full_shape": shape of the data within the file where the patch was extracted.

  • "patch_coords": coordinates of the data that represents the patch.

• zarr_data_information (dict) – Information when using Zarr/H5 files. Assumes that the H5/Zarr files contain the information according CREMI data format. The following keys are expected:

  • "raw_data_path": path within the file where the raw data is stored. Reference in CREMI: volumes/raw

  • "axes_order": order of the axes in the file. E.g. “ZYX” or “ZCYX”.

  • "z_axe_pos": position of z axis of the data within the file.

  • "y_axe_pos": position of y axis of the data within the file.

  • "x_axe_pos": position of x axis of the data within the file.

  • "id_path": path within the file where the ids are stored. Reference in CREMI: annotations/ids

  • "partners_path": path within the file where partners is stored. Reference in CREMI: annotations/partners

  • "locations_path": path within the file where locations is stored. Reference in CREMI: annotations/locations

  • "resolution_path": path within the file where resolution is stored. Reference in CREMI: ["volumes/raw"].attrs["offset"]

• savepath (str) – Path to save the data created.

• mode (List, optional) – Operation mode.

• channel_extra_opts (dict, optional) – Extra options for specific channels. For example, dilation for the “F_pre” and “F_post” channels. Expected keys are:

  • "F_pre": options for the “F_pre” channel. Expected keys are:

    • "dilation": list of 3 ints specifying the dilation in z,y,x for the “F_pre” channel (default: [1,10,10]).

  • "F_post": options for the “F_post” channel. Expected keys are:

    • "dilation": list of 3 ints specifying the dilation in z,y,x for the “F_post” channel (default: [1,10,10]).

  • "H", "V", "Z": options for the distance channels. Expected keys are:

    • "norm": whether to normalize the distance channels per instance (default: True).

• verbose (bool, optional) – Whether to print warnings about out-of-bounds synaptic points (default: False).

Returns:

• new_mask (5D Numpy array) – 5D array with 3 channels instead of one. E.g. (10, 200, 1000, 1000, 3)

• patch_offset (list of list) – Pixels used on each axis to pad the patch in order to not cut some of the values in the edges.

biapy.data.pre_processing.create_HoVe_channels(data: ndarray[tuple[int, ...], dtype[_ScalarType_co]], ref_point: str = 'center', label_to_pre_site: Dict | None = None, normalize_values: bool = True, calc_props: Dict | None = None, axis_order: str = 'ZYX', resolution: List[float | int] = [1, 1, 1])

Obtain the horizontal and vertical distance maps for each instance.

Depth distance is also calculated if the data provided is 3D.

Parameters:

• data (2D/3D Numpy array) – Instance mask to create horizontal/vertical/depth channels from. E.g. (500, 500) for 2D and (200, 1000, 1000) for 3D.

• ref_point (str, optional) – Reference point used to create the horizontal/vertical/depth channels. Possible values are center and presynaptic. center points to the centroid, while presynaptic points to the presynaptic site (and requires label_to_pre_site).

• label_to_pre_site (dict, optional) – Reference of the presynaptic site for each label within the provided volume (data).

• normalize_values (bool, optional) – Whether to normalize the values or not.

• calc_props (dict, optional) – If region properties have already been calculated, they can be provided here to avoid recalculation.

• resolution (list of int or float, optional) – Physical resolution of the data in each dimension. Used to scale the horizontal/vertical/depth values to physical units if provided. Default is [1,1,1] (isotropic).

Returns:

new_mask – Horizontal/vertical/depth channels. E.g. (500, 500, 2) for 2D and (200, 1000, 1000, 3) for 3D.

Return type:

3D/4D Numpy array

biapy.data.pre_processing.generate_ellipse_footprint(shape=[1, 1, 1]) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Generate footprint of an ellipse in a n-dimensional image.

Parameters:

shape (list, optional) – Shape of the hyperball with the given side lengths.

Returns:

distances – Ellipse footprint.

Return type:

NDArray

biapy.data.pre_processing.create_detection_masks(cfg: CfgNode, data_type: str = 'train')

Create detection masks based on CSV files.

Parameters:

• cfg (YACS CN object) – Configuration.

• data_type (str, optional) – Wheter to create train, validation or test masks.

biapy.data.pre_processing.create_ssl_source_data_masks(cfg: CfgNode, data_type: str = 'train')

Create SSL source data.

Parameters:

cfg (YACS CN object) – Configuration.

data_type: str, optional

Wheter to create train, validation or test source data.

biapy.data.pre_processing.crappify(input_img: ndarray[tuple[int, ...], dtype[_ScalarType_co]], resizing_factor: float, add_noise: bool = True, noise_level: float | None = None, Down_up: bool = True)

Crappify input image by adding Gaussian noise and downsampling and upsampling it so the resolution gets worsen.

input_img4D/5D Numpy array

Data to be modified. E.g. (y, x, channels) if working with 2D images or (z, y, x, channels) if working with 3D.

resizing_factorfloats

Downsizing factor to reshape the image.

add_noiseboolean, optional

Indicating whether to add gaussian noise before applying the resizing.

noise_level: float, optional

Number between [0,1] indicating the std of the Gaussian noise N(0,std).

Down_upbool, optional

Indicating whether to perform a final upsampling operation to obtain an image of the same size as the original but with the corresponding loss of quality of downsizing and upsizing.

Returns:

img – Train images. E.g. (y, x, channels) if working with 2D images or (z, y, x, channels) if working with 3D.

Return type:

4D/5D Numpy array

biapy.data.pre_processing.add_gaussian_noise(image: ndarray[tuple[int, ...], dtype[_ScalarType_co]], percentage_of_noise: float) → ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Add Gaussian noise to an input image.

Parameters:

• image (3D Numpy array) – Image to be added Gaussian Noise with 0 mean and a certain std. E.g. (y, x, channels).

• percentage_of_noise (float) – percentage of the maximum value of the image that will be used as the std of the Gaussian Noise distribution.

Returns:

out – Transformed image. E.g. (y, x, channels).

Return type:

3D Numpy array

biapy.data.pre_processing.calculate_volume_prob_map(Y: BiaPyDataset, is_3d: bool = False, w_foreground: float = 0.94, w_background: float = 0.06, save_dir=None) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Calculate the probability map of the given data.

Parameters:

• Y (list of dict) – Data to calculate the probability map from. Each item in the list represents a sample of the dataset. Expected keys:

  • "filename": name of the image to extract the data sample from.

  • "dir": directory where the image resides.

  • "img": image sample itself. It is a ndarrray of (y, x, channels) in 2D and (z, y, x, channels)``in ``3D. Provided if the user selected to load data into memory.

  If "img" is provided "filename" and "filename" are not necessary, and vice versa.

• w_foreground (float, optional) – Weight of the foreground. This value plus w_background must be equal 1.

• w_background (float, optional) – Weight of the background. This value plus w_foreground must be equal 1.

• save_dir (str, optional) – Path to the file where the probability map will be stored.

Returns:

maps – Probability map(s) of all samples in Y.sample_list.

Return type:

NDArray or list of NDArray

biapy.data.pre_processing.resize_images(images: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], **kwards) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Resize all the images using the specified parameters or default values if not provided.

Parameters:

• images (list of Numpy arrays) – The images parameter is the list of all input images that you want to resize.

• output_shape (iterable) – Size of the generated output image. E.g. (256,256)

• (kwards) (optional) – skimage.transform.resize() parameters are also allowed.

Returns:

resized_images – The resized images. The returned data will use the same data type as the given images.

Return type:

list of Numpy arrays

biapy.data.pre_processing.apply_gaussian_blur(images: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], **kwards) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Apply a Gaussian blur to all images.

Parameters:

• images (list of Numpy arrays) – The input images on which the Gaussian blur will be applied.

• (kwards) (optional) – skimage.filters.gaussian() parameters are also allowed.

Returns:

blurred_images – A Gaussian blurred images. The returned data will use the same data type as the given images.

Return type:

list of Numpy arrays

biapy.data.pre_processing.apply_median_blur(images: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], **kwards) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Apply a median blur filter to all images.

Parameters:

• image (list of Numpy arrays) – The input image on which the median blur operation will be applied.

• (kwards) (optional) – skimage.filters.median() parameters are also allowed.

Returns:

blurred_images – The median-blurred images. The returned data will use the same data type as the given images.

Return type:

list of Numpy arrays

biapy.data.pre_processing.detect_edges(images: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], **kwards) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Detect edges in the given images using the Canny edge detection algorithm.

The function detect_edges takes the 2D images as input, converts it to grayscale if necessary, and applies the Canny edge detection algorithm to detect edges in the image.

Parameters:

• images (list of Numpy arrays) – The list of all input images on which the edge detection will be performed. It can be either a color image with shape (height, width, 3) or a grayscale image with shape (height, width, 1).

• (kwards) (optional) – skimage.feature.canny() parameters are also allowed.

Returns:

edges – The edges of the input images. The returned Numpy arrays will be uint8, where background is black (0) and edges white (255). The returned data will use the same structure as the given images (list[Numpy array] or Numpy array).

Return type:

list of Numpy arrays

biapy.data.pre_processing.apply_histogram_matching(images: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], reference_path: str, is_2d: bool)

Apply histogram matching to a list of images based on the histogram of reference images.

The function returns the images with their histogram matched to the histogram of the reference images, loaded from the given reference_path.

Parameters:

• images (list of Numpy arrays) – The list of input images whose histogram needs to be matched to the reference histogram. It should be a Numpy array representing the image.

• reference_path (str) – The reference_path is the directory path to the reference images. From reference images, we will extract the reference histogram with which we want to match the histogram of the images. It represents the desired distribution of pixel intensities in the output image.

• is_2d (bool, optional) – The value indicate if the data given in reference_path is 2D (is_2d = True) or 3D (is_2d = False). Defaults to True.

Returns:

matched_images – The result of matching the histogram of the input images to the histogram of the reference image. The returned data will use the same data type as the given images.

Return type:

list of Numpy arrays

biapy.data.pre_processing.apply_clahe(images: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], **kwards) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]

Apply Contrast Limited Adaptive Histogram Equalization (CLAHE) to a list of images.

The function applies Contrast Limited Adaptive Histogram Equalization (CLAHE) to an image and returns the result.

Parameters:

• images (list of Numpy arrays) – The list of input images that you want to apply the CLAHE (Contrast Limited Adaptive Histogram Equalization) algorithm to.

• (kwards) (optional) – skimage.exposure.equalize_adapthist() parameters are also allowed.

Returns:

processed_images – The images after applying the Contrast Limited Adaptive Histogram Equalization (CLAHE) algorithm. The returned data will use the same data type as the given images.

Return type:

list of Numpy arrays

biapy.data.pre_processing.preprocess_data(cfg: CfgNode, x_data: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] = [], y_data: List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] = [], is_2d: bool = True, is_y_mask: bool = False) → List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]] | Tuple[List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], List[ndarray[tuple[int, ...], dtype[_ScalarType_co]]]]

Pre-process data by applying various image processing techniques.

Parameters:

• cfg (dict) – The cfg parameter is a configuration object that contains various settings for preprocessing the data. It is used to control the behavior of different preprocessing techniques such as image resizing, blurring, histogram matching, etc.

• x_data (list of 3D/4D Numpy arrays, optional) – The input data (images) to be preprocessed. The first dimension must be the number of images. E.g. (num_of_images, y, x, channels) or (num_of_images, z, y, x, channels). In case of using a list, the format of the images remains the same. Each item in the list corresponds to a different image.

• y_data (list of 3D/4D Numpy arrays, optional) – The target data that corresponds to the x_data. The first dimension must be the number of images. E.g. (num_of_images, y, x, channels) or (num_of_images, z, y, x, channels). In case of using a list, the format of the images remains the same. Each item in the list corresponds to a different image.

• is_2d (bool, optional) – A boolean flag indicating whether the reference data for histogram matching is 2D or not. Defaults to True.

• is_y_mask (bool, optional) – is_y_mask is a boolean parameter that indicates whether the y_data is a mask or not. If it is set to True, the resize operation for y_data will use the nearest neighbor interpolation method (order=0), otherwise it will use the interpolation method specified in the cfg.RESIZE.ORDER parameter. Defaults to False.

Returns:

• x_data (list of 3D/4D Numpy arrays, optional) – Preprocessed data. The same structure and dimensionality of the given data will be returned.

• y_data (list of 3D/4D Numpy arrays, optional) – Preprocessed data. The same structure and dimensionality of the given data will be returned.