deepdespeckling

denoiser

class deepdespeckling.denoiser.Denoiser

Bases: object

Class to share parameters beyond denoising functions

denoise_image()

denoise_image_kernel()

denoise_images()

get_device() → str

Get torch device to use depending on gpu’s availability

Returns:

device to be used by torch

Return type:

device (str)

initialize_axis_range(image_axis_dim: int, patch_size: int, stride_size: int) → list

Initialize the convolution range for x or y axis

Parameters:

• image_axis_dim (int) – axis size

• patch_size (int) – patch size

• stride_size (int) – stride size

Returns:

pixel borders of each convolution

Return type:

axis_range (list)

preprocess_denoised_image()

save_despeckled_images()

despeckling

deepdespeckling.despeckling.despeckle(sar_images_path: str, destination_directory_path: str, model_name: str = 'spotlight', patch_size: int = 256, stride_size: int = 254, symetrise: bool = True)

Despeckle coSAR images using trained MERLIN (spotlight or stripmap weights) or SAR2SAR

Parameters:

• sar_images_path (str) – path of sar images

• destination_directory_path (str) – path of folder in which results will be stored

• model_name (str) – model name, either “spotlight”, “stripmap” or “Sentinel_TOPS” to select MERLIN model on the right cosar image format or “sar2sar” for SAR2SAR model. Default to “spotlight”

• patch_size (int) – patch size. Defaults to constant PATCH_SIZE.

• stride_size (int) – stride size. Defaults to constant STRIDE_SIZE.

• symetrise (bool) – if using spotlight or stripmap model, if True, will symetrise the real and imaginary parts of the noisy image. Defaults to True

deepdespeckling.despeckling.despeckle_from_coordinates(sar_images_path: str, coordinates_dict: dict, destination_directory_path: str, model_name: str = 'spotlight', patch_size: int = 256, stride_size: int = 254, symetrise: bool = True)

Despeckle specified area with coordinates in coSAR images using trained MERLIN (spotlight or stripmap weights)

Parameters:

• sar_images_path (str) – path of sar images

• coordinates_dict (dict) – dictionary containing pixel boundaries of the area to despeckle (x_start, x_end, y_start, y_end)

• destination_directory_path (str) – path of folder in which results will be stored

• model_name (str) – model name, either “spotlight”, “stripmap” or “Sentinel_TOPS” to select MERLIN model on the right cosar image format or “sar2sar” for SAR2SAR model. Default to “spotlight”

• patch_size (int) – patch size. Defaults to constant PATCH_SIZE.

• stride_size (int) – stride size. Defaults to constant STRIDE_SIZE.

• symetrise (bool) – if using spotlight or stripmap model, if True, will symetrise the real and imaginary parts of the noisy image. Defaults to True

deepdespeckling.despeckling.despeckle_from_crop(sar_images_path: str, destination_directory_path: str, model_name: str = 'spotlight', patch_size: int = 256, stride_size: int = 254, fixed: bool = True, symetrise: bool = True)

Despeckle specified area with an integrated cropping tool (made with OpenCV) in coSAR images using trained MERLIN (spotlight or stripmap weights)

Parameters:

• sar_images_path (str) – path of sar images

• destination_directory_path (str) – path of folder in which results will be stored

• patch_size (int) – patch size. Defaults to constant PATCH_SIZE.

• stride_size (int) – stride size. Defaults to constant STRIDE_SIZE.

• model_name (str) – model name, either “spotlight”, “stripmap” or “Sentinel_TOPS” to select MERLIN model on the right cosar image format or “sar2sar” for SAR2SAR model. Default to “spotlight”

• fixed (bool) – If True, crop size is limited to 256*256. Defaults to True

• symetrise (bool) – if using spotlight or stripmap model, if True, will symetrise the real and imaginary parts of the noisy image. Defaults to True

model

class deepdespeckling.model.Model(device: str, height: int, width: int)

Bases: Module

forward(x: array) → array

Defines a class for an autoencoder algorithm for an object (image) x

An autoencoder is a specific type of feedforward neural networks where the input is the same as the output. It compresses the input into a lower-dimensional code and then reconstruct the output from this representattion. It is a dimensionality reduction algorithm

Parameters:

• x (np.array)

• image (a numpy array containing)

Returns:

• x-n (np.array)

• a numpy array containing the denoised image i.e the image itself minus the noise

merlin_denoiser

class deepdespeckling.merlin.merlin_denoiser.MerlinDenoiser(model_name, symetrise, **params)

Bases: Denoiser

Class to share parameters beyond denoising functions

denoise_image(noisy_image: array, patch_size: int, stride_size: int) → dict

Preprocess and denoise a coSAR image using given model weights

