shareloc.geofunctions.rectification

This module contains functions to generate stereo-rectification epipolar grids

Functions

write_epipolar_grid(grid, filename, geotransform[, ...])	Write epipolar grid in a tiff file
compute_epipolar_angle(end_line, start_line)	Define the epipolar angle
compute_local_epipolar_line(geom_model_left, ...)	Estimate the beginning and the ending of local epipolar line in left image
prepare_rectification(left_im, geom_model_left, ...[, ...])	Determine size and spacing of the epipolar grids.
get_epipolar_extent(left_im, geom_model_left, ...[, ...])	Return epipolar rectification grid footprint using reprojection of epipolar geometry in left image.
moving_along_axis(geom_model_left, geom_model_right, ...)	Moving to the next line in epipolar geometry
compute_strip_of_epipolar_grid(geom_model_left, ...[, ...])	Compute stereo-rectification epipolar grids by strip. We start with a starting positions_point,
init_inputs_rectification(left_im, geom_model_left, ...)	Inputs rectification with its starting point, spacing, grid size, rectified_image size.
positions_to_displacement_grid(left_grid, right_grid, ...)	Transform position grids to displacement grid
compute_stereorectification_epipolar_grids(left_im, ...)	Compute stereo-rectification epipolar grids. Rectification scheme is composed of :

Module Contents

shareloc.geofunctions.rectification.write_epipolar_grid(grid, filename, geotransform, xy_convention=True)

Write epipolar grid in a tiff file

Parameters:

• grid (np.ndarray) – epipolar grid (row,col,3)

• filename (str) – output filename

• geotransform (Affine) – grid geotransform

• xy_convention (bool) – True: write grid with xy convention : [band 1 = col displacement, band 2 = row displacement, band 3 = altitude] False: write grid with yx convention : [band 1 = row displacement, band 2 = col displacement, band 3 = altitude]

• xy_convention – bool

shareloc.geofunctions.rectification.compute_epipolar_angle(end_line, start_line)

Define the epipolar angle

Parameters:

• end_line (1D np.array [row, col, altitude] or 2D np.array [number of points, [row, col, altitude]]) – ending of the epipolar line (georeferenced coordinates)

• start_line (1D np.array [row, col, altitude] or 2D np.array [number of points, [row, col, altitude]]) – beginning of the epipolar line (georeferenced coordinates)

Returns:

epipolar angle

Return type:

float or 1D np.array

shareloc.geofunctions.rectification.compute_local_epipolar_line(geom_model_left, geom_model_right, left_point, elevation, elevation_offset)

Estimate the beginning and the ending of local epipolar line in left image

Parameters:

• geom_model_left (GeomodelTemplate) – geometric model of the left image

• geom_model_right (GeomodelTemplate) – geometric model of the right image

• left_point (1D numpy array : [row coord, col coord, altitude] or 2D numpy array : (number of points, [row coord, col coord, altitude])) – georeferenced coordinates in the left image

• elevation (shareloc.dtm or float) – elevation

• elevation_offset (float) – elevation difference used to estimate the local tangent

Returns:

Coordinates of the beginning and the ending of local epipolar line in the left image

Return type:

Tuple(1D np.array [row, col, altitude], 1D numpy array [row, col, altitude]) or Tuple(2D np.array (nb points, [row, col, altitude]), 2D np.array (nb points, [row, col, altitude]))

shareloc.geofunctions.rectification.prepare_rectification(left_im, geom_model_left, geom_model_right, elevation, epi_step, elevation_offset, margin=0)

Determine size and spacing of the epipolar grids. Determine size of the epipolar images and the upper-left origin of the stereo-rectified left image (starting point)

Parameters:

• left_im (shareloc.image object) – left image

• geom_model_left (GeomodelTemplate) – geometric model of the left image

• geom_model_right (GeomodelTemplate) – geometric model of the right image

• elevation (shareloc.dtm or float) – elevation

• epi_step (int) – epipolar step

• elevation_offset (int) – elevation difference used to estimate the local tangent

• margin (int) – margin of the rectification grid (in grid pixels)

Returns:

• epipolar grids spacing (pixel size), 1D np.array [row pixel size, col pixel size]

• epipolar grids size, 1D np.array [number of row, number of columns]

• epipolar images size, 1D np.array [number of row, number of columns]

