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 :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, 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 :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 :param margin: margin to add to the grid :type margin: int :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)