pandora2d.img_tools

This module contains functions associated to raster images.

Classes

Datasets

NamedTuple to store left and right datasets.

Functions

create_datasets_from_inputs(→ Datasets)	Read image and return the corresponding xarray.DataSet
check_disparities(→ None)	Do various check against disparities properties.
check_disparity_presence(→ None)	Check that disparity keys are not missing from input_config.
check_disparity_types(→ None)	Check that disparity a dictionary with keys "init" and range"
add_disparity_grid(→ xarray.Dataset)	Add disparity to dataset
get_min_max_disp_from_dicts(...)	Transforms input disparity dicts with constant init into min/max disparity grids
shift_disp_row_img(→ xarray.Dataset)	Return a Dataset that contains the shifted right images
get_margins_values(→ tuple[int, int])	Generate the values of margins
get_roi_processing(→ dict)	Return a roi which takes disparities into account.
remove_roi_margins(dataset, cfg)	Remove ROI margins before saving output dataset
row_zoom_img(→ xarray.Dataset)	Return a list that contains the shifted right images in row
col_zoom_img(→ xarray.Dataset)	Return a list that contains the shifted right images in col
shift_subpix_img(→ list[xarray.Dataset])	Return an array that contains the shifted right images
shift_subpix_img_2d(→ list[xarray.Dataset])	Return an array that contains the shifted right images in rows and columns
get_initial_disparity(→ numpy.typing.NDArray | int)	Return initial disparity.
get_extrema_disparity(→ tuple[int, int])	Returns [min, max] disparity
convert_no_data(→ float | int)	If no_data is NaN or Inf, return -9999.

Module Contents

class pandora2d.img_tools.Datasets

Bases: NamedTuple

NamedTuple to store left and right datasets.

left: xarray.Dataset

right: xarray.Dataset

pandora2d.img_tools.create_datasets_from_inputs(input_config: dict, roi: dict = None, estimation_cfg: dict = None, attributes: dict = None) → Datasets

Read image and return the corresponding xarray.DataSet

Parameters:

• input_config – configuration used to create dataset.

• roi –

  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

• estimation_cfg – dictionary containing estimation configuration

• attributes – dictionary with attribute parameters

Returns:

Datasets NamedTuple with two attributes left and right each containing a xarray.DataSet containing the variables :

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

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

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

pandora2d.img_tools.check_disparities(input_config: dict) → None

Do various check against disparities properties.

Parameters:

input_config – configuration used to create dataset.

Raises:

SystemExit – If any check fails.

pandora2d.img_tools.check_disparity_presence(input_config: dict) → None

Check that disparity keys are not missing from input_config.

Parameters:

input_config – configuration used to create dataset.

Raises:

SystemExit – if one or both keys are missing

pandora2d.img_tools.check_disparity_types(disparity: Any) → None

Check that disparity a dictionary with keys “init” and range” where “init” is either:

• an integer

• a path to a grid with integer values

Parameters:

disparity – disparity to check

Raises:

SystemExit – if it does not meet requirements

pandora2d.img_tools.add_disparity_grid(dataset: xarray.Dataset, col_disparity: dict, row_disparity: dict, attributes: dict = None, right: bool = False) → xarray.Dataset

Add disparity to dataset

Parameters:

• dataset – xarray dataset

• col_disparity – Disparity interval for columns

• row_disparity – Disparity interval for rows

• attributes – dictionary with attribute parameters

• right – indicates whether the disparity grid is added to the right dataset

Returns:

dataset : updated dataset

pandora2d.img_tools.get_min_max_disp_from_dicts(dataset: xarray.Dataset, disparity: dict, origin: pandora2d.types.Origin, step: pandora2d.types.Step, user_invalid_disp: int | float, right: bool = False) → tuple[numpy.typing.NDArray, list, float | None]

Transforms input disparity dicts with constant init into min/max disparity grids

Parameters:

• dataset – xarray dataset

• disparity – input disparity

• origin – origin of the grid

• step – step that separates two points in the disparity grid

• user_invalid_disp – user invalid disparity value

• right – indicates whether the disparity grid is added to the right dataset

Returns:

3D numpy array containing min/max disparity grids and list with disparity source

pandora2d.img_tools.shift_disp_row_img(img_right: xarray.Dataset, dec_row: int) → xarray.Dataset

Return a Dataset that contains the shifted right images

Parameters:

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

• dec_row – the value of shifting for dispy

Returns:

img_right_shift: Dataset containing the shifted image

pandora2d.img_tools.get_margins_values(init_value: int | numpy.ndarray, range_value: int, margins: list) → tuple[int, int]

Generate the values of margins

Parameters:

• init_value – init value for disparity interval

• range_value – range value for disparity interval

• margins – necessary value for margins

Returns:

Margins value

pandora2d.img_tools.get_roi_processing(roi: dict, col_disparity: dict, row_disparity: dict, from_previous_run: bool = False) → dict

Return a roi which takes disparities into account. Update cfg roi with new margins.

Parameters:

• roi –

  roi in config file

  ”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

• col_disparity – init and range for disparities in columns.

• row_disparity – init and range for disparities in rows.

• from_previous_run – True when initial disparity grids come from a previous Pandora2D run (local coordinates); passed through to get_initial_disparity to skip ROI windowing.

pandora2d.img_tools.remove_roi_margins(dataset: xarray.Dataset, cfg: dict)

Remove ROI margins before saving output dataset

Parameters:

• dataset – dataset containing disparity row and col maps

• cfg – output configuration of the pandora2d machine

pandora2d.img_tools.row_zoom_img(img: numpy.ndarray, ny: int, subpix: int, coords: xarray.Coordinates, ind: int, no_data: float | int, order: int = 1) → xarray.Dataset

Return a list that contains the shifted right images in row

This method is temporary, the user can then choose the filter for this function

Parameters:

• img – image to shift

• ny – row number in data

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

• coords – coordinates for output datasets

• ind – index of range(subpix)

• no_data – no_data value in img

• order – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.

Returns:

an array that contains the shifted right images in row

pandora2d.img_tools.col_zoom_img(img: numpy.ndarray, nx: int, subpix: int, coords: xarray.Coordinates, ind: int, no_data: float | int, order: int = 1) → xarray.Dataset

Return a list that contains the shifted right images in col

This method is temporary, the user can then choose the filter for this function

Parameters:

• img – image to shift

• nx – col number in data

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

• coords – coordinates for output datasets

• ind – index of range(subpix)

• no_data – no_data value in img

• order – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.

Returns:

an array that contains the shifted right images in col

pandora2d.img_tools.shift_subpix_img(img_right: xarray.Dataset, subpix: int, row: bool = True, order: int = 1) → list[xarray.Dataset]

Return an array that contains the shifted right images

Parameters:

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

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

• row – row to shift (otherwise column)

• order – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.

Returns:

an array that contains the shifted right images

pandora2d.img_tools.shift_subpix_img_2d(img_right: xarray.Dataset, subpix: int, order: int = 1) → list[xarray.Dataset]

Return an array that contains the shifted right images in rows and columns

Parameters:

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

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

• column – column to shift (otherwise row)

• order – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.

Returns:

an array that contains the shifted right images

pandora2d.img_tools.get_initial_disparity(disparity: dict, roi: dict | None = None, from_previous_run: bool = False) → numpy.typing.NDArray | int

Return initial disparity.

When initial disparity is read from a file, nodata and infinite values are replaced by NaNs. When a ROI is provided and the raster is NOT from a previous run, only the pixels within the ROI are read, preventing border outliers from inflating the extrema used to compute ROI processing margins. When the raster comes from a previous run (from_previous_run=True), it is already cropped to the relevant zone in local coordinates, so the full raster is read regardless of the ROI.

Parameters:

• disparity – init and range for disparities in columns.

• roi – optional ROI dict with keys “row” and “col”, each containing “first” and “last”.

• from_previous_run – True when the disparity raster was produced by a previous Pandora2D run and is therefore stored in local (ROI-relative) coordinates.

Returns:

initial disparity

pandora2d.img_tools.get_extrema_disparity(init_value: numpy.typing.NDArray | float, range_value: int) → tuple[int, int]

Returns [min, max] disparity

Parameters:

• init_value – initial disparity

• range_value – disparity exploration value

Returns:

[min disparity, max disparity]

pandora2d.img_tools.convert_no_data(no_data: float | int) → float | int

If no_data is NaN or Inf, return -9999. Otherwise return no_data.

Parameters:

no_data – no data value

Returns:

updated no data value