pandora.img_tools

This module contains functions associated to raster images.

Attributes

interpolate_nodata_sgm
find_valid_neighbors

Functions

rasterio_open(→ rasterio.io.DatasetReader)	rasterio.open wrapper to silence UserWarning like NotGeoreferencedWarning.
get_window(→ rasterio.windows.Window)	Get window from image size and roi
add_disparity(→ xarray.Dataset)	Add disparity to dataset
add_disparity_grid(→ xarray.Dataset)	Add a disparity grid to dataset.
add_classif(→ xarray.Dataset)	Add classification information and image to dataset
add_segm(→ xarray.Dataset)	Add Segmentation information and image to dataset
add_edges(→ xarray.Dataset)	Add Edges information and image to dataset
add_no_data(→ xarray.Dataset)	Add no data information to dataset
add_mask(→ xarray.Dataset)	Add mask information and image to dataset
add_global_disparity(→ xarray.Dataset)	Add global disparity information to dataset
create_dataset_from_inputs(→ xarray.Dataset)	Read image and mask, and return the corresponding xarray.DataSet
get_metadata(→ xarray.Dataset)	Read metadata from image, and return the corresponding xarray.DataSet
get_pyramids(data, num_scales, scale_factor[, ...])	Returns the pyramid of images, of height num_scales and width factor scale_factor
prepare_pyramid(→ Tuple[List[xarray.Dataset], ...)	Return a List with the datasets at the different scales
fill_nodata_image(→ Tuple[numpy.ndarray, numpy.ndarray])	Interpolate no data values in image. If no mask was given, create all valid masks
masks_pyramid(→ List[numpy.ndarray])	Return a List with the downsampled masks for each scale
convert_pyramid_to_dataset(→ List[xarray.Dataset])	Return a List with the datasets at the different scales
shift_right_img(→ List[xarray.Dataset])	Return an array that contains the shifted right images
check_inside_image(→ bool)	Check if the coordinates row,col are inside the image
census_transform(→ xarray.Dataset)	Generates the census transformed image from an image
compute_mean_raster(→ numpy.ndarray)	Compute the mean within a sliding window for the whole image
compute_mean_patch(→ numpy.float32)	Compute the mean within a window centered at position row,col
compute_std_raster(→ numpy.ndarray)	Compute the standard deviation within a sliding window for the whole image
read_disp(→ Tuple[int, int] | Tuple[numpy.ndarray, ...)	Read the disparity :
fuse_classification_bands(→ numpy.ndarray)	Get the multiband classification map present in the input image dataset

Module Contents

pandora.img_tools.rasterio_open(*args: str, **kwargs: int | str | None) → rasterio.io.DatasetReader

rasterio.open wrapper to silence UserWarning like NotGeoreferencedWarning.

(see https://rasterio.readthedocs.io/en/latest/api/rasterio.errors.html)

Parameters:

• args (str) – args to be given to rasterio.open method

• kwargs (Union[int, str, None]) – kwargs to be given to rasterio.open method

Returns:

rasterio DatasetReader

Return type:

rasterio.io.DatasetReader

pandora.img_tools.get_window(roi: Dict, width: int, height: int) → rasterio.windows.Window

Get window from image size and roi

Parameters:

roi –

dictionnary with a roi

”col”: {“first”: <value - int>, “last”: <value - int>}, “row”: {“first”: <value - int>, “last”: <value - int>}, “margins”: [<value - int>, <value - int>, <value - int>, <value - int>]

with margins : left, up, right, down :type roi: dict :param width: image width :type width: int :param height: image height :type height: int :return: Window : Windowed reading with rasterio :rtype: Window

pandora.img_tools.add_disparity(dataset: xarray.Dataset, disparity: Tuple[int, int] | list[int] | str | None, window: rasterio.windows.Window) → xarray.Dataset

Add disparity to dataset

If disparity is None, will return dataset unmodified.

Parameters:

• dataset (xr.Dataset) – xarray dataset without classification

• disparity (Tuple[int, int] or list[int] or str or None) – disparity, or path to the disparity grid

:param window : Windowed reading with rasterio :type window: Window :return: dataset : updated dataset :rtype: xr.Dataset

pandora.img_tools.add_disparity_grid(dataset: xarray.Dataset, disparity_grid: xarray.DataArray | None = None, disparity_source: Tuple[int, int] | list[int] | str | None = 'xr.Dataset') → xarray.Dataset

Add a disparity grid to dataset.

If disparity_grid is None, will return dataset unmodified.

Parameters:

• dataset (xr.Dataset) – xarray dataset without classification

• disparity_grid (xr.DataArray or None) – disparity grid dataset with dimensions [“band_disp”, “row”, “col”] or None.

• disparity_source (Union[Tuple[int, int], list[int], str, None]) – source of the disparity: either a path to a file or xr.Dataset if the dataset was directly provided.

Returns:

dataset : updated dataset

Return type:

xr.Dataset

pandora.img_tools.add_classif(dataset: xarray.Dataset, classif: str | None, window: rasterio.windows.Window) → xarray.Dataset

Add classification information and image to dataset

Parameters:

• dataset (xr.Dataset) – xarray dataset without classification

• classif (str or None) – classification image path

:param window : Windowed reading with rasterio :type window: Window :return: dataset : updated dataset :rtype: xr.Dataset

pandora.img_tools.add_segm(dataset: xarray.Dataset, segm: str | None, window: rasterio.windows.Window) → xarray.Dataset

Add Segmentation information and image to dataset

Parameters:

• dataset (xr.Dataset) – xarray dataset without segmentation

• segm (str or None) – segmentation image path

:param window : Windowed reading with rasterio :type window: Window :return: dataset : updated dataset :rtype: xr.Dataset

pandora.img_tools.add_edges(dataset: xarray.Dataset, edges: str | None, window: rasterio.windows.Window) → xarray.Dataset

Add Edges information and image to dataset

Parameters:

• dataset (xr.Dataset) – xarray dataset without edges

• edges (str or None) – edges image path

:param window : Windowed reading with rasterio :type window: Window :return: dataset : updated dataset :rtype: xr.Dataset

pandora.img_tools.add_no_data(dataset: xarray.Dataset, no_data: int | float, no_data_pixels: Tuple[numpy.ndarray, Ellipsis]) → xarray.Dataset

Add no data information to dataset

Parameters:

• dataset (xr.Dataset) – xarray dataset without no_data information

• no_data (int or float) – value

• no_data_pixels (np.ndarray) – matrix with no_data value

Returns:

dataset : updated dataset

Return type:

xr.Dataset

pandora.img_tools.add_mask(dataset: xarray.Dataset, mask: str | None, no_data_pixels: Tuple[numpy.ndarray, Ellipsis], width: int, height: int, window: rasterio.windows.Window) → xarray.Dataset

Add mask information and image to dataset

Parameters:

• dataset (xr.Dataset) – xarray dataset without mask

• mask (str or None) – mask image path

• no_data_pixels (np.ndarray) – matrix with no_data value

• width (int) – nb columns

• height (int) – nb rows

• window (rasterio.window) – information about window

Returns:

dataset : updated dataset

Return type:

xr.Dataset

pandora.img_tools.add_global_disparity(dataset: xarray.Dataset, global_disp_min: int, global_disp_max: int) → xarray.Dataset

Add global disparity information to dataset

Parameters:

• dataset (xr.Dataset) – xarray dataset without no_data information

• global_disp_min (int) – global minimum disparity

• global_disp_max (int) – global maximum disparity

Returns:

dataset : updated dataset

Return type:

xr.Dataset

pandora.img_tools.create_dataset_from_inputs(input_config: dict, roi: dict = None) → xarray.Dataset

Read image and mask, and return the corresponding xarray.DataSet

Parameters:

• input_config (dict) – configuration used to create dataset.

• roi (dict) –

  dictionary with a roi

  ”col”: {“first”: <value - int>, “last”: <value - int>}, “row”: {“first”: <value - int>, “last”: <value - int>}, “margins”: [<value - int>, <value - int>, <value - int>, <value - int>]

  with margins : left, up, right, down

Returns:

xarray.DataSet containing the variables :

• im: 2D (row, col) or 3D (band_im, row, col) xarray.DataArray float32

• disparity (optional): 3D (disp, row, col) xarray.DataArray float32

• msk (optional): 2D (row, col) xarray.DataArray int16

• classif (optional): 3D (band_classif, row, col) xarray.DataArray int16

• segm (optional): 2D (row, col) xarray.DataArray int16

• edges (optional): 2D (row, col) xarray.DataArray int16

Return type:

xarray.DataSet

pandora.img_tools.get_metadata(img: str, disparity: list[int] | str | None = None, classif: str = None, segm: str = None, edges: str = None) → xarray.Dataset

Read metadata from image, and return the corresponding xarray.DataSet

Parameters:

• img (str) – img_path

• disparity (list[int] | str | None) – disparity couple of ints or path to disparity grid file (optional)

• classif (str) – path to the classif (optional)

• segm (str) – path to the segm (optional)

• edges (str) – path to the edges (optional)

Returns:

partial xarray.DataSet (attributes and coordinates)

Return type:

xarray.DataSet

pandora.img_tools.get_pyramids(data, num_scales, scale_factor, channel_axis=None)

Returns the pyramid of images, of height num_scales and width factor scale_factor

Parameters:

• data (2D or 3D np.ndarray) – image

• num_scales (int) – number of scaled images

• scale_factor (float) – ratio in width/height between two consecutives images of the pyramid

Returns:

the list of images in the pyramid, large to small

Return type:

list(np.ndarray)

pandora.img_tools.prepare_pyramid(img_left: xarray.Dataset, img_right: xarray.Dataset, num_scales: int, scale_factor: int) → Tuple[List[xarray.Dataset], List[xarray.Dataset]]

Return a List with the datasets at the different scales

Parameters:

• img_left (xarray.Dataset) – left Dataset image containing the image im : 2D (row, col) xarray.Dataset

• img_right (xarray.Dataset) – right Dataset image containing the image im : 2D (row, col) xarray.Dataset

• num_scales (int) – number of scales

• scale_factor (int) – factor by which downsample the images

Returns:

a List that contains the different scaled datasets

Return type:

List of xarray.Dataset

pandora.img_tools.fill_nodata_image(dataset: xarray.Dataset) → Tuple[numpy.ndarray, numpy.ndarray]

Interpolate no data values in image. If no mask was given, create all valid masks

Parameters:

dataset (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

Returns:

a Tuple that contains the filled image and mask

Return type:

Tuple of np.ndarray

pandora.img_tools.interpolate_nodata_sgm

pandora.img_tools.masks_pyramid(msk: numpy.ndarray, scale_factor: int, num_scales: int) → List[numpy.ndarray]

Return a List with the downsampled masks for each scale

Parameters:

• msk (np.ndarray) – full resolution mask

• scale_factor (int) – scale factor

• num_scales (int) – number of scales

Returns:

a List that contains the different scaled masks

Return type:

List of np.ndarray

pandora.img_tools.convert_pyramid_to_dataset(img_orig: xarray.Dataset, images: List[numpy.ndarray], masks: List[numpy.ndarray], disps=None) → List[xarray.Dataset]

Return a List with the datasets at the different scales

Parameters:

• img_orig (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• images (list[np.ndarray]) – list of images for the pyramid

• masks (list[np.ndarray]) – list of masks for the pyramid

Returns:

a List that contains the different scaled datasets

Return type:

List of xarray.Dataset

pandora.img_tools.shift_right_img(img_right: xarray.Dataset, subpix: int, band: str = None, order: int = 1) → List[xarray.Dataset]

Return an array that contains the shifted right images

Parameters:

• img_right (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• subpix (int) – subpixel precision = (1 or pair number)

• band (str) – User’s value for selected band

• order (int) – order parameter on zoom method

Returns:

an array that contains the shifted right images

Return type:

array of xarray.Dataset

pandora.img_tools.check_inside_image(img: xarray.Dataset, row: int, col: int) → bool

Check if the coordinates row,col are inside the image

Parameters:

• img (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• row (int) – row coordinates

• col (int) – column coordinates

Returns:

True if the coordinates row,col are inside the image

Return type:

boolean

pandora.img_tools.census_transform(image: xarray.Dataset, window_size: int, band: str = None) → xarray.Dataset

Generates the census transformed image from an image

Parameters:

• image (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• window_size (int) – Census window size

• band (str) – User’s value for selected band

Returns:

Dataset census transformed uint32 containing the transformed image im: 2D (row, col) xarray.DataArray uint32

Return type:

xarray.Dataset

pandora.img_tools.compute_mean_raster(img: xarray.Dataset, win_size: int, band: str = None) → numpy.ndarray

Compute the mean within a sliding window for the whole image

Parameters:

• img (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• win_size (int) – window size

• band (str) – User’s value for selected band

Returns:

mean raster

Return type:

numpy array

pandora.img_tools.find_valid_neighbors

pandora.img_tools.compute_mean_patch(img: xarray.Dataset, row: int, col: int, win_size: int) → numpy.float32

Compute the mean within a window centered at position row,col

Parameters:

• img (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• row (int) – row coordinates

• col (int) – column coordinates

• win_size (int) – window size

Returns:

mean

Return type:

float

pandora.img_tools.compute_std_raster(img: xarray.Dataset, win_size: int, band: str = None) → numpy.ndarray

Compute the standard deviation within a sliding window for the whole image with the formula : std = sqrt( E[row^2] - E[row]^2 )

Parameters:

• img (xarray.Dataset) – Dataset image containing the image im : 2D (row, col) xarray.Dataset

• win_size (int) – window size

• band (str) – User’s value for selected band

Returns:

std raster

Return type:

numpy array

pandora.img_tools.read_disp(disparity: Tuple[int, int] | list[int] | str) → Tuple[int, int] | Tuple[numpy.ndarray, numpy.ndarray]

Read the disparity :

• if cfg_disp is the path of a disparity grid, read and return the grids (type tuple of numpy arrays)

• else return the value of cfg_disp

Parameters:

disparity (Tuple[int, int] or list[int] or str) – disparity, or path to the disparity grid

Returns:

the disparity

Return type:

Tuple[int, int] | Tuple[np.ndarray, np.ndarray]

pandora.img_tools.fuse_classification_bands(img: xarray.Dataset, class_names: List[str]) → numpy.ndarray

Get the multiband classification map present in the input image dataset and select the given classes to make a single-band classification map

Parameters:

• img (xr.Dataset) – image dataset

• class_names (List[str]) – chosen classification classes

Returns:

the map representing the selected classifications

Return type:

np.ndarray