biapy.engine.denoising

Denoising workflow and utilities for BiaPy.

This module provides the Denoising_Workflow class for training and inference on image denoising tasks, as well as utility functions for patch manipulation, stratified coordinate sampling, and structN2V masking. It supports both 2D and 3D data, and includes implementations of various pixel manipulation strategies used in self-supervised denoising approaches such as Noise2Void (N2V).

class biapy.engine.denoising.Denoising_Workflow(cfg, job_identifier, device, system_dict, args, **kwargs)

Bases: Base_Workflow

Denoising workflow where the goal is to remove noise from an image.

More details in our documentation.

Parameters:

• cfg (YACS configuration) – Running configuration.

• job_identifier (str) – Complete name of the running job.

• device (torch.device) – Device used.

• args (argparse.Namespace) – Arguments used in BiaPy’s call.

define_activations_and_channels()

Define the activations to be applied to the model output and the channels that the model will output.

This function must define the following variables:

self.model_output_channelsList of int

Number of channels for each output head of the model. E.g. [3] for a model with one head outputting 3 channels, [1, 5] for a model with two heads outputting 1 and 5 channels respectively, etc.

self.model_output_channel_infoList of str

Information about the output channels. A value per output head of the model must be defined.

self.separated_class_channelbool

Whether if we should expect a separated output channel for classification.

self.head_activationsList of str

Activations to be applied to the model output. A value per output channel (not output head) of the model must be defined. “linear” and “ce_sigmoid” will not be applied. E.g. [“linear”] for a model with one channel, [“linear”, “sigmoid”] for a model with two channels, etc.

Example of a correct definition of the function for a model with two output heads: 1) the first one will be predicting foreground and contours; 2) the second one will classify into 3 classes the predicted objects. In this case the following definition would be correct:

self.model_output_channels = [1, 3]
self.model_output_channel_info = ["mask", "class"]
self.separated_class_channel = True
self.head_activations = ["ce_sigmoid", "ce_sigmoid", "ce_softmax", "ce_softmax", "ce_softmax"]

define_metrics()

Define the metrics to be used during training and test/inference.

This function must define the following variables:

self.train_metricsList of functions

Metrics to be calculated during model’s training.

self.train_metric_namesList of str

Names of the metrics calculated during training.

self.train_metric_bestList of str

To know which value should be considered as the best one. Options must be: “max” or “min”.

self.test_metricsList of functions

Metrics to be calculated during model’s test/inference.

self.test_metric_namesList of str

Names of the metrics calculated during test/inference.

self.lossFunction

Loss function used during training and test.

metric_calculation(output: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | Tensor, targets: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | Tensor, train: bool = True, metric_logger: MetricLogger | None = None) → Dict

Execute the calculation of metrics defined in define_metrics() function.

Parameters:

• output (Torch Tensor) – Prediction of the model.

• targets (Torch Tensor) – Ground truth to compare the prediction with.

• train (bool, optional) – Whether to calculate train or test metrics.

• metric_logger (MetricLogger, optional) – Class to be updated with the new metric(s) value(s) calculated.

Returns:

out_metrics – Value of the metrics for the given prediction.

Return type:

dict

process_test_sample()

Process a sample in the test/inference phase.

torchvision_model_call(in_img: Tensor, is_train: bool = False) → Tensor | None

Call a regular Pytorch model.

Parameters:

• in_img (torch.Tensor) – Input image to pass through the model.

• is_train (bool, optional) – Whether if the call is during training or inference.

Returns:

prediction – Image prediction.

Return type:

torch.Tensor

after_merge_patches(pred: Tensor)

Execute steps needed after merging all predicted patches into the original image.

Parameters:

pred (Torch Tensor) – Model prediction.

after_full_image(pred: ndarray[tuple[int, ...], dtype[_ScalarType_co]])

Execute steps needed after generating the prediction by supplying the entire image to the model.

Parameters:

pred (NDArray) – Model prediction.

after_all_images()

Excute steps that must be done after predicting all images.

after_all_chunk_prediction_workflow_process()

Place any code that needs to be done after predicting all patches in “by chunks” setting. This function is called on all ranks.

after_all_chunk_prediction_workflow_process_master_rank()

Place any code that needs to be done after predicting all patches in “by chunks” setting, but only on the master rank. This function is called only on the master rank.

biapy.engine.denoising.get_subpatch(patch, coord, local_sub_patch_radius, crop_patch=True)

Extract a subpatch centered at a given coordinate, handling border cropping.

Parameters:

• patch (np.ndarray) – Input patch.

• coord (tuple of int) – Center coordinate for the subpatch.

• local_sub_patch_radius (int) – Radius of the subpatch to extract.

• crop_patch (bool, optional) – Whether to crop the patch at the borders (default: True).

Returns:

• subpatch (np.ndarray) – Extracted subpatch.

• crop_neg (int) – Negative crop offset.

• crop_pos (int) – Positive crop offset.

biapy.engine.denoising.random_neighbor(shape, coord)

Sample a random neighbor coordinate different from the given coordinate.

Parameters:

• shape (tuple of int) – Shape of the patch.

• coord (tuple of int) – Center coordinate.

Returns:

rand_coords – Random neighbor coordinate.

Return type:

list of int

biapy.engine.denoising.sample_coords(shape, coord, sigma=4)

Sample random coordinates from a normal distribution centered at coord.

Parameters:

• shape (tuple of int) – Shape of the patch.

• coord (tuple of int) – Center coordinate.