Parameters:

• noisy_image (numpy array) – numpy array containing the noisy image to despeckle

• patch_size (int) – size of the patch of the convolution

• stride_size (int) – number of pixels between one convolution to the next

Returns:

noisy and denoised images

Return type:

despeckled_image (dict)

denoise_image_kernel(noisy_image: tensor, denoised_image: array, x: int, y: int, patch_size: int, model: Model, normalisation_kernel: bool = False) → array

Denoise a subpart of a given symetrised noisy image delimited by x, y and patch_size using a given model

Parameters:

• noisy_image (torch tensor) – symetrised noisy image to denoise

• denoised_image (numpy array) – symetrised partially denoised image

• x (int) – x coordinate of current kernel to denoise

• y (int) – y coordinate of current kernel to denoise

• patch_size (int) – patch size

• model (Model) – trained model with loaded weights

• normalisation_kernel (bool, optional) – Determine if. Defaults to False.

Returns:

image denoised in the given coordinates and the ones already iterated

Return type:

denoised_image (numpy array)

denoise_images(images_to_denoise_path: list, save_dir: str, patch_size: int, stride_size: int)

Iterate over a directory of coSAR images and store the denoised images in a directory

Parameters:

• images_to_denoise_path (list) – a list of paths of npy images to denoise

• save_dir (str) – repository to save sar images, real images and noisy images

• patch_size (int) – size of the patch of the convolution

• stride_size (int) – number of pixels between one convolution to the next

init_min_max_norm_values() → Tuple[float, float]

Initialize min and max values for normalization depending on model name

Returns:

Max and min values for SAR image normalization

Return type:

Tuple[float, float]

init_model_weights_path() → str

Get model weights path from model name

Returns:

the path of the weights of the specified model

Return type:

model_weights_path (str)

load_model(patch_size: int) → Model

Load model with given weights

Parameters:

• weights_path (str) – path to weights

• patch_size (int) – patch size

Returns:

model loaded with stored weights

Return type:

model (Model)

preprocess_denoised_image(denoised_image_real_part: array, denoised_image_imaginary_part: array, count_image: array) → tuple[array, array, array]

Preprocess given denoised real and imaginary parts of an image, and build the full denoised image

Parameters:

• denoised_image_real_part (numpy array) – real part of a denoised image

• denoised_image_imaginary_part (numpy array) – imaginary part of a denoised image

• count_image (numpy array) – normalisation image used for denormalisation

Returns:

processed denoised full image, processed denoised image real part, processed denoised image imaginary part

Return type:

denoised_image, denoised_image_real_part, denoised_image_imaginary_part (numpy array, numpy array, numpy array)

preprocess_noisy_image(noisy_image: array) → tuple[array, array, array]

preprocess a given noisy image and generates its real and imaginary parts

Parameters:

noisy_image (numpy array) – noisy image

Returns:

preprocessed noisy image, real part of noisy image, imaginary part of noisy image

Return type:

noisy_image, noisy_image_real_part, noisy_image_imaginary_part (numpy array, numpy array, numpy array)

save_despeckled_images(despeckled_images: dict, image_name: str, save_dir: str)

Save full, real and imaginary part of noisy and denoised image stored in a dictionary in png to a given folder

Parameters:

• despeckled_images (dict) – dictionary containing full, real and imaginary parts of noisy and denoised image

• image_name (str) – name of the image

• save_dir (str) – path to the folder where to save the png images

sar2sar_denoiser

class deepdespeckling.sar2sar.sar2sar_denoiser.Sar2SarDenoiser(**params)

Bases: Denoiser

Class to share parameters beyond denoising functions

denoise_image(noisy_image: array, patch_size: int, stride_size: int) → dict

Preprocess and denoise a coSAR image using given model weights

Parameters:

• noisy_image (numpy array) – numpy array containing the noisy image to despeckle

• patch_size (int) – size of the patch of the convolution

• stride_size (int) – number of pixels between one convolution to the next

Returns:

denoised image

Return type:

output_image (numpy array)

denoise_image_kernel(noisy_image_kernel: tensor, denoised_image_kernel: array, x: int, y: int, patch_size: int, model: Model, normalisation_kernel: bool = False) → array

Denoise a subpart of a given symetrised noisy image delimited by x, y and patch_size using a given model

Parameters:

• noisy_image_kernel (torch tensor) – part of the noisy image to denoise

• denoised_image_kernel (numpy array) – part of the partially denoised image

• x (int) – x coordinate of current kernel to denoise

• y (int) – y coordinate of current kernel to denoise

• patch_size (int) – patch size

• model (Model) – trained model with loaded weights

• normalisation_kernel (bool, optional) – Determine if. Defaults to False.

