shareloc.geofunctions.rectification

This module contains functions to generate stereo-rectification epipolar grids

Module Contents

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 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 :

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)

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

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, margin=0.0)

return epipolar 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

• 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.

  We consider that if epipolar angles are provided, then baseline ratio for these elements have been already computed.

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)

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 :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) –

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)

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

Returns:

Returns left and right epipolar displacement 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]] - right epipolar grid, np.ndarray object with size (nb_rows,nb_cols,3) : [nb rows, nb cols, [row displacement, col displacement, alt]] - 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)