• sigma (float, optional) – Standard deviation for the normal distribution (default: 4).

Returns:

coords – Sampled coordinates.

Return type:

list of int

biapy.engine.denoising.normal_int(mean, sigma, w)

Sample an integer from a normal distribution and clip to valid range.

Parameters:

• mean (float) – Mean of the normal distribution.

• sigma (float) – Standard deviation.

• w (int) – Maximum allowed value (exclusive).

Returns:

Sampled and clipped integer.

Return type:

int

biapy.engine.denoising.mask_center(local_sub_patch_radius, ndims=2)

Create a mask with the center pixel set to zero.

Parameters:

• local_sub_patch_radius (int) – Radius of the patch.

• ndims (int, optional) – Number of dimensions (default: 2).

Returns:

mask – Boolean mask with center pixel set to zero.

Return type:

np.ndarray

biapy.engine.denoising.pm_normal_withoutCP(local_sub_patch_radius)

Return a function that samples a random neighbor from a normal distribution (without center pixel).

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns values from random neighbors.

Return type:

Callable

biapy.engine.denoising.pm_mean(local_sub_patch_radius)

Return a function that computes the mean of the local neighborhood (excluding center pixel).

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns mean values.

Return type:

Callable

biapy.engine.denoising.pm_median(local_sub_patch_radius)

Return a function that computes the median of the local neighborhood (excluding center pixel).

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns median values.

Return type:

Callable

biapy.engine.denoising.pm_uniform_withCP(local_sub_patch_radius)

Return a function that samples a random value from the local neighborhood (including center pixel).

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns random values.

Return type:

Callable

biapy.engine.denoising.pm_uniform_withoutCP(local_sub_patch_radius)

Return a function that samples a random value from the local neighborhood (excluding center pixel).

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns random values.

Return type:

Callable

biapy.engine.denoising.pm_normal_additive(pixel_gauss_sigma)

Return a function that adds Gaussian noise to the center pixel.

Parameters:

pixel_gauss_sigma (float) – Standard deviation of the Gaussian noise.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns noisy values.

Return type:

Callable

biapy.engine.denoising.pm_normal_fitted(local_sub_patch_radius)

Return a function that samples from a Gaussian fitted to the local neighborhood.

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch.

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns sampled values.

Return type:

Callable

biapy.engine.denoising.pm_identity(local_sub_patch_radius)

Return a function that simply returns the center pixel value (identity).

Parameters:

local_sub_patch_radius (int) – Radius of the local subpatch (unused).

Returns:

Function that takes (patch, coords, dims, structN2Vmask) and returns the center pixel value.

Return type:

Callable

biapy.engine.denoising.get_stratified_coords2D(box_size, shape)

Generate stratified random coordinates for 2D patches.

Parameters:

• box_size (int) – Size of the box for stratification.

• shape (tuple of int) – Shape of the 2D image.

Returns:

(y_coords, x_coords) for sampled points.

Return type:

tuple of lists

biapy.engine.denoising.get_stratified_coords3D(box_size, shape)

Generate stratified random coordinates for 3D patches.

Parameters:

• box_size (int) – Size of the box for stratification.

• shape (tuple of int) – Shape of the 3D image.

Returns:

(z_coords, y_coords, x_coords) for sampled points.

Return type:

tuple of lists

biapy.engine.denoising.apply_structN2Vmask(patch, coords, mask)

Apply a structN2V mask to a 2D patch.

Each point in coords corresponds to the center of the mask. For each point in the mask with value=1, assign a random value.

Parameters:

• patch (np.ndarray) – Input patch to modify.

• coords (np.ndarray or list) – Coordinates of mask centers.

• mask (np.ndarray) – Binary mask to apply.

biapy.engine.denoising.apply_structN2Vmask3D(patch, coords, mask)

Apply a structN2V mask to a 3D patch.

Each point in coords corresponds to the center of the mask. For each point in the mask with value=1, assign a random value.

Parameters:

• patch (np.ndarray) – Input 3D patch to modify.

• coords (np.ndarray or list) – Coordinates of mask centers (z, y, x).

• mask (np.ndarray) – Binary mask to apply.

biapy.engine.denoising.manipulate_val_data(X_val: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]], Y_val: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]], perc_pix: float = 0.198, shape: ~typing.Tuple[int, ...] = (64, 64), value_manipulation: ~typing.Callable = <function pm_uniform_withCP.<locals>.random_neighbor_withCP_uniform>)

Manipulate validation data for self-supervised denoising.

Applies a value manipulation strategy (e.g., uniform, mean, median) to a percentage of pixels in the validation set, as used in Noise2Void/structN2V validation.

Parameters:

• X_val (NDArray) – Validation input data.

• Y_val (NDArray) – Validation target data (will be overwritten).

• perc_pix (float, optional) – Percentage of pixels to manipulate (default: 0.198).

• shape (tuple of int, optional) – Shape of the patch (default: (64, 64)).

• value_manipulation (Callable, optional) – Function to manipulate pixel values (default: pm_uniform_withCP(5)).

biapy.engine.denoising.get_value_manipulation(n2v_manipulator, n2v_neighborhood_radius)

Return a value manipulation function for N2V/structN2V based on the given strategy.

Parameters:

• n2v_manipulator (str) – Name of the manipulation strategy (e.g., ‘uniform_withCP’).

• n2v_neighborhood_radius (int) – Neighborhood radius for the manipulation.

Returns:

Value manipulation function.

Return type:

Callable