Returns:

image denoised in the given coordinates and the ones already iterated

Return type:

denoised_image_kernel (numpy array)

denoise_images(images_to_denoise_path: list, save_dir: str, patch_size: int, stride_size: int)

Iterate over a directory of coSAR images and store the denoised images in a directory

Parameters:

• images_to_denoise_path (list) – a list of paths of npy images to denoise

• save_dir (str) – repository to save sar images, real images and noisy images

• patch_size (int) – size of the patch of the convolution

• stride_size (int) – number of pixels between one convolution to the next

denormalize_sar_image(image: array) → array

Denormalize a sar image stored in a numpy array

Parameters:

image (numpy array) – a sar image

Raises:

TypeError – raise an error if the image file is not a numpy array

Returns:

the image denormalized

Return type:

(numpy array)

load_model(patch_size: int) → Model

Load model with given weights

Parameters:

• weights_path (str) – path to weights

• patch_size (int) – patch size

Returns:

model loaded with stored weights

Return type:

model (Model)

save_despeckled_images(despeckled_images: dict, image_name: str, save_dir: str)

Save full, real and imaginary part of noisy and denoised image stored in a dictionary in png to a given folder

Parameters:

• despeckled_images (dict) – dictionary containing noisy and denoised image

• image_name (str) – name of the image

• save_dir (str) – path to the folder where to save the png images

utils

deepdespeckling.utils.utils.compute_psnr(Shat: array, S: array) → float

Compute Peak Signal to Noise Ratio

Parameters:

• Shat (numpy array) – a SAR amplitude image

• S (numpy array) – a reference SAR image

Returns:

psnr value

Return type:

res (float)

deepdespeckling.utils.utils.create_empty_folder_in_directory(destination_directory_path: str, folder_name: str = 'processed_images') → str

Create an empty folder in a given directory

Parameters:

• destination_directory_path (str) – path pf the directory in which an empty folder is created if it doest not exist yet

• folder_name (str, optional) – name of the folder to create. Defaults to “processed_images”.

Returns:

path of the created empty folder

Return type:

processed_images_path

deepdespeckling.utils.utils.crop_image(image: array, image_path: str, cropping_coordinates: list, model_name: str, processed_images_path: str)

Crop an image using given cropping coordinates and store the result in a given folder

Parameters:

• image (numpy array) – image to be cropped

• image_path (str) – path of the image

• cropping_coordinates (list) – list of coordinates of cropping, format [(x1, y1), (x2, y2)]

• model_name (str) – name of the model (stripmap, spotlight or sar2sar)

• processed_images_path (str) – path of the folder where to store the cropped image in npy format

deepdespeckling.utils.utils.denormalize_sar_image(image: array, M: float = 10.089038980848645, m: float = -1.429329123112601) → array

Denormalize a sar image store in a numpy array

Parameters:

• image (numpy array) – a sar image

• M (float) – global maximum used for normalisation

• m (float) – global minimum used for normalisation

Raises:

TypeError – raise an error if the image file is not a numpy array

Returns:

the image denormalized

Return type:

(numpy array)

deepdespeckling.utils.utils.denormalize_sar_image_sar2sar(image: array) → array

Denormalize a sar image store i a numpy array

Parameters:

image (numpy array) – a sar image

Raises:

TypeError – raise an error if the image file is not a numpy array

Returns:

the image denormalized

Return type:

(numpy array)

deepdespeckling.utils.utils.get_cropping_coordinates(image: array, destination_directory_path: str, model_name: str, fixed: bool = True)

Launch the crop tool to enable the user to select the subpart of the image to be despeckled

Parameters:

• image (numpy aray) – full image to be cropped

• destination_directory_path (str) – path of a folder to store the results

• model_name (str) – model name to be use for despeckling. Default to “spotlight”

• fixed (bool, optional) – whether the area of selection has a fixed size of not. Defaults to True.

deepdespeckling.utils.utils.get_cropping_coordinates_from_file(destination_directory_path: str) → list

Get cropping coordinates from a file where it’s stored

Parameters:

destination_directory_path (str) – path of the file in which the cropping coordinates are stored

Returns:

list containing cropping coordinates

Return type:

cropping_coordinates (list)

deepdespeckling.utils.utils.get_maximum_patch_size(kernel_size: int, patch_bound: int) → int

Get maximum manifold of a number lower than a bound

Parameters:

• kernel_size (int) – the kernel size of the trained model

• patch_bound (int) – the maximum bound of the kernel size

Returns:

the maximum patch size

Return type:

maximum_patch_size (int)

deepdespeckling.utils.utils.get_maximum_patch_size_from_image_dimensions(kernel_size: int, height: int, width: int) → int