• epipolar grid corners in left image geometry [ul, ll, lr, ur]

  2D np.array [georef corner_row, georef corner_col, altitude]

Return type:

Tuple

shareloc.geofunctions.rectification.get_epipolar_extent(left_im, geom_model_left, geom_model_right, elevation=0.0, epi_step=30.0, elevation_offset=50.0, grid_margin=0, additional_margin=0.0)

Return epipolar rectification grid footprint using reprojection of epipolar geometry in left image.

Parameters:

• left_im (shareloc.image object) – left image

• geom_model_left (GeomodelTemplate) – geometric model of the left image

• geom_model_right (GeomodelTemplate) – geometric model of the right image

• elevation (shareloc.dtm or float) – elevation

• epi_step (float) – epipolar step

• elevation_offset (float) – elevation difference used to estimate the local tangent

• grid_margin (int) – margin of the rectification grid (in grid pixels)

• additional_margin (float) – footprint margin (in degrees)

Returns:

[lon_min,lat_min,lon max,lat max] (2D np.array)

Return type:

numpy.array

shareloc.geofunctions.rectification.moving_along_axis(geom_model_left, geom_model_right, current_coords, spacing, elevation, epi_step, epi_angles, axis)

Moving to the next line in epipolar geometry

Parameters:

• geom_model_left (GeoModelTemplate) – geometric model of the left image

• geom_model_right (GeoModelTemplate) – geometric model of the right image

• current_coords (1D np.array [row, col, altitude] or 2D numpy array (number rows in epipolar geometry, [row, col, altitude])) – current line in the left epipolar geometry or current georeferenced coordinates in left epipolar line

• spacing (float) – image spacing along axis dimension (in general mean image spacing)

• elevation (shareloc.dtm or float) – elevation

• epi_step (int) – epipolar step

• epi_angles (np.ndarray) – epipolar angle

• axis (int) – displacement direction (0 = along columns, 1 = along lines)

Returns:

left and right positions in epipolar grid

Return type:

Tuple([row, col, altitude], [row, col, altitude]) or Tuple(2D numpy array (number rows in epipolar geometry, [row, col, altitude]), 2D numpy array (number rows in epipolar geometry, [row, col, altitude]))

shareloc.geofunctions.rectification.compute_strip_of_epipolar_grid(geom_model_left, geom_model_right, left_positions_point, right_positions_point, spacing, axis, strip_size, epi_step=1, elevation=0.0, elevation_offset=50.0, epipolar_angles=None)

Compute stereo-rectification epipolar grids by strip. We start with a starting positions_point, and optional already computed epipolar_angles at these points, and we move strip_size times along axis direction (0 = along columns, 1 = along lines) to compute a strip of epipolar grid. positions_points is a (rows,cols,3) array containing (rows,cols) 3D coordinates (row,col,alt). If axis==0 (resp. 1) rows (resp. cols) dimension must be 1.

Parameters:

• geom_model_left (GeomodelTemplate) – geometric model of the left image

• geom_model_right (GeomodelTemplate) – geometric model of the right image

• left_positions_point (np.ndarray) – array of size (rows,cols,3) containing positions for left points

• right_positions_point (np.ndarray) – array of size (rows,cols,3) containing positions for left points

• spacing (float) – image spacing along axis dimension (in general mean image spacing)

• axis (int) – displacement direction (0 = along columns, 1 = along lines)

• strip_size (int) – desired size of grid along one axis for strip generation

• epi_step (int) – epipolar grid sampling step

• elevation (shareloc.dtm or float) – elevation

• elevation_offset (float) – elevation difference used to estimate the local tangent

• epipolar_angles (np.ndarray) – 2D array (rows,cols) containing epipolar angles at each grid node (angle in between epipolar coordinate system and left image coordinate system), size must be coherent with positions_point 1st,2nd dim

Returns:

• left epipolar positions grid in shape (rows,cols,3) rows (resp. cols) is strip_size if axis = 0 (resp. 1)

• right epipolar positions grid in shape (rows,cols,3) rows (resp. cols) is strip_size if axis = 0 (resp. 1)

• array of epipolar angles (rows,cols)

• mean baseline ratio of the strip computed on rows x cols elements minus provided epipolar angles shape,

  and number of NaNs in local epipolar lines computations. We consider that if epipolar angles are provided, then baseline ratio for these elements have been already computed.

• number of NaNs in mean baseline ratio

Return type:

Tuple

