shareloc.geofunctions.rectification =================================== .. py:module:: shareloc.geofunctions.rectification .. autoapi-nested-parse:: This module contains functions to generate stereo-rectification epipolar grids Functions --------- .. autoapisummary:: shareloc.geofunctions.rectification.write_epipolar_grid shareloc.geofunctions.rectification.compute_epipolar_angle shareloc.geofunctions.rectification.compute_local_epipolar_line shareloc.geofunctions.rectification.prepare_rectification shareloc.geofunctions.rectification.get_epipolar_extent shareloc.geofunctions.rectification.moving_along_axis shareloc.geofunctions.rectification.compute_strip_of_epipolar_grid shareloc.geofunctions.rectification.init_inputs_rectification shareloc.geofunctions.rectification.positions_to_displacement_grid shareloc.geofunctions.rectification.compute_stereorectification_epipolar_grids Module Contents --------------- .. py:function:: write_epipolar_grid(grid, filename, geotransform, xy_convention = True) Write epipolar grid in a tiff file :param grid: epipolar grid (row,col,3) :type grid: np.ndarray :param filename: output filename :type filename: str :param geotransform: grid geotransform :type geotransform: Affine :param xy_convention: 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] :param xy_convention: bool .. py:function:: compute_epipolar_angle(end_line, start_line) Define the epipolar angle :param end_line: ending of the epipolar line (georeferenced coordinates) :type end_line: 1D np.array [row, col, altitude] or 2D np.array [number of points, [row, col, altitude]] :param start_line: beginning of the epipolar line (georeferenced coordinates) :type start_line: 1D np.array [row, col, altitude] or 2D np.array [number of points, [row, col, altitude]] :return: epipolar angle :rtype: float or 1D np.array .. py:function:: 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 :param geom_model_left: geometric model of the left image :type geom_model_left: GeomodelTemplate :param geom_model_right: geometric model of the right image :type geom_model_right: GeomodelTemplate :param left_point: georeferenced coordinates in the left image :type left_point: 1D numpy array : [row coord, col coord, altitude] or 2D numpy array : (number of points, [row coord, col coord, altitude]) :param elevation: elevation :type elevation: shareloc.dtm or float :param elevation_offset: elevation difference used to estimate the local tangent :type elevation_offset: float :return: Coordinates of the beginning and the ending of local epipolar line in the left image :rtype: 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])) .. py:function:: 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) :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 geom_model_right: geometric model of the right image :type geom_model_right: GeomodelTemplate :param elevation: elevation :type elevation: shareloc.dtm or float :param epi_step: epipolar step :type epi_step: int :param elevation_offset: elevation difference used to estimate the local tangent :type elevation_offset: int :param margin: margin of the rectification grid (in grid pixels) :type margin: int :return: - 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] :rtype: Tuple .. py:function:: 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. :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 geom_model_right: geometric model of the right image :type geom_model_right: GeomodelTemplate :param elevation: elevation :type elevation: shareloc.dtm 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 grid_margin: margin of the rectification grid (in grid pixels) :type grid_margin: int :param additional_margin: footprint margin (in degrees) :type additional_margin: float :return: [lon_min,lat_min,lon max,lat max] (2D np.array) :rtype: numpy.array .. py:function:: 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 :param geom_model_left: geometric model of the left image :type geom_model_left: GeoModelTemplate :param geom_model_right: geometric model of the right image :type geom_model_right: GeoModelTemplate :param current_coords: current line in the left epipolar geometry or current georeferenced coordinates in left epipolar line :type current_coords: 1D np.array [row, col, altitude] or 2D numpy array (number rows in epipolar geometry, [row, col, altitude]) :param spacing: image spacing along axis dimension (in general mean image spacing) :type spacing: float :param elevation: elevation :type elevation: shareloc.dtm or float :param epi_step: epipolar step :type epi_step: int :param epi_angles: epipolar angle :type epi_angles: np.ndarray :param axis: displacement direction (0 = along columns, 1 = along lines) :type axis: int :return: left and right positions in epipolar grid :rtype: 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])) .. py:function:: 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. :param geom_model_left: geometric model of the left image :type geom_model_left: GeomodelTemplate :param geom_model_right: geometric model of the right image :type geom_model_right: GeomodelTemplate :param left_positions_point: array of size (rows,cols,3) containing positions for left points :type left_positions_point: np.ndarray :param right_positions_point: array of size (rows,cols,3) containing positions for left points :type right_positions_point: np.ndarray :param spacing: image spacing along axis dimension (in general mean image spacing) :type spacing: float :param axis: displacement direction (0 = along columns, 1 = along lines) :type axis: int :param strip_size: desired size of grid along one axis for strip generation :type strip_size: int :param epi_step: epipolar grid sampling step :type epi_step: int :param elevation: elevation :type elevation: shareloc.dtm or float :param elevation_offset: elevation difference used to estimate the local tangent :type elevation_offset: float :param epipolar_angles: 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 :type epipolar_angles: np.ndarray :param margin: margin of the rectification grid (in grid pixels) :type margin: int :return: - 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. :rtype: Tuple .. py:function:: 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 .. py:function:: 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) .. py:function:: 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 :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 :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 as_displacement_grid: False: generates localisation grids, True: displacement grids :type as_displacement_grid: bool :return: 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 :rtype: Tuple(np.ndarray, np.ndarray, List[int], float, Affine)