Get the maximum patch size from the width and heigth and the kernel size of the model we use

Parameters:

• kernel_size (int) – the kernel size of the trained model

• height (int) – the heigth of the image

• width (int) – the width of the image

Returns:

the maximum patch size to use for despeckling

Return type:

maximum_patch_size (int)

deepdespeckling.utils.utils.load_sar_image(image_path: str) → array

Load a SAR image in a numpy array, use cos2mat function if the file is a cos file, load_tiff_image if the file is a tiff file

Parameters:

image_path (str) – absolute path to a SAR image (cos or npy file)

Returns:

the image of dimension [ncolumns,nlines,2]

Return type:

image (numpy array)

deepdespeckling.utils.utils.load_sar_images(file_list)

Description

Loads files , resize them and append them into a list called data

param filelist:

type filelist:

a path to a folder containing the images

rtype:

A list of images

deepdespeckling.utils.utils.normalize_sar_image(image: array) → array

normalize a sar image store in a numpy array

Parameters:

image (numpy array) – the image to be normalized

Returns:

normalized image

Return type:

(numpy array)

deepdespeckling.utils.utils.preprocess_and_store_sar_images(sar_images_path: str, processed_images_path: str, model_name: str = 'spotlight')

Convert coSAR images to numpy arrays and store it in a specified path

Parameters:

• sar_images_path (str) – path of a folder containing coSAR images to be converted in numpy array

• processed_images_path (str) – path of the folder where converted images are stored

• model_name (str) – model name to be use for despeckling

deepdespeckling.utils.utils.preprocess_and_store_sar_images_from_coordinates(sar_images_path: str, processed_images_path: str, coordinates_dict: dict, model_name: str = 'spotlight')

Convert specified areas of coSAR images to numpy arrays and store it in a specified path

Parameters:

• sar_images_path (str) – path of a folder containing coSAR images to be converted in numpy array

• processed_images_path (str) – path of the folder where converted images are stored

• coordinates_dict (dict) – dictionary containing pixel boundaries of the area to despeckle (x_start, x_end, y_start, y_end)

• model_name (str) – model name to be use for despeckling. Default to “spotlight”

deepdespeckling.utils.utils.preprocess_image(image: array, threshold: float) → array

Preprocess image by limiting pixel values with a threshold

Parameters:

• image (numpy array) – image to preprocess

• threshold (float) – pixel value threshold

Returns:

image to be saved

Return type:

image (cv2 Image)

deepdespeckling.utils.utils.preprocess_sar_image_for_cropping(image: array, model_name: str) → array

Preprocess image to use the cropping tool

Parameters:

• image (numpy array) – image from which we get cropping coordinates by using the cropping tool

• model_name (str) – name of the model (stripmap, spotlight or sar2sar)

Returns:

image preprocessed for cropping

Return type:

image (cv2 image)

deepdespeckling.utils.utils.save_image_to_npy_and_png(image: array, save_dir: str, prefix: str, image_name: str, threshold: float)

Save a given image to npy and png in a given folder

Parameters:

• image (numpy array) – image to save

• save_dir (str) – path to the folder where to save the image

• prefix (str) – prefix of the image file name

• image_name (str) – name of the image file

• threshold (float) – threshold of image pixel values used for png conversion

deepdespeckling.utils.utils.save_image_to_png(image: array, threshold: int, image_full_path: str)

Save a given image to a png file in a given folder

Parameters:

• image (numpy array) – image to save

• threshold (float) – threshold of pixel values of the image to be saved in png

• image_full_path (str) – full path of the image

Raises:

TypeError – if the image is not a numpy array

deepdespeckling.utils.utils.symetrise_real_and_imaginary_parts(real_part: array, imag_part: array) → tuple[array, array]

Symetrise given real and imaginary parts to ensure MERLIN properties

Parameters:

• real_part (numpy array) – real part of the noisy image to symetrise

• imag_part (numpy array) – imaginary part of the noisy image to symetrise

Returns:

symetrised real and imaginary parts of a noisy image

Return type:

np.real(ima2), np.imag(ima2) (numpy array, numpy array)

load_cosar

deepdespeckling.utils.load_cosar.cos2mat(path_to_cosar_image: str) → array

Convert a CoSAR imge to a numpy array of size [ncolumns,nlines,2]

Parameters:

path_to_cosar_image (str) – path to the image which is a cos file

Returns:

the image in a numpy array

Return type:

numpy array

deepdespeckling.utils.load_cosar.load_tiff_image(path_to_tiff_image: str) → array

Load a tiff image in a numpy array using gdal library

Parameters:

path_to_tiff_image (str) – path to a tiff image

Returns:

numpy array containing the tiff image

Return type:

(numpy array)