shareloc.geofunctions.rectification.init_inputs_rectification(left_im, geom_model_left, right_im, geom_model_right, elevation=0.0, epi_step=1.0, elevation_offset=50.0, margin=0)

Inputs rectification with its starting point, spacing, grid size, rectified_image size. spacing is defined as mean pixel size of input image. :param left_im: left image :type left_im: shareloc Image object :param geom_model_left: geometric model of the left image :type geom_model_left: GeoModelTemplate :param right_im: right image (not used, be still here for API symmetry) :type right_im: shareloc Image object :param geom_model_right: geometric model of the right image :type geom_model_right: GeoModelTemplate :param elevation: elevation :type elevation: DTMIntersection or float :param epi_step: epipolar step :type epi_step: float :param elevation_offset: elevation difference used to estimate the local tangent :type elevation_offset: float :param margin: margin of the rectification grid (in grid pixels) :type margin: int :return: returns a Tuple containing: - left starting point, np.ndarray of size (1,1,3) - right starting point, np.ndarray of size (1,1,3) - epipolar spacing, float - grid size, list [nb_row,nb_cols] - rectified image size, list [nb_row,nb_cols] :rtype: Tuple

Parameters:

• left_im (shareloc.image.Image)

• geom_model_left (shareloc.geomodels.geomodel_template.GeoModelTemplate)

• right_im (shareloc.image.Image)

• geom_model_right (shareloc.geomodels.geomodel_template.GeoModelTemplate)

• elevation (Union[float, shareloc.geofunctions.dtm_intersection.DTMIntersection])

• epi_step (float)

• elevation_offset (float)

• margin (int)

Return type:

Tuple[numpy.ndarray, numpy.ndarray, float, List[int], List[int]]

shareloc.geofunctions.rectification.positions_to_displacement_grid(left_grid, right_grid, epi_step)

Transform position grids to displacement grid :param left_grid: left epipolar positions grids :type left_grid: np.ndarray :param right_grid: right epipolar positions grids :type right_grid: np.ndarray :param epi_step: epipolar step :type epi_step: float :return: - left epipolar displacement grid, np.ndarray - right epipolar displacement grid, np.ndarray - transform, Affine :rtype: Tuple(np.ndarray, np.ndarray, Affine)

Parameters:

• left_grid (numpy.ndarray)

• right_grid (numpy.ndarray)

• epi_step (float)

Return type:

Tuple[numpy.ndarray, numpy.ndarray, affine.Affine]

shareloc.geofunctions.rectification.compute_stereorectification_epipolar_grids(left_im, geom_model_left, right_im, geom_model_right, elevation=0.0, epi_step=1.0, elevation_offset=50.0, as_displacement_grid=False, margin=0)

Compute stereo-rectification epipolar grids. Rectification scheme is composed of : - rectification grid initialisation - compute first grid row (one vertical strip by moving along rows) - compute all columns (one horizontal strip along columns) - transform position to displacement grid

Parameters:

• left_im (shareloc Image object) – left image

• geom_model_left (GeoModelTemplate) – geometric model of the left image

• right_im (shareloc Image object) – right image

• geom_model_right (GeoModelTemplate) – geometric model of the right image

• elevation (DTMIntersection or float) – elevation

• epi_step (float) – epipolar step

• elevation_offset (float) – elevation difference used to estimate the local tangent

• as_displacement_grid (bool) – False: generates localisation grids, True: displacement grids

• margin (int) – margin to add to the grid

Returns:

Returns left and right epipolar displacement/localisation grid, epipolar image size, mean of base to height ratio and geotransfrom of the grid in a tuple containing : - left epipolar grid, np.ndarray object with size (nb_rows,nb_cols,3): [nb rows, nb cols, [row displacement, col displacement, alt]] if as_displacement_grid is True [nb rows, nb cols, [row localisation, col localisation, alt]] if as_displacement_grid is False - right epipolar grid, np.ndarray object with size (nb_rows,nb_cols,3) : [nb rows, nb cols, [row displacement, col displacement, alt]] if as_displacement_grid is True [nb rows, nb cols, [row localisation, col localisation, alt]] if as_displacement_grid is False - size of epipolar image, [nb_rows,nb_cols] - mean value of the baseline to sensor altitude ratio, float - epipolar grid geotransform, Affine

Return type:

Tuple(np.ndarray, np.ndarray, List[int], float, Affine)