pandora.img_tools

This module contains functions associated to raster images.

Module Contents

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_classif(→ xarray.Dataset)

Add classification information and image to dataset

add_segm(→ xarray.Dataset)

Add Segmentation 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

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

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

interpolate_nodata_sgm(→ Tuple[numpy.ndarray, ...)

Interpolation of the input image to resolve invalid (nodata) pixels.

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

find_valid_neighbors(dirs, disp, valid, row, col)

Find valid neighbors along directions

compute_mean_patch(→ numpy.float64)

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
pandora.img_tools.rasterio_open(*args: str, **kwargs: int | str | None) → rasterio.io.DatasetReader[source]

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[source]

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[source]

Add disparity to dataset

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_classif(dataset: xarray.Dataset, classif: str | None, window: rasterio.windows.Window) → xarray.Dataset[source]

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[source]

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_no_data(dataset: xarray.Dataset, no_data: int | float, no_data_pixels: numpy.ndarray) → xarray.Dataset[source]

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: numpy.ndarray, width: int, height: int, window: rasterio.windows.Window) → xarray.Dataset[source]

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.create_dataset_from_inputs(input_config: dict, roi: dict = None) → xarray.Dataset[source]

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

Return type:

xarray.DataSet

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

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)

Returns:

partial xarray.DataSet (attributes and coordinates)

Return type:

xarray.DataSet

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]][source]

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][source]

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(img: numpy.ndarray, valid: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray][source]

Interpolation of the input image to resolve invalid (nodata) pixels. Interpolate invalid pixels by finding the nearest correct pixels in 8 different directions and use the median of their disparities.

HIRSCHMULLER, Heiko. Stereo processing by semiglobal matching and mutual information. IEEE Transactions on pattern analysis and machine intelligence, 2007, vol. 30, no 2, p. 328-341.

Parameters:

  • img (2D np.ndarray (row, col)) – input image

  • valid (2D np.ndarray (row, col)) – validity mask

Returns:

the interpolate input image, with the validity mask update :

  • If out & PANDORA_MSK_PIXEL_FILLED_NODATA != 0 : Invalid pixel : filled nodata pixel

Return type:

tuple(2D np.array (row, col), 2D np.array (row, col))

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

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]) → List[xarray.Dataset][source]

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) → List[xarray.Dataset][source]

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

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[source]

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[source]

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[source]

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(dirs: numpy.ndarray, disp: numpy.ndarray, valid: numpy.ndarray, row: int, col: int)[source]

Find valid neighbors along directions

Parameters:

  • dirs (2D np.ndarray (row, col)) – directions

  • disp (2D np.ndarray (row, col)) – disparity map

  • valid (2D np.ndarray (row, col)) – validity mask

  • row (int) – row current value

  • col (int) – col current value

Returns:

valid neighbors

Return type:

2D np.ndarray

pandora.img_tools.compute_mean_patch(img: xarray.Dataset, row: int, col: int, win_size: int) → numpy.float64[source]

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[source]

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][source]
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[source]

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