arosics package

Submodules

arosics.CoReg module

class arosics.CoReg.COREG(im_ref, im_tgt, path_out=None, fmt_out='ENVI', out_crea_options=None, r_b4match=1, s_b4match=1, wp=(None, None), ws=(256, 256), max_iter=5, max_shift=5, align_grids=False, match_gsd=False, out_gsd=None, target_xyGrid=None, resamp_alg_deshift='cubic', resamp_alg_calc='cubic', footprint_poly_ref=None, footprint_poly_tgt=None, data_corners_ref=None, data_corners_tgt=None, nodata=(None, None), calc_corners=True, binary_ws=True, mask_baddata_ref=None, mask_baddata_tgt=None, CPUs=None, force_quadratic_win=True, progress=True, v=False, path_verbose_out=None, q=False, ignore_errors=False)

Bases: object

The COREG class detects and corrects global X/Y shifts between a target and reference image.

Geometric shifts are calculated at a specific (adjustable) image position. Correction performs a global shifting in X- or Y direction.

See help(COREG) for documentation!

Get an instance of the COREG class.

Parameters

• im_ref (Union[GeoArray, str]) – source path or GeoArray instance of reference image (any GDAL compatible image format is supported)

• im_tgt (Union[GeoArray, str]) – source path or GeoArray instance of the target image, i.e., the image to be shifted (any GDAL compatible image format is supported)

• path_out (str) – target path of the coregistered image - if None (default), the method correct_shifts() does not write to disk - if ‘auto’: /dir/of/im1/<im1>__shifted_to__<im0>.bsq

• fmt_out (str) – raster file format for output file. ignored if path_out is None. can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI). Refer to https://gdal.org/drivers/raster/index.html to get a full list of supported formats.

• out_crea_options (list) – GDAL creation options for the output image, e.g. [“QUALITY=80”, “REVERSIBLE=YES”, “WRITE_METADATA=YES”]

• r_b4match (int) – band of reference image to be used for matching (starts with 1; default: 1)

• s_b4match (int) – band of shift image to be used for matching (starts with 1; default: 1)

• wp (Tuple[float, float]) – custom matching window position as (X, Y) map coordinate in the same projection like the reference image (default: central position of image overlap)

• ws (Tuple[int, int]) – custom matching window size [pixels] as (X, Y) tuple (default: (256,256))

• max_iter (int) – maximum number of iterations for matching (default: 5)

• max_shift (int) – maximum shift distance in reference image pixel units (default: 5 px)

• align_grids (bool) –

  True: align the input coordinate grid to the reference (does not affect the output pixel size as long as input and output pixel sizes are compatible (5:30 or 10:30 but not 4:30), default = False

  • NOTE: If this is set to False, the mis-registration in the target image is corrected by updating its geocoding information only, i.e., without performing any resampling which preserves the original image values (except that a resampling is needed due to other reasons, e.g., if ‘match_gsd’, ‘out_gsd’ or ‘target_xyGrid’ are given).

• match_gsd (bool) – True: match the input pixel size to the reference pixel size, default = False

• out_gsd (Tuple[float]) – output pixel size (X/Y) in units of the reference coordinate system (default = pixel size of the target image), given values are overridden by match_gsd=True

• target_xyGrid (List[List]) – a list with a target x-grid and a target y-grid like [[15,45], [15,45]] This overrides ‘out_gsd’, ‘align_grids’ and ‘match_gsd’.

• resamp_alg_deshift (str) – the resampling algorithm to be used for shift correction (if neccessary) - valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 - default: cubic

• resamp_alg_calc (str) – the resampling algorithm to be used for all warping processes during calculatio of spatial shift - valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 - default: cubic (highly recommended)

• footprint_poly_ref (str) – footprint polygon of the reference image (WKT string or shapely.geometry.Polygon), e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• footprint_poly_tgt (str) – footprint polygon of the image to be shifted (WKT string or shapely.geometry.Polygon) e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• data_corners_ref (list) – map coordinates of data corners within reference image. ignored if footprint_poly_ref is given.

• data_corners_tgt (list) – map coordinates of data corners within image to be shifted. ignored if footprint_poly_tgt is given.

• nodata (Tuple) – no-data values for reference image and image to be shifted. The default is (None, None) which indicates that there is no specific no-data value for both of the input images.

• calc_corners (bool) – calculate true positions of the dataset corners in order to get a useful matching window position within the actual image overlap (default: True; deactivated if ‘-cor0’ and ‘-cor1’ are given

• binary_ws (bool) – use binary X/Y dimensions for the matching window (default: True)

• mask_baddata_ref (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of GeoArray) for the reference image where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• mask_baddata_tgt (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of GeoArray) for the image to be shifted where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• CPUs (int) – number of CPUs to use during pixel grid equalization (default: None, which means ‘all CPUs available’)

• force_quadratic_win (bool) – force a quadratic matching window (default: True)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• path_verbose_out (str) – an optional output directory for intermediate results (if not given, no intermediate results are written to disk)

• q (bool) – quiet mode (default: False)

• ignore_errors (bool) – Useful for batch processing. (default: False) In case of error COREG.success == False and COREG.x_shift_px/COREG.y_shift_px is None

_calc_integer_shifts(scps)

Return type

(int, int)

_calc_shift_reliability(scps)

Calculate a confidence percentage to be used as an assessment for reliability of the calculated shifts.

Parameters

scps (ndarray) – shifted cross power spectrum

Returns

_calc_shifted_cross_power_spectrum(im0=None, im1=None, precision=<class 'numpy.complex64'>)

Calculate the shifted cross power spectrum for quantifying X/Y-shifts.

Parameters

• im0 – reference image

• im1 – subject image to shift

• precision – to be quantified as a datatype

Return type

ndarray

Returns

2D-numpy-array of the shifted cross power spectrum

_calc_subpixel_shifts(scps)

_check_and_handle_metaRotation()

Check if the provided input data have a metadata rotation and if yes, correct it.

In case there is a rotation, the GDAL GeoTransform is not 0 at positions 2 or 4. So far, AROSICS does not handle such rotations, so the resampling is needed to make things work.

static _clip_image(im, center_YX, winSzYX)

_find_side_maximum(scps)

_get_clip_window_properties()

Calculate all properties of the matching window and the other window.

These windows are used to read the corresponding image positions in the reference and the target image.

NOTE: Even if X- and Y-dimension of the target window is equal, the output window can be NON-quadratic!

Return type

None

_get_deshifted_otherWin()

Return a de-shifted version of self.otherWin as a GeoArray instance.

The output dimensions and geographic bounds are equal to those of self.matchWin and geometric shifts are corrected according to the previously computed X/Y shifts within the matching window. This allows direct application of algorithms e.g. measuring image similarity.

The image subset that is resampled in this function is always the same that has been resampled during computation of geometric shifts (usually the image with the higher geometric resolution).

Return type

GeoArray

Returns

GeoArray instance of de-shifted self.otherWin

_get_grossly_deshifted_images(im0, im1, x_intshift, y_intshift)

_get_image_params()

Return type

None

_get_image_windows_to_match()

Read the matching window and the other window as subsets.

The other window is resampled to the resolution and the pixel grid of the matching window. The result consists of two images with the same dimensions and exactly the same corner coordinates.

Return type

None

_get_inverted_coreg_info()

Return an inverted dictionary of coreg_info.

This dictionary can be passed to DESHIFTER in order to fit the REFERENCE image onto the TARGET image.

Return type

dict

_get_opt_winpos_winsize()

Calculate optimal window position and size in reference image units.

NOTE: The returned values are computed according to DGM, cloud_mask and trueCornerLonLat.

Return type

None

_get_overlap_properties()

Return type

None

static _get_peakpos(scps)

Return the row/column position of the peak within the given cross power spectrum.

Parameters

scps (ndarray) – shifted cross power spectrum

Return type

ndarray

Returns

[row, column]

static _get_shifts_from_peakpos(peakpos, arr_shape)

Return type

(float, float)

static _get_total_shifts(x_intshift, y_intshift, x_subshift, y_subshift)

_get_updated_map_info()

Return type

None

_handle_error(error, warn=False, warnMsg=None)

Append the given error to self.tracked_errors.

This sets self.success to False and raises the error in case self.ignore_errors = True.

Parameters

• error – instance of an error

• warn – whether to give a warning in case error would be ignored otherwise

• warnMsg – a custom message for the warning

Returns

_set_outpathes(im_ref, im_tgt)

Return type

None

static _shrink_winsize_to_binarySize(win_shape_YX, target_size=None)

Shrink a given window size to the closest binary window size (a power of 2).

NOTE: X- and Y-dimension are handled separately.

Parameters

• win_shape_YX (tuple) – source window shape as pixel units (rows,colums)

• target_size (tuple) – source window shape as pixel units (rows,colums)

Return type

Optional[Tuple[int, int]]

_validate_integer_shifts(im0, im1, x_intshift, y_intshift)

_validate_ssim_improvement(v=False)

Compute mean structural similarity index between reference and target image before and after co-registration.

Parameters

v (bool) – verbose mode: shows images of the matchWin, otherWin and shifted version of otherWin

Return type

(float, float)

Returns

SSIM before an after shift correction

property are_pixGrids_equal

calculate_spatial_shifts()

Compute the global X/Y shift between reference and the target image within the matching window.

Return type

str

Returns

‘success’ or ‘fail’

property coreg_info: dict

Return a dictionary containing everything to correct the detected global X/Y shift of the target image.

correct_shifts()

Correct the already calculated X/Y shift of the target image.

Return type

dict

Returns

COREG.deshift_results (dictionary)

equalize_pixGrids()

Equalize image grids and projections of reference and target image (align target to reference).

NOTE: This method is only called by COREG_LOCAL to speed up processing during detection of displacements.

Return type

None

show_cross_power_spectrum(interactive=False)

Show a 3D surface of the cross power spectrum.

NOTE: The cross power spectrum is the result from phase correlating the reference and target

image within the matching window.

Parameters

interactive (bool) – whether to return an interactice 3D surface plot based on ‘plotly’ library

Return type

None

Returns

show_image_footprints()

Show a web map containing the calculated footprints and overlap area of the input images.

NOTE: This method is intended to be called from Jupyter Notebook.

show_matchWin(figsize=(15, 15), interactive=True, after_correction=None, pmin=2, pmax=98)

Show the image content within the matching window.

Parameters

• figsize (tuple) – figure size

• interactive (bool) – whether to return an interactive figure based on ‘holoviews’ library

• after_correction (bool) – True/False: show the image content AFTER shift correction or before None: show both states - before and after correction (default)

• pmin – percentage to be used for excluding the darkest pixels from stretching (default: 2)

• pmax – percentage to be used for excluding the brightest pixels from stretching (default: 98)

Returns

property ssim_improved: bool

Return True if image similarity within the matching window has been improved by co-registration.

class arosics.CoReg.GeoArray_CoReg(CoReg_params, imID)

Bases: GeoArray

Get an instance of GeoArray.

Parameters

• path_or_array – a numpy.ndarray or a valid file path

• geotransform – GDAL geotransform of the given array or file on disk

• projection – projection of the given array or file on disk as WKT string (only needed if GeoArray is instanced with an array)

• bandnames – names of the bands within the input array, e.g. [‘mask_1bit’, ‘mask_clouds’], (default: [‘B1’, ‘B2’, ‘B3’, …])

• nodata – nodata value

• basename – a short base name of the dataset (e.g., used in some status messages)

• progress – show progress bars (default: True)

• q – quiet mode (default: False)

property poly

arosics.CoReg_local module

class arosics.CoReg_local.COREG_LOCAL(im_ref, im_tgt, grid_res, max_points=None, window_size=(256, 256), path_out=None, fmt_out='ENVI', out_crea_options=None, projectDir=None, r_b4match=1, s_b4match=1, max_iter=5, max_shift=5, tieP_filter_level=3, min_reliability=60, rs_max_outlier=10, rs_tolerance=2.5, rs_random_state=0, align_grids=True, match_gsd=False, out_gsd=None, target_xyGrid=None, resamp_alg_deshift='cubic', resamp_alg_calc='cubic', footprint_poly_ref=None, footprint_poly_tgt=None, data_corners_ref=None, data_corners_tgt=None, outFillVal=-9999, nodata=(None, None), calc_corners=True, binary_ws=True, force_quadratic_win=True, mask_baddata_ref=None, mask_baddata_tgt=None, CPUs=None, progress=True, v=False, q=False, ignore_errors=True)

Bases: object

COREG_LOCAL applies the algorithm to detect spatial shifts to the whole overlap area of the input images.

Spatial shifts are calculated for each point in grid of which the parameters can be adjusted using keyword arguments. Shift correction performs a polynomial transformation using the calculated shifts of each point in the grid as GCPs. Thus this class can be used to correct for locally varying geometric distortions of the target image.

See help(COREG_LOCAL) for documentation.

Get an instance of COREG_LOCAL.

Parameters

• im_ref (Union[GeoArray, str]) – source path of reference image (any GDAL compatible image format is supported)

• im_tgt (Union[GeoArray, str]) – source path of image to be shifted (any GDAL compatible image format is supported)

• grid_res (float) – tie point grid resolution in pixels of the target image (x-direction)

• max_points (int) –

  maximum number of points used to find coregistration tie points

  NOTE: Points are selected randomly from the given point grid (specified by ‘grid_res’).

  If the point grid does not provide enough points, all available points are chosen.

• window_size (Tuple[int, int]) – custom matching window size [pixels] (default: (256,256))

• path_out (str) – target path of the coregistered image - if None (default), no output is written to disk - if ‘auto’: /dir/of/im1/<im1>__shifted_to__<im0>.bsq

• fmt_out (str) – raster file format for output file. ignored if path_out is None. Can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI). Refer to https://gdal.org/drivers/raster/index.html to get a full list of supported formats.

• out_crea_options (list) – GDAL creation options for the output image, e.g. [“QUALITY=80”, “REVERSIBLE=YES”, “WRITE_METADATA=YES”]

• projectDir (str) – name of a project directory where to store all the output results. If given, name is inserted into all automatically generated output paths.

• r_b4match (int) – band of reference image to be used for matching (starts with 1; default: 1)

• s_b4match (int) – band of shift image to be used for matching (starts with 1; default: 1)

• max_iter (int) – maximum number of iterations for matching (default: 5)

• max_shift (int) – maximum shift distance in reference image pixel units (default: 5 px)

• tieP_filter_level (int) –

  filter tie points used for shift correction in different levels (default: 3). NOTE: lower levels are also included if a higher level is chosen

  • Level 0: no tie point filtering

  • Level 1: Reliablity filtering

    • filter all tie points out that have a low reliability according to internal tests

  • Level 2: SSIM filtering

    • filters all tie points out where shift correction does not increase image similarity within matching window (measured by mean structural similarity index)

  • Level 3: RANSAC outlier detection

• min_reliability (float) – Tie point filtering: minimum reliability threshold, below which tie points are marked as false-positives (default: 60%) - accepts values between 0% (no reliability) and 100 % (perfect reliability) HINT: decrease this value in case of poor signal-to-noise ratio of your input data

• rs_max_outlier (float) – RANSAC tie point filtering: proportion of expected outliers (default: 10%)

• rs_tolerance (float) – RANSAC tie point filtering: percentage tolerance for max_outlier_percentage (default: 2.5%)

• rs_random_state (Optional[int]) – RANSAC random state (an integer corresponds to a fixed/pseudo-random state, None randomizes the result)

• align_grids (bool) – True: align the input coordinate grid to the reference (does not affect the output pixel size as long as input and output pixel sizes are compatible (5:30 or 10:30 but not 4:30), default = True

• match_gsd (bool) – True: match the input pixel size to the reference pixel size, default = False

• out_gsd (float) – output pixel size in units of the reference coordinate system (default = pixel size of the input array), given values are overridden by match_gsd=True

• target_xyGrid – a list with a target x-grid and a target y-grid like [[15,45], [15,45]] This overrides ‘out_gsd’, ‘align_grids’ and ‘match_gsd’.

• resamp_alg_deshift (str) – the resampling algorithm to be used for shift correction (if neccessary) valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 (default: cubic)

• resamp_alg_calc (str) – the resampling algorithm to be used for all warping processes during calculation of spatial shifts valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 (default: cubic (highly recommended))

• footprint_poly_ref (str) – footprint polygon of the reference image (WKT string or shapely.geometry.Polygon), e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• footprint_poly_tgt (str) – footprint polygon of the image to be shifted (WKT string or shapely.geometry.Polygon) e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• data_corners_ref (list) – map coordinates of data corners within reference image. ignored if footprint_poly_ref is given.

• data_corners_tgt (list) – map coordinates of data corners within image to be shifted. ignored if footprint_poly_tgt is given.

• outFillVal (int) – if given the generated tie point grid is filled with this value in case no match could be found during co-registration (default: -9999)

• nodata (Tuple[int, int]) – no data values for reference image and image to be shifted

• calc_corners (bool) – calculate true positions of the dataset corners in order to get a useful matching window position within the actual image overlap (default: True; deactivated if ‘data_corners_im0’ and ‘data_corners_im1’ are given)

• binary_ws (bool) – use binary X/Y dimensions for the matching window (default: True)

• force_quadratic_win (bool) – force a quadratic matching window (default: True)

• mask_baddata_ref (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of BadDataMask) for the reference image where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• mask_baddata_tgt (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of BadDataMask) for the image to be shifted where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• CPUs (int) – number of CPUs to use during calculation of tie point grid (default: None, which means ‘all CPUs available’)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• q (bool) – quiet mode (default: False)

• ignore_errors (bool) – Useful for batch processing. (default: False)

property CoRegPoints_table: GeoDataFrame

Return a GeoDataFrame containing all the results from coregistration for all points in the tie point grid.

Columns of the GeoDataFrame: ‘geometry’,’POINT_ID’,’X_IM’,’Y_IM’,’X_MAP’,’Y_MAP’,’X_WIN_SIZE’, ‘Y_WIN_SIZE’,

‘X_SHIFT_PX’,’Y_SHIFT_PX’, ‘X_SHIFT_M’, ‘Y_SHIFT_M’, ‘ABS_SHIFT’ and ‘ANGLE’

_check_and_handle_metaRotation()

Check if the provided input data have a metadata rotation and if yes, correct it AND equalize grids.

In case there is a rotation, the GDAL GeoTransform is not 0 at positions 2 or 4. So far, AROSICS does not handle such rotations, so the resampling is needed to make things work. The pixel grid equalization is also done here to avoid a double-resampling (grid would be equalized by COREG.equalize_pixGrids() otherwise).

_get_updated_map_info_meanShifts()

Return the updated map info of the target image, shifted on the basis of the mean X/Y shifts.

Return type

list

calculate_spatial_shifts()

Return type

None

check_if_fftw_works()

Assign the attribute ‘fftw_works’ to self.COREG_obj by executing shift calculation once with muted output.

Return type

None

property coreg_info: dict

Return a dictionary containing everthing to correct the detected local displacements of the target image.

correct_shifts(max_GCP_count=None, cliptoextent=False, min_points_local_corr=5)

Perform a local shift correction using all points from the previously calculated tie point grid.

NOTE: Only valid matches are used as GCP points.

Parameters

• max_GCP_count (int) – maximum number of GCPs to use

• cliptoextent (bool) – whether to clip the output image to its real extent

• min_points_local_corr (int) – number of valid tie points, below which a global shift correction is performed instead of a local correction (global X/Y shift is then computed as the mean shift of the remaining points)(default: 5 tie points)

Return type

OrderedDict

Returns

property projectDir: str

show_image_footprints()

Show a web map containing the calculated footprints and overlap area of the input images.

NOTE: This method is intended to be called from Jupyter Notebook.

property success: bool

property tiepoint_grid: Tie_Point_Grid

view_CoRegPoints(shapes2plot='points', attribute2plot='ABS_SHIFT', cmap=None, exclude_fillVals=True, backgroundIm='tgt', hide_filtered=True, figsize=None, figsize_multiplier=1, title='', vector_scale=1.0, savefigPath='', savefigDPI=96, showFig=True, vmin=None, vmax=None, return_map=False)

Show a map of the calculated tie point grid with the target image as background.

Parameters

• shapes2plot (str) – ‘points’: plot points representing values of ‘attribute2plot’ onto the map ‘vectors’: plot shift vectors onto the map

• attribute2plot (str) – the attribute of the tie point grid to be shown (default: ‘ABS_SHIFT’)

• cmap (<module 'matplotlib.cm' from '/opt/conda/envs/ci_env/lib/python3.11/site-packages/matplotlib/cm.py'>) – a custom color map to be applied to the plotted grid points (default: ‘RdYlGn_r’)

• exclude_fillVals (bool) – whether to exclude those points of the grid where spatial shift detection failed

• backgroundIm (str) – whether to use the target or the reference image as map background. Possible options are ‘ref’ and ‘tgt’ (default: ‘tgt’)

• hide_filtered (bool) – hide all points that have been filtered out according to tie point filter level

• figsize (tuple) – size of the figure to be viewed, e.g. (10, 10); automatically estimated if not given

• figsize_multiplier (float) – if given, the figure size is multiplied with this value

• title (str) – plot title

• vector_scale (float) – scale factor for shift vector length (default: 1 -> no scaling)

• savefigPath (str) – path where to save the figure

• savefigDPI (int) – DPI resolution of the output figure when saved to disk (default: 96)

• showFig (bool) – whether to show or to hide the figure (default: True)

• vmin (float) – minimum value of ‘attribute2plot’ to be included in the figure

• vmax (float) – maximum value of ‘attribute2plot’ to be included in the figure

• return_map (bool) – whether to return the figure and axis objects (default: False)

Return type

Optional[Tuple]

Returns

tuple of figure and axis objects or None in case return_map is set to False

view_CoRegPoints_folium(attribute2plot='ABS_SHIFT')

arosics.DeShifter module

class arosics.DeShifter.DESHIFTER(im2shift, coreg_results, **kwargs)

Bases: object

Class to deshift an image array or one of its products by applying previously the computed coregistration info.

See help(DESHIFTER) for documentation.

Get an instance of DESHIFTER.

Parameters

• im2shift (Union[GeoArray, str]) – path of an image to be de-shifted or alternatively a GeoArray object

• coreg_results (dict) – the results of the co-registration as given by COREG.coreg_info or COREG_LOCAL.coreg_info

• path_out (int) – /output/directory/filename for coregistered results

• fmt_out (str) – raster file format for output file. ignored if path_out is None. can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI)

• out_crea_options (list) – GDAL creation options for the output image, e.g., [“QUALITY=20”, “REVERSIBLE=YES”, “WRITE_METADATA=YES”]

• band2process (int) – The index of the band to be processed within the given array (starts with 1), default = None (all bands are processed)

• nodata (float) – no data value of the image to be de-shifted

• out_gsd (float) – output pixel size in units of the reference coordinate system (default = pixel size of the input array), given values are overridden by match_gsd=True

• align_grids (bool) – True: align the input coordinate grid to the reference (does not affect the output pixel size as long as input and output pixel sizes are compatible (5:30 or 10:30 but not 4:30), default = False

• match_gsd (bool) – True: match the input pixel size to the reference pixel size, default = False

• target_xyGrid (list) – a list with an x-grid and a y-grid like [[15,45], [15,45]]. This overrides ‘out_gsd’, ‘align_grids’ and ‘match_gsd’.

• min_points_local_corr (int) – number of valid tie points, below which a global shift correction is performed instead of a local correction (global X/Y shift is then computed as the mean shift of the remaining points) (default: 5 tie points)

• resamp_alg (str) – the resampling algorithm to be used if neccessary (valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3)

• cliptoextent (bool) – True: clip the input image to its actual bounds while deleting possible no data areas outside of the actual bounds, default = False

• clipextent (list) – xmin, ymin, xmax, ymax - if given the calculation of the actual bounds is skipped. The given coordinates are automatically snapped to the output grid.

• CPUs (int) – number of CPUs to use (default: None, which means ‘all CPUs available’)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• q (bool) – quiet mode (default: False)

_are_grids_alignable(in_xgsd, in_ygsd, out_xgsd, out_ygsd)

Check if the input image pixel grid is alignable to the output grid.

Parameters

• in_xgsd –

• in_ygsd –

• out_xgsd –

• out_ygsd –

Returns

_get_out_extent()

_get_out_grid()

correct_shifts()

Return type

OrderedDict

property deshift_results

property warping_needed

Return True if image warping is needed in consideration of the input parameters of DESHIFTER.

arosics.DeShifter.deshift_image_using_coreg_info(im2shift, coreg_results, path_out=None, fmt_out='ENVI', q=False)

Correct a geometrically distorted image using previously calculated coregistration info.

This function can be used for example to correct spatial shifts of mask files using the same transformation parameters that have been used to correct their source images.

Parameters

• im2shift (Union[GeoArray, str]) – path of an image to be de-shifted or alternatively a GeoArray object

• coreg_results (dict) – the results of the co-registration as given by COREG.coreg_info or COREG_LOCAL.coreg_info respectively

• path_out (str) – /output/directory/filename for coregistered results. If None, no output is written - only the shift corrected results are returned.

• fmt_out (str) – raster file format for output file. ignored if path_out is None. can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI)

• q (bool) – quiet mode (default: False)

Returns

arosics.Tie_Point_Grid module

class arosics.Tie_Point_Grid.Tie_Point_Grid(COREG_obj, grid_res, max_points=None, outFillVal=-9999, resamp_alg_calc='cubic', tieP_filter_level=3, outlDetect_settings=None, dir_out=None, CPUs=None, progress=True, v=False, q=False)

Bases: object

The ‘Tie_Point_Grid’ class applies the algorithm to detect spatial shifts to the overlap area of the input images.

Spatial shifts are calculated for each point in grid of which the parameters can be adjusted using keyword arguments. Shift correction performs a polynomial transformation using te calculated shifts of each point in the grid as GCPs. Thus, ‘Tie_Point_Grid’ can be used to correct for locally varying geometric distortions of the target image.

See help(Tie_Point_Grid) for documentation!

Get an instance of the ‘Tie_Point_Grid’ class.

Parameters

• COREG_obj (COREG) – an instance of COREG class

• grid_res (float) – grid resolution in pixels of the target image (x-direction)

• max_points (int) –

  maximum number of points used to find coregistration tie points

  NOTE: Points are selected randomly from the given point grid (specified by ‘grid_res’). If the point does not provide enough points, all available points are chosen.

• outFillVal (int) – if given the generated tie points grid is filled with this value in case no match could be found during co-registration (default: -9999)

• resamp_alg_calc (str) – the resampling algorithm to be used for all warping processes during calculation of spatial shifts (valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3) default: cubic (highly recommended)

• tieP_filter_level (int) –

  filter tie points used for shift correction in different levels (default: 3). NOTE: lower levels are also included if a higher level is chosen

  • Level 0: no tie point filtering

  • Level 1: Reliablity filtering

    • filter all tie points out that have a low reliability according to internal tests

  • Level 2: SSIM filtering

    • filters all tie points out where shift correction does not increase image similarity within matching window (measured by mean structural similarity index)

  • Level 3: RANSAC outlier detection

• outlDetect_settings (dict) – a dictionary with the settings to be passed to arosics.TiePointGrid.Tie_Point_Refiner. Available keys: min_reliability, rs_max_outlier, rs_tolerance, rs_max_iter, rs_exclude_previous_outliers, rs_timeout, rs_random_state, q. See documentation there.

• dir_out (str) – output directory to be used for all outputs if nothing else is given to the individual methods

• CPUs (int) – number of CPUs to use during calculation of tie points grid (default: None, which means ‘all CPUs available’)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• q (bool) – quiet mode (default: False)

property CoRegPoints_table

Return a GeoDataFrame containing all the results from coregistration for all points in the tie point grid.

Columns of the GeoDataFrame: ‘geometry’,’POINT_ID’,’X_IM’,’Y_IM’,’X_MAP’,’Y_MAP’,’X_WIN_SIZE’, ‘Y_WIN_SIZE’,

‘X_SHIFT_PX’,’Y_SHIFT_PX’, ‘X_SHIFT_M’, ‘Y_SHIFT_M’, ‘ABS_SHIFT’ and ‘ANGLE’

property GCPList

Return a list of GDAL compatible GCP objects.

_exclude_bad_XYpos(GDF)

Exclude all points outside of the image overlap area and where the bad data mask is True (if given).

Parameters

GDF – <geopandas.GeoDataFrame> must include the columns ‘X_MAP’ and ‘Y_MAP’

Returns

_get_coreg_kwargs(pID, wp)

_get_imXY__mapXY_points(grid_res)

Return a numpy array containing possible positions for coregistration tie points.

NOTE: The returned positions are dependent from the given grid resolution.

Parameters

grid_res –

Returns

_get_line_by_PID(PID)

_get_lines_by_PIDs(PIDs)

static _get_spatial_shifts(coreg_kwargs)

_to_PointShapefile(skip_nodata=True, skip_nodata_col='ABS_SHIFT')

calc_overall_ssim(include_outliers=False, after_correction=True)

Calculate the median value of all SSIM values contained in tie point grid.

Parameters

• include_outliers (bool) – whether to include tie points that have been marked as false-positives

• after_correction (bool) – whether to compute median SSIM before correction or after

Return type

float

calc_overall_stats(include_outliers=False)

Calculate statistics like RMSE, MSE, MAE, … from the tie point grid.

Full list of returned statistics:

• N_TP: number of tie points

• N_VALID_TP: number of valid tie points

• N_INVALID_TP: number of invalid tie points (false-positives)

• PERC_VALID_TP: percentage of valid tie points

• RMSE_M: root mean squared error of absolute shift vector length in map units

• RMSE_X_M: root mean squared error of shift vector length in x-direction in map units

• RMSE_Y_M: root mean squared error of shift vector length in y-direction in map units

• RMSE_X_PX: root mean squared error of shift vector length in x-direction in pixel units

• RMSE_Y_PX: root mean squared error of shift vector length in y-direction in pixel units

• MSE_M: mean squared error of absolute shift vector length in map units

• MSE_X_M: mean squared error of shift vector length in x-direction in map units

• MSE_Y_M: mean squared error of shift vector length in y-direction in map units

• MSE_X_PX: mean squared error of shift vector length in x-direction in pixel units

• MSE_Y_PX: mean squared error of shift vector length in y-direction in pixel units

• MAE_M: mean absolute error of absolute shift vector length in map units

• MAE_X_M: mean absolute error of shift vector length in x-direction in map units

• MAE_Y_M: mean absolute error of shift vector length in y-direction in map units

• MAE_X_PX: mean absolute error of shift vector length in x-direction in pixel units

• MAE_Y_PX: mean absolute error of shift vector length in y-direction in pixel units

• MEAN_ABS_SHIFT: mean absolute shift vector length in map units

• MEAN_X_SHIFT_M: mean shift vector length in x-direction in map units

• MEAN_Y_SHIFT_M: mean shift vector length in y-direction in map units

• MEAN_X_SHIFT_PX: mean shift vector length in x-direction in pixel units

• MEAN_Y_SHIFT_PX: mean shift vector length in y-direction in pixel units

• MEAN_ANGLE: mean direction of the shift vectors in degrees from north

• MEAN_SSIM_BEFORE: mean structural similatity index within each matching window before co-registration

• MEAN_SSIM_AFTER: mean structural similatity index within each matching window after co-registration

• MEAN_RELIABILITY: mean tie point reliability in percent

• MEDIAN_ABS_SHIFT: median absolute shift vector length in map units

• MEDIAN_X_SHIFT_M: median shift vector length in x-direction in map units

• MEDIAN_Y_SHIFT_M: median shift vector length in y-direction in map units

• MEDIAN_X_SHIFT_PX: median shift vector length in x-direction in pixel units

• MEDIAN_Y_SHIFT_PX: median shift vector length in y-direction in pixel units

• MEDIAN_ANGLE: median direction of the shift vectors in degrees from north

• MEDIAN_SSIM_BEFORE: median structural similatity index within each matching window before co-registration

• MEDIAN_SSIM_AFTER: median structural similatity index within each matching window after co-registration

• MEDIAN_RELIABILITY: median tie point reliability in percent

• STD_ABS_SHIFT: standard deviation of absolute shift vector length in map units

• STD_X_SHIFT_M: standard deviation of shift vector length in x-direction in map units

• STD_Y_SHIFT_M: standard deviation of shift vector length in y-direction in map units

• STD_X_SHIFT_PX: standard deviation of shift vector length in x-direction in pixel units

• STD_Y_SHIFT_PX: standard deviation of shift vector length in y-direction in pixel units

• STD_ANGLE: standard deviation of direction of the shift vectors in degrees from north

• STD_SSIM_BEFORE: standard deviation of structural similatity index within each matching window before

  co-registration

• STD_SSIM_AFTER: standard deviation of structural similatity index within each matching window after

  co-registration

• STD_RELIABILITY: standard deviation of tie point reliability in percent

• MIN_ABS_SHIFT: minimal absolute shift vector length in map units

• MIN_X_SHIFT_M: minimal shift vector length in x-direction in map units

• MIN_Y_SHIFT_M: minimal shift vector length in y-direction in map units

• MIN_X_SHIFT_PX: minimal shift vector length in x-direction in pixel units

• MIN_Y_SHIFT_PX: minimal shift vector length in y-direction in pixel units

• MIN_ANGLE: minimal direction of the shift vectors in degrees from north

• MIN_SSIM_BEFORE: minimal structural similatity index within each matching window before co-registration

• MIN_SSIM_AFTER: minimal structural similatity index within each matching window after co-registration

• MIN_RELIABILITY: minimal tie point reliability in percent

• MIN_ABS_SHIFT: maximal absolute shift vector length in map units

• MAX_X_SHIFT_M: maximal shift vector length in x-direction in map units

• MAX_Y_SHIFT_M: maximal shift vector length in y-direction in map units

• MAX_X_SHIFT_PX: maximal shift vector length in x-direction in pixel units

• MAX_Y_SHIFT_PX: maximal shift vector length in y-direction in pixel units

• MAX_ANGLE: maximal direction of the shift vectors in degrees from north

• MAX_SSIM_BEFORE: maximal structural similatity index within each matching window before co-registration

• MAX_SSIM_AFTER: maximal structural similatity index within each matching window after co-registration

• MAX_RELIABILITY: maximal tie point reliability in percent

Parameters

include_outliers (bool) – whether to include tie points that have been marked as false-positives (if present)

Return type

dict

calc_rmse(include_outliers=False)

Calculate root mean square error of absolute shifts from the tie point grid.

Parameters

include_outliers (bool) – whether to include tie points that have been marked as false-positives (if present)

Return type

float

dump_CoRegPoints_table(path_out=None)

get_CoRegPoints_table()

property mean_x_shift_map

property mean_x_shift_px

property mean_y_shift_map

property mean_y_shift_px

plot_shift_distribution(include_outliers=True, unit='m', interactive=False, figsize=None, xlim=None, ylim=None, fontsize=12, title='shift distribution', savefigPath='', savefigDPI=96, showFig=True, return_fig=False)

Create a 2D scatterplot containing the distribution of calculated X/Y-shifts.

Parameters

• include_outliers (bool) – whether to include tie points that have been marked as false-positives

• unit (str) – ‘m’ for meters or ‘px’ for pixels (default: ‘m’)

• interactive (bool) – whether to use interactive mode (uses plotly for visualization)

• figsize (tuple) – (xdim, ydim)

• xlim (list) – [xmin, xmax]

• ylim (list) – [ymin, ymax]

• fontsize (int) – size of all used fonts

• title (str) – the title to be plotted above the figure

• savefigPath (str) – path where to save the figure

• savefigDPI (int) – DPI resolution of the output figure when saved to disk

• showFig (bool) – whether to show or to hide the figure

• return_fig (bool) – whether to return the figure and axis objects

Return type

tuple

test_if_singleprocessing_equals_multiprocessing_result()

to_GCPList()

to_PointShapefile(path_out=None, skip_nodata=True, skip_nodata_col='ABS_SHIFT')

Write the calculated tie point grid to a point shapefile (e.g., for visualization by a GIS software).

NOTE: The shapefile uses Tie_Point_Grid.CoRegPoints_table as attribute table.

Parameters

• path_out (str) – <str> the output path. If not given, it is automatically defined.

• skip_nodata (bool) – <bool> whether to skip all points where no valid match could be found

• skip_nodata_col (str) – <str> determines which column of Tie_Point_Grid.CoRegPoints_table is used to identify points where no valid match could be found

Return type

None

static to_Raster_using_Kriging(*args, **kwargs)

to_interpolated_raster(metric='ABS_SHIFT', method='RBF', plot_result=False, lowres_spacing=5, v=False)

Interpolate the point data of the given metric into space.

Parameters

• metric (str) – metric name to interpolate, i.e., one of the column names of Tie_Point_Grid.CoRegPoints_table, e.g., ‘ABS_SHIFT’.

• method (str) – interpolation algorithm - ‘RBF’ (Radial Basis Function) - ‘GPR’ (Gaussian Process Regression; equivalent to Simple Kriging) - ‘Kriging’ (Ordinary Kriging based on pykrige)

• plot_result (bool) – plot the result to assess the interpolation quality

• lowres_spacing (int) – by default, RBF, GPR, and Kriging run a lower resolution which is then linearly interpolated to the full output image resolution. lowres_spacing defines the number of pixels between the low resolution grid points (higher values are faster but less accurate, default: 5)

• v (bool) – enable verbose mode

Return type

ndarray

Returns

interpolation result as numpy array in the X/Y dimension of the target image of the co-registration

to_vectorfield(path_out=None, fmt=None, mode='md')

Save the calculated X-/Y-shifts to a 2-band raster file that can be used to visualize a vectorfield.

NOTE: For example ArcGIS is able to visualize such 2-band raster files as a vectorfield.

Parameters

• path_out (str) – the output path. If not given, it is automatically defined.

• fmt (str) – output raster format string

• mode (str) – The mode how the output is written (‘uv’ or ‘md’; default: ‘md’) - ‘uv’: outputs X-/Y shifts - ‘md’: outputs magnitude and direction

Return type

GeoArray

class arosics.Tie_Point_Grid.Tie_Point_Grid_Interpolator(tiepointgrid, v=False)

Bases: object

Class to interpolate tie point data into space.

Get an instance of Tie_Point_Grid_Interpolator.

Parameters

• tiepointgrid (Tie_Point_Grid) – instance of Tie_Point_Grid after computing spatial shifts

• v (bool) – enable verbose mode

_get_pointdata(metric)

Get the point data for the given metric from Tie_Point_Grid.CoRegPoints_table while ignoring outliers.

static _interpolate_regulargrid(rows, cols, data, rows_full, cols_full)

Run linear regular grid interpolation.

static _interpolate_via_gpr(rows, cols, data, rows_full, cols_full)

Run Gaussian Process Regression (GPR) interpolation.

-> https://stackoverflow.com/questions/24978052/interpolation-over-regular-grid-in-python

static _interpolate_via_kriging(rows, cols, data, rows_full, cols_full)

Run Ordinary Kriging interpolation based on pykrige.

Reference: P.K. Kitanidis, Introduction to Geostatistics: Applications in Hydrogeology,

(Cambridge University Press, 1997) 272 p.

static _interpolate_via_rbf(rows, cols, data, rows_full, cols_full)

Run Radial Basis Function (RBF) interpolation.

-> https://github.com/agile-geoscience/xlines/blob/master/notebooks/11_Gridding_map_data.ipynb -> documents the legacy scipy.interpolate.Rbf

static _plot_interpolation_result(data_full, rows, cols, data, metric)

Plot the interpolation result together with the input point data.

interpolate(metric, method='RBF', plot_result=False, lowres_spacing=5)

Interpolate the point data of the given metric into space.

Parameters

• metric (str) – metric name to interpolate, i.e., one of the column names of Tie_Point_Grid.CoRegPoints_table, e.g., ‘ABS_SHIFT’.

• method (str) – interpolation algorithm - ‘RBF’ (Radial Basis Function) - ‘GPR’ (Gaussian Process Regression; equivalent to Simple Kriging) - ‘Kriging’ (Ordinary Kriging based on pykrige)

• plot_result (bool) – plot the result to assess the interpolation quality

• lowres_spacing (int) – by default, RBF, GPR, and Kriging run a lower resolution which is then linearly interpolated to the full output image resolution. lowres_spacing defines the number of pixels between the low resolution grid points (higher values are faster but less accurate, default: 5)

Return type

array

Returns

interpolation result as numpy array in the X/Y dimension of the target image of the co-registration

class arosics.Tie_Point_Grid.Tie_Point_Refiner(GDF, min_reliability=60, rs_max_outlier=10, rs_tolerance=2.5, rs_max_iter=15, rs_exclude_previous_outliers=True, rs_timeout=20, rs_random_state=0, q=False)

Bases: object

A class for performing outlier detection.

Get an instance of Tie_Point_Refiner.

Parameters

• GDF – GeoDataFrame like TiePointGrid.CoRegPoints_table containing all tie points to be filtered and the corresponding metadata

• min_reliability – minimum threshold for previously computed tie X/Y shift reliability (default: 60%)

• rs_max_outlier (float) – RANSAC: maximum percentage of outliers to be detected (default: 10%)

• rs_tolerance (float) – RANSAC: percentage tolerance for max_outlier_percentage (default: 2.5%)

• rs_max_iter (int) – RANSAC: maximum iterations for finding the best RANSAC threshold (default: 15)

• rs_exclude_previous_outliers (bool) – RANSAC: whether to exclude points that have been flagged as outlier by earlier filtering (default:True)

• rs_timeout (float) – RANSAC: timeout for iteration loop in seconds (default: 20)

• rs_random_state (Optional[int]) – RANSAC random state (an integer corresponds to a fixed/pseudo-random state, None randomizes the result)

• q (bool) –

_RANSAC_outlier_detection(inGDF)

Detect geometric outliers between point cloud of source and estimated coordinates using RANSAC algorithm.

_SSIM_filtering()

Exclude all records where SSIM decreased.

_reliability_thresholding()

Exclude all records where estimated reliability of the calculated shifts is below the given threshold.

run_filtering(level=3)

Filter tie points used for shift correction.

Parameters

level –

tie point filter level (default: 3). NOTE: lower levels are also included if a higher level is chosen

• Level 0: no tie point filtering

• Level 1: Reliablity filtering

  • filter all tie points out that have a low reliability according to internal tests

• Level 2: SSIM filtering

  • filters all tie points out where shift correction does not increase image similarity within matching window (measured by mean structural similarity index)

• Level 3: RANSAC outlier detection

Returns

arosics.Tie_Point_Grid.mp_initializer(imref, imtgt)

Declare global variables needed for self._get_spatial_shifts().

Parameters

• imref – reference image

• imtgt – target image

arosics.arosics_cli module

arosics.arosics_cli.get_arosics_argparser()

Return argument parser for arosics console command.

arosics.arosics_cli.main()

arosics.arosics_cli.run_global_coreg(args)

arosics.arosics_cli.run_local_coreg(args)

arosics.geometry module

arosics.geometry.angle_to_north(XY)

Calculate the angle in degrees of a given line to north in clockwise direction.

Angle definition: between [origin:[0,0],north:[0,1]] and [origin:[0,0],pointXY:[X,Y]].

arosics.geometry.get_GeoArrayPosition_from_boxImYX(boxImYX)

Return row_start,row_end,col_start,col_end and assumes boxImYX as [UL_YX,UR_YX,LR_YX,LL_YX).

arosics.geometry.get_gdalReadInputs_from_boxImYX(boxImYX)

Return row_start,col_start,rows_count,cols_count and assumes boxImYX as [UL_YX,UR_YX,LR_YX,LL_YX).

arosics.geometry.get_subset_GeoTransform(gt_fullArr, subset_box_imYX)

arosics.geometry.get_true_corner_mapXY(fPath_or_geoarray, band=0, noDataVal=None, mp=1, v=0, q=0)

Return the actual map corner coordinates of a given image file or GeoArray instance.

Parameters

• fPath_or_geoarray –

• band – <int> index of the band to be used (starting with 0)

• noDataVal –

• mp –

• v –

• q –

Returns

arosics.geometry.has_metaRotation(path_or_geoarray)

Return True if there is a row or column rotation due to the given GDAL GeoTransform tuple.

arosics.geometry.remove_metaRotation(gA_rot, rspAlg='cubic')

Remove any metadata rotation (a rotation that only exists in the map info).

Return type

GeoArray

arosics.plotting module

arosics.plotting._norm(array, normto)

arosics.plotting.subplot_2dline(XY_tuples, titles=None, shapetuple=None, grid=False)

arosics.plotting.subplot_3dsurface(ims, shapetuple=None)

arosics.plotting.subplot_imshow(ims, titles=None, shapetuple=None, grid=False)

arosics.version module

Module contents

Top-level package for arosics.

class arosics.COREG(im_ref, im_tgt, path_out=None, fmt_out='ENVI', out_crea_options=None, r_b4match=1, s_b4match=1, wp=(None, None), ws=(256, 256), max_iter=5, max_shift=5, align_grids=False, match_gsd=False, out_gsd=None, target_xyGrid=None, resamp_alg_deshift='cubic', resamp_alg_calc='cubic', footprint_poly_ref=None, footprint_poly_tgt=None, data_corners_ref=None, data_corners_tgt=None, nodata=(None, None), calc_corners=True, binary_ws=True, mask_baddata_ref=None, mask_baddata_tgt=None, CPUs=None, force_quadratic_win=True, progress=True, v=False, path_verbose_out=None, q=False, ignore_errors=False)

Bases: object

The COREG class detects and corrects global X/Y shifts between a target and reference image.

Geometric shifts are calculated at a specific (adjustable) image position. Correction performs a global shifting in X- or Y direction.

See help(COREG) for documentation!

Get an instance of the COREG class.

Parameters

• im_ref (Union[GeoArray, str]) – source path or GeoArray instance of reference image (any GDAL compatible image format is supported)

• im_tgt (Union[GeoArray, str]) – source path or GeoArray instance of the target image, i.e., the image to be shifted (any GDAL compatible image format is supported)

• path_out (str) – target path of the coregistered image - if None (default), the method correct_shifts() does not write to disk - if ‘auto’: /dir/of/im1/<im1>__shifted_to__<im0>.bsq

• fmt_out (str) – raster file format for output file. ignored if path_out is None. can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI). Refer to https://gdal.org/drivers/raster/index.html to get a full list of supported formats.

• out_crea_options (list) – GDAL creation options for the output image, e.g. [“QUALITY=80”, “REVERSIBLE=YES”, “WRITE_METADATA=YES”]

• r_b4match (int) – band of reference image to be used for matching (starts with 1; default: 1)

• s_b4match (int) – band of shift image to be used for matching (starts with 1; default: 1)

• wp (Tuple[float, float]) – custom matching window position as (X, Y) map coordinate in the same projection like the reference image (default: central position of image overlap)

• ws (Tuple[int, int]) – custom matching window size [pixels] as (X, Y) tuple (default: (256,256))

• max_iter (int) – maximum number of iterations for matching (default: 5)

• max_shift (int) – maximum shift distance in reference image pixel units (default: 5 px)

• align_grids (bool) –

  True: align the input coordinate grid to the reference (does not affect the output pixel size as long as input and output pixel sizes are compatible (5:30 or 10:30 but not 4:30), default = False

  • NOTE: If this is set to False, the mis-registration in the target image is corrected by updating its geocoding information only, i.e., without performing any resampling which preserves the original image values (except that a resampling is needed due to other reasons, e.g., if ‘match_gsd’, ‘out_gsd’ or ‘target_xyGrid’ are given).

• match_gsd (bool) – True: match the input pixel size to the reference pixel size, default = False

• out_gsd (Tuple[float]) – output pixel size (X/Y) in units of the reference coordinate system (default = pixel size of the target image), given values are overridden by match_gsd=True

• target_xyGrid (List[List]) – a list with a target x-grid and a target y-grid like [[15,45], [15,45]] This overrides ‘out_gsd’, ‘align_grids’ and ‘match_gsd’.

• resamp_alg_deshift (str) – the resampling algorithm to be used for shift correction (if neccessary) - valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 - default: cubic

• resamp_alg_calc (str) – the resampling algorithm to be used for all warping processes during calculatio of spatial shift - valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 - default: cubic (highly recommended)

• footprint_poly_ref (str) – footprint polygon of the reference image (WKT string or shapely.geometry.Polygon), e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• footprint_poly_tgt (str) – footprint polygon of the image to be shifted (WKT string or shapely.geometry.Polygon) e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• data_corners_ref (list) – map coordinates of data corners within reference image. ignored if footprint_poly_ref is given.

• data_corners_tgt (list) – map coordinates of data corners within image to be shifted. ignored if footprint_poly_tgt is given.

• nodata (Tuple) – no-data values for reference image and image to be shifted. The default is (None, None) which indicates that there is no specific no-data value for both of the input images.

• calc_corners (bool) – calculate true positions of the dataset corners in order to get a useful matching window position within the actual image overlap (default: True; deactivated if ‘-cor0’ and ‘-cor1’ are given

• binary_ws (bool) – use binary X/Y dimensions for the matching window (default: True)

• mask_baddata_ref (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of GeoArray) for the reference image where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• mask_baddata_tgt (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of GeoArray) for the image to be shifted where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• CPUs (int) – number of CPUs to use during pixel grid equalization (default: None, which means ‘all CPUs available’)

• force_quadratic_win (bool) – force a quadratic matching window (default: True)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• path_verbose_out (str) – an optional output directory for intermediate results (if not given, no intermediate results are written to disk)

• q (bool) – quiet mode (default: False)

• ignore_errors (bool) – Useful for batch processing. (default: False) In case of error COREG.success == False and COREG.x_shift_px/COREG.y_shift_px is None

_calc_integer_shifts(scps)

Return type

(int, int)

_calc_shift_reliability(scps)

Calculate a confidence percentage to be used as an assessment for reliability of the calculated shifts.

Parameters

scps (ndarray) – shifted cross power spectrum

Returns

_calc_shifted_cross_power_spectrum(im0=None, im1=None, precision=<class 'numpy.complex64'>)

Calculate the shifted cross power spectrum for quantifying X/Y-shifts.

Parameters

• im0 – reference image

• im1 – subject image to shift

• precision – to be quantified as a datatype

Return type

ndarray

Returns

2D-numpy-array of the shifted cross power spectrum

_calc_subpixel_shifts(scps)

_check_and_handle_metaRotation()

Check if the provided input data have a metadata rotation and if yes, correct it.

In case there is a rotation, the GDAL GeoTransform is not 0 at positions 2 or 4. So far, AROSICS does not handle such rotations, so the resampling is needed to make things work.

static _clip_image(im, center_YX, winSzYX)

_find_side_maximum(scps)

_get_clip_window_properties()

Calculate all properties of the matching window and the other window.

These windows are used to read the corresponding image positions in the reference and the target image.

NOTE: Even if X- and Y-dimension of the target window is equal, the output window can be NON-quadratic!

Return type

None

_get_deshifted_otherWin()

Return a de-shifted version of self.otherWin as a GeoArray instance.

The output dimensions and geographic bounds are equal to those of self.matchWin and geometric shifts are corrected according to the previously computed X/Y shifts within the matching window. This allows direct application of algorithms e.g. measuring image similarity.

The image subset that is resampled in this function is always the same that has been resampled during computation of geometric shifts (usually the image with the higher geometric resolution).

Return type

GeoArray

Returns

GeoArray instance of de-shifted self.otherWin

_get_grossly_deshifted_images(im0, im1, x_intshift, y_intshift)

_get_image_params()

Return type

None

_get_image_windows_to_match()

Read the matching window and the other window as subsets.

The other window is resampled to the resolution and the pixel grid of the matching window. The result consists of two images with the same dimensions and exactly the same corner coordinates.

Return type

None

_get_inverted_coreg_info()

Return an inverted dictionary of coreg_info.

This dictionary can be passed to DESHIFTER in order to fit the REFERENCE image onto the TARGET image.

Return type

dict

_get_opt_winpos_winsize()

Calculate optimal window position and size in reference image units.

NOTE: The returned values are computed according to DGM, cloud_mask and trueCornerLonLat.

Return type

None

_get_overlap_properties()

Return type

None

static _get_peakpos(scps)

Return the row/column position of the peak within the given cross power spectrum.

Parameters

scps (ndarray) – shifted cross power spectrum

Return type

ndarray

Returns

[row, column]

static _get_shifts_from_peakpos(peakpos, arr_shape)

Return type

(float, float)

static _get_total_shifts(x_intshift, y_intshift, x_subshift, y_subshift)

_get_updated_map_info()

Return type

None

_handle_error(error, warn=False, warnMsg=None)

Append the given error to self.tracked_errors.

This sets self.success to False and raises the error in case self.ignore_errors = True.

Parameters

• error – instance of an error

• warn – whether to give a warning in case error would be ignored otherwise

• warnMsg – a custom message for the warning

Returns

_set_outpathes(im_ref, im_tgt)

Return type

None

static _shrink_winsize_to_binarySize(win_shape_YX, target_size=None)

Shrink a given window size to the closest binary window size (a power of 2).

NOTE: X- and Y-dimension are handled separately.

Parameters

• win_shape_YX (tuple) – source window shape as pixel units (rows,colums)

• target_size (tuple) – source window shape as pixel units (rows,colums)

Return type

Optional[Tuple[int, int]]

_validate_integer_shifts(im0, im1, x_intshift, y_intshift)

_validate_ssim_improvement(v=False)

Compute mean structural similarity index between reference and target image before and after co-registration.

Parameters

v (bool) – verbose mode: shows images of the matchWin, otherWin and shifted version of otherWin

Return type

(float, float)

Returns

SSIM before an after shift correction

property are_pixGrids_equal

calculate_spatial_shifts()

Compute the global X/Y shift between reference and the target image within the matching window.

Return type

str

Returns

‘success’ or ‘fail’

property coreg_info: dict

Return a dictionary containing everything to correct the detected global X/Y shift of the target image.

correct_shifts()

Correct the already calculated X/Y shift of the target image.

Return type

dict

Returns

COREG.deshift_results (dictionary)

equalize_pixGrids()

Equalize image grids and projections of reference and target image (align target to reference).

NOTE: This method is only called by COREG_LOCAL to speed up processing during detection of displacements.

Return type

None

show_cross_power_spectrum(interactive=False)

Show a 3D surface of the cross power spectrum.

NOTE: The cross power spectrum is the result from phase correlating the reference and target

image within the matching window.

Parameters

interactive (bool) – whether to return an interactice 3D surface plot based on ‘plotly’ library

Return type

None

Returns

show_image_footprints()

Show a web map containing the calculated footprints and overlap area of the input images.

NOTE: This method is intended to be called from Jupyter Notebook.

show_matchWin(figsize=(15, 15), interactive=True, after_correction=None, pmin=2, pmax=98)

Show the image content within the matching window.

Parameters

• figsize (tuple) – figure size

• interactive (bool) – whether to return an interactive figure based on ‘holoviews’ library

• after_correction (bool) – True/False: show the image content AFTER shift correction or before None: show both states - before and after correction (default)

• pmin – percentage to be used for excluding the darkest pixels from stretching (default: 2)

• pmax – percentage to be used for excluding the brightest pixels from stretching (default: 98)

Returns

property ssim_improved: bool

Return True if image similarity within the matching window has been improved by co-registration.

class arosics.COREG_LOCAL(im_ref, im_tgt, grid_res, max_points=None, window_size=(256, 256), path_out=None, fmt_out='ENVI', out_crea_options=None, projectDir=None, r_b4match=1, s_b4match=1, max_iter=5, max_shift=5, tieP_filter_level=3, min_reliability=60, rs_max_outlier=10, rs_tolerance=2.5, rs_random_state=0, align_grids=True, match_gsd=False, out_gsd=None, target_xyGrid=None, resamp_alg_deshift='cubic', resamp_alg_calc='cubic', footprint_poly_ref=None, footprint_poly_tgt=None, data_corners_ref=None, data_corners_tgt=None, outFillVal=-9999, nodata=(None, None), calc_corners=True, binary_ws=True, force_quadratic_win=True, mask_baddata_ref=None, mask_baddata_tgt=None, CPUs=None, progress=True, v=False, q=False, ignore_errors=True)

Bases: object

COREG_LOCAL applies the algorithm to detect spatial shifts to the whole overlap area of the input images.

Spatial shifts are calculated for each point in grid of which the parameters can be adjusted using keyword arguments. Shift correction performs a polynomial transformation using the calculated shifts of each point in the grid as GCPs. Thus this class can be used to correct for locally varying geometric distortions of the target image.

See help(COREG_LOCAL) for documentation.

Get an instance of COREG_LOCAL.

Parameters

• im_ref (Union[GeoArray, str]) – source path of reference image (any GDAL compatible image format is supported)

• im_tgt (Union[GeoArray, str]) – source path of image to be shifted (any GDAL compatible image format is supported)

• grid_res (float) – tie point grid resolution in pixels of the target image (x-direction)

• max_points (int) –

  maximum number of points used to find coregistration tie points

  NOTE: Points are selected randomly from the given point grid (specified by ‘grid_res’).

  If the point grid does not provide enough points, all available points are chosen.

• window_size (Tuple[int, int]) – custom matching window size [pixels] (default: (256,256))

• path_out (str) – target path of the coregistered image - if None (default), no output is written to disk - if ‘auto’: /dir/of/im1/<im1>__shifted_to__<im0>.bsq

• fmt_out (str) – raster file format for output file. ignored if path_out is None. Can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI). Refer to https://gdal.org/drivers/raster/index.html to get a full list of supported formats.

• out_crea_options (list) – GDAL creation options for the output image, e.g. [“QUALITY=80”, “REVERSIBLE=YES”, “WRITE_METADATA=YES”]

• projectDir (str) – name of a project directory where to store all the output results. If given, name is inserted into all automatically generated output paths.

• r_b4match (int) – band of reference image to be used for matching (starts with 1; default: 1)

• s_b4match (int) – band of shift image to be used for matching (starts with 1; default: 1)

• max_iter (int) – maximum number of iterations for matching (default: 5)

• max_shift (int) – maximum shift distance in reference image pixel units (default: 5 px)

• tieP_filter_level (int) –

  filter tie points used for shift correction in different levels (default: 3). NOTE: lower levels are also included if a higher level is chosen

  • Level 0: no tie point filtering

  • Level 1: Reliablity filtering

    • filter all tie points out that have a low reliability according to internal tests

  • Level 2: SSIM filtering

    • filters all tie points out where shift correction does not increase image similarity within matching window (measured by mean structural similarity index)

  • Level 3: RANSAC outlier detection

• min_reliability (float) – Tie point filtering: minimum reliability threshold, below which tie points are marked as false-positives (default: 60%) - accepts values between 0% (no reliability) and 100 % (perfect reliability) HINT: decrease this value in case of poor signal-to-noise ratio of your input data

• rs_max_outlier (float) – RANSAC tie point filtering: proportion of expected outliers (default: 10%)

• rs_tolerance (float) – RANSAC tie point filtering: percentage tolerance for max_outlier_percentage (default: 2.5%)

• rs_random_state (Optional[int]) – RANSAC random state (an integer corresponds to a fixed/pseudo-random state, None randomizes the result)

• align_grids (bool) – True: align the input coordinate grid to the reference (does not affect the output pixel size as long as input and output pixel sizes are compatible (5:30 or 10:30 but not 4:30), default = True

• match_gsd (bool) – True: match the input pixel size to the reference pixel size, default = False

• out_gsd (float) – output pixel size in units of the reference coordinate system (default = pixel size of the input array), given values are overridden by match_gsd=True

• target_xyGrid – a list with a target x-grid and a target y-grid like [[15,45], [15,45]] This overrides ‘out_gsd’, ‘align_grids’ and ‘match_gsd’.

• resamp_alg_deshift (str) – the resampling algorithm to be used for shift correction (if neccessary) valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 (default: cubic)

• resamp_alg_calc (str) – the resampling algorithm to be used for all warping processes during calculation of spatial shifts valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3 (default: cubic (highly recommended))

• footprint_poly_ref (str) – footprint polygon of the reference image (WKT string or shapely.geometry.Polygon), e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• footprint_poly_tgt (str) – footprint polygon of the image to be shifted (WKT string or shapely.geometry.Polygon) e.g. ‘POLYGON ((299999 6000000, 299999 5890200, 409799 5890200, 409799 6000000, 299999 6000000))’

• data_corners_ref (list) – map coordinates of data corners within reference image. ignored if footprint_poly_ref is given.

• data_corners_tgt (list) – map coordinates of data corners within image to be shifted. ignored if footprint_poly_tgt is given.

• outFillVal (int) – if given the generated tie point grid is filled with this value in case no match could be found during co-registration (default: -9999)

• nodata (Tuple[int, int]) – no data values for reference image and image to be shifted

• calc_corners (bool) – calculate true positions of the dataset corners in order to get a useful matching window position within the actual image overlap (default: True; deactivated if ‘data_corners_im0’ and ‘data_corners_im1’ are given)

• binary_ws (bool) – use binary X/Y dimensions for the matching window (default: True)

• force_quadratic_win (bool) – force a quadratic matching window (default: True)

• mask_baddata_ref (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of BadDataMask) for the reference image where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• mask_baddata_tgt (Union[GeoArray, str]) – path to a 2D boolean mask file (or an instance of BadDataMask) for the image to be shifted where all bad data pixels (e.g. clouds) are marked with True and the remaining pixels with False. Must have the same geographic extent and projection like ‘im_ref’. The mask is used to check if the chosen matching window position is valid in the sense of useful data. Otherwise this window position is rejected.

• CPUs (int) – number of CPUs to use during calculation of tie point grid (default: None, which means ‘all CPUs available’)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• q (bool) – quiet mode (default: False)

• ignore_errors (bool) – Useful for batch processing. (default: False)

property CoRegPoints_table: GeoDataFrame

Return a GeoDataFrame containing all the results from coregistration for all points in the tie point grid.

Columns of the GeoDataFrame: ‘geometry’,’POINT_ID’,’X_IM’,’Y_IM’,’X_MAP’,’Y_MAP’,’X_WIN_SIZE’, ‘Y_WIN_SIZE’,

‘X_SHIFT_PX’,’Y_SHIFT_PX’, ‘X_SHIFT_M’, ‘Y_SHIFT_M’, ‘ABS_SHIFT’ and ‘ANGLE’

_check_and_handle_metaRotation()

Check if the provided input data have a metadata rotation and if yes, correct it AND equalize grids.

In case there is a rotation, the GDAL GeoTransform is not 0 at positions 2 or 4. So far, AROSICS does not handle such rotations, so the resampling is needed to make things work. The pixel grid equalization is also done here to avoid a double-resampling (grid would be equalized by COREG.equalize_pixGrids() otherwise).

_get_updated_map_info_meanShifts()

Return the updated map info of the target image, shifted on the basis of the mean X/Y shifts.

Return type

list

calculate_spatial_shifts()

Return type

None

check_if_fftw_works()

Assign the attribute ‘fftw_works’ to self.COREG_obj by executing shift calculation once with muted output.

Return type

None

property coreg_info: dict

Return a dictionary containing everthing to correct the detected local displacements of the target image.

correct_shifts(max_GCP_count=None, cliptoextent=False, min_points_local_corr=5)

Perform a local shift correction using all points from the previously calculated tie point grid.

NOTE: Only valid matches are used as GCP points.

Parameters

• max_GCP_count (int) – maximum number of GCPs to use

• cliptoextent (bool) – whether to clip the output image to its real extent

• min_points_local_corr (int) – number of valid tie points, below which a global shift correction is performed instead of a local correction (global X/Y shift is then computed as the mean shift of the remaining points)(default: 5 tie points)

Return type

OrderedDict

Returns

property projectDir: str

show_image_footprints()

Show a web map containing the calculated footprints and overlap area of the input images.

NOTE: This method is intended to be called from Jupyter Notebook.

property success: bool

property tiepoint_grid: Tie_Point_Grid

view_CoRegPoints(shapes2plot='points', attribute2plot='ABS_SHIFT', cmap=None, exclude_fillVals=True, backgroundIm='tgt', hide_filtered=True, figsize=None, figsize_multiplier=1, title='', vector_scale=1.0, savefigPath='', savefigDPI=96, showFig=True, vmin=None, vmax=None, return_map=False)

Show a map of the calculated tie point grid with the target image as background.

Parameters

• shapes2plot (str) – ‘points’: plot points representing values of ‘attribute2plot’ onto the map ‘vectors’: plot shift vectors onto the map

• attribute2plot (str) – the attribute of the tie point grid to be shown (default: ‘ABS_SHIFT’)

• cmap (<module 'matplotlib.cm' from '/opt/conda/envs/ci_env/lib/python3.11/site-packages/matplotlib/cm.py'>) – a custom color map to be applied to the plotted grid points (default: ‘RdYlGn_r’)

• exclude_fillVals (bool) – whether to exclude those points of the grid where spatial shift detection failed

• backgroundIm (str) – whether to use the target or the reference image as map background. Possible options are ‘ref’ and ‘tgt’ (default: ‘tgt’)

• hide_filtered (bool) – hide all points that have been filtered out according to tie point filter level

• figsize (tuple) – size of the figure to be viewed, e.g. (10, 10); automatically estimated if not given

• figsize_multiplier (float) – if given, the figure size is multiplied with this value

• title (str) – plot title

• vector_scale (float) – scale factor for shift vector length (default: 1 -> no scaling)

• savefigPath (str) – path where to save the figure

• savefigDPI (int) – DPI resolution of the output figure when saved to disk (default: 96)

• showFig (bool) – whether to show or to hide the figure (default: True)

• vmin (float) – minimum value of ‘attribute2plot’ to be included in the figure

• vmax (float) – maximum value of ‘attribute2plot’ to be included in the figure

• return_map (bool) – whether to return the figure and axis objects (default: False)

Return type

Optional[Tuple]

Returns

tuple of figure and axis objects or None in case return_map is set to False

view_CoRegPoints_folium(attribute2plot='ABS_SHIFT')

class arosics.DESHIFTER(im2shift, coreg_results, **kwargs)

Bases: object

Class to deshift an image array or one of its products by applying previously the computed coregistration info.

See help(DESHIFTER) for documentation.

Get an instance of DESHIFTER.

Parameters

• im2shift (Union[GeoArray, str]) – path of an image to be de-shifted or alternatively a GeoArray object

• coreg_results (dict) – the results of the co-registration as given by COREG.coreg_info or COREG_LOCAL.coreg_info

• path_out (int) – /output/directory/filename for coregistered results

• fmt_out (str) – raster file format for output file. ignored if path_out is None. can be any GDAL compatible raster file format (e.g. ‘ENVI’, ‘GTIFF’; default: ENVI)

• out_crea_options (list) – GDAL creation options for the output image, e.g., [“QUALITY=20”, “REVERSIBLE=YES”, “WRITE_METADATA=YES”]

• band2process (int) – The index of the band to be processed within the given array (starts with 1), default = None (all bands are processed)

• nodata (float) – no data value of the image to be de-shifted

• out_gsd (float) – output pixel size in units of the reference coordinate system (default = pixel size of the input array), given values are overridden by match_gsd=True

• align_grids (bool) – True: align the input coordinate grid to the reference (does not affect the output pixel size as long as input and output pixel sizes are compatible (5:30 or 10:30 but not 4:30), default = False

• match_gsd (bool) – True: match the input pixel size to the reference pixel size, default = False

• target_xyGrid (list) – a list with an x-grid and a y-grid like [[15,45], [15,45]]. This overrides ‘out_gsd’, ‘align_grids’ and ‘match_gsd’.

• min_points_local_corr (int) – number of valid tie points, below which a global shift correction is performed instead of a local correction (global X/Y shift is then computed as the mean shift of the remaining points) (default: 5 tie points)

• resamp_alg (str) – the resampling algorithm to be used if neccessary (valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3)

• cliptoextent (bool) – True: clip the input image to its actual bounds while deleting possible no data areas outside of the actual bounds, default = False

• clipextent (list) – xmin, ymin, xmax, ymax - if given the calculation of the actual bounds is skipped. The given coordinates are automatically snapped to the output grid.

• CPUs (int) – number of CPUs to use (default: None, which means ‘all CPUs available’)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• q (bool) – quiet mode (default: False)

_are_grids_alignable(in_xgsd, in_ygsd, out_xgsd, out_ygsd)

Check if the input image pixel grid is alignable to the output grid.

Parameters

• in_xgsd –

• in_ygsd –

• out_xgsd –

• out_ygsd –

Returns

_get_out_extent()

_get_out_grid()

correct_shifts()

Return type

OrderedDict

property deshift_results

property warping_needed

Return True if image warping is needed in consideration of the input parameters of DESHIFTER.

class arosics.Tie_Point_Grid(COREG_obj, grid_res, max_points=None, outFillVal=-9999, resamp_alg_calc='cubic', tieP_filter_level=3, outlDetect_settings=None, dir_out=None, CPUs=None, progress=True, v=False, q=False)

Bases: object

The ‘Tie_Point_Grid’ class applies the algorithm to detect spatial shifts to the overlap area of the input images.

Spatial shifts are calculated for each point in grid of which the parameters can be adjusted using keyword arguments. Shift correction performs a polynomial transformation using te calculated shifts of each point in the grid as GCPs. Thus, ‘Tie_Point_Grid’ can be used to correct for locally varying geometric distortions of the target image.

See help(Tie_Point_Grid) for documentation!

Get an instance of the ‘Tie_Point_Grid’ class.

Parameters

• COREG_obj (COREG) – an instance of COREG class

• grid_res (float) – grid resolution in pixels of the target image (x-direction)

• max_points (int) –

  maximum number of points used to find coregistration tie points

  NOTE: Points are selected randomly from the given point grid (specified by ‘grid_res’). If the point does not provide enough points, all available points are chosen.

• outFillVal (int) – if given the generated tie points grid is filled with this value in case no match could be found during co-registration (default: -9999)

• resamp_alg_calc (str) – the resampling algorithm to be used for all warping processes during calculation of spatial shifts (valid algorithms: nearest, bilinear, cubic, cubic_spline, lanczos, average, mode, max, min, med, q1, q3) default: cubic (highly recommended)

• tieP_filter_level (int) –

  filter tie points used for shift correction in different levels (default: 3). NOTE: lower levels are also included if a higher level is chosen

  • Level 0: no tie point filtering

  • Level 1: Reliablity filtering

    • filter all tie points out that have a low reliability according to internal tests

  • Level 2: SSIM filtering

    • filters all tie points out where shift correction does not increase image similarity within matching window (measured by mean structural similarity index)

  • Level 3: RANSAC outlier detection

• outlDetect_settings (dict) – a dictionary with the settings to be passed to arosics.TiePointGrid.Tie_Point_Refiner. Available keys: min_reliability, rs_max_outlier, rs_tolerance, rs_max_iter, rs_exclude_previous_outliers, rs_timeout, rs_random_state, q. See documentation there.

• dir_out (str) – output directory to be used for all outputs if nothing else is given to the individual methods

• CPUs (int) – number of CPUs to use during calculation of tie points grid (default: None, which means ‘all CPUs available’)

• progress (bool) – show progress bars (default: True)

• v (bool) – verbose mode (default: False)

• q (bool) – quiet mode (default: False)

property CoRegPoints_table

Return a GeoDataFrame containing all the results from coregistration for all points in the tie point grid.

Columns of the GeoDataFrame: ‘geometry’,’POINT_ID’,’X_IM’,’Y_IM’,’X_MAP’,’Y_MAP’,’X_WIN_SIZE’, ‘Y_WIN_SIZE’,

‘X_SHIFT_PX’,’Y_SHIFT_PX’, ‘X_SHIFT_M’, ‘Y_SHIFT_M’, ‘ABS_SHIFT’ and ‘ANGLE’

property GCPList

Return a list of GDAL compatible GCP objects.

_exclude_bad_XYpos(GDF)

Exclude all points outside of the image overlap area and where the bad data mask is True (if given).

Parameters

GDF – <geopandas.GeoDataFrame> must include the columns ‘X_MAP’ and ‘Y_MAP’

Returns

_get_coreg_kwargs(pID, wp)

_get_imXY__mapXY_points(grid_res)

Return a numpy array containing possible positions for coregistration tie points.

NOTE: The returned positions are dependent from the given grid resolution.

Parameters

grid_res –

Returns

_get_line_by_PID(PID)

_get_lines_by_PIDs(PIDs)

static _get_spatial_shifts(coreg_kwargs)

_to_PointShapefile(skip_nodata=True, skip_nodata_col='ABS_SHIFT')

calc_overall_ssim(include_outliers=False, after_correction=True)

Calculate the median value of all SSIM values contained in tie point grid.

Parameters

• include_outliers (bool) – whether to include tie points that have been marked as false-positives

• after_correction (bool) – whether to compute median SSIM before correction or after

Return type

float

calc_overall_stats(include_outliers=False)

Calculate statistics like RMSE, MSE, MAE, … from the tie point grid.

Full list of returned statistics:

• N_TP: number of tie points

• N_VALID_TP: number of valid tie points

• N_INVALID_TP: number of invalid tie points (false-positives)

• PERC_VALID_TP: percentage of valid tie points

• RMSE_M: root mean squared error of absolute shift vector length in map units

• RMSE_X_M: root mean squared error of shift vector length in x-direction in map units

• RMSE_Y_M: root mean squared error of shift vector length in y-direction in map units

• RMSE_X_PX: root mean squared error of shift vector length in x-direction in pixel units

• RMSE_Y_PX: root mean squared error of shift vector length in y-direction in pixel units

• MSE_M: mean squared error of absolute shift vector length in map units

• MSE_X_M: mean squared error of shift vector length in x-direction in map units

• MSE_Y_M: mean squared error of shift vector length in y-direction in map units

• MSE_X_PX: mean squared error of shift vector length in x-direction in pixel units

• MSE_Y_PX: mean squared error of shift vector length in y-direction in pixel units

• MAE_M: mean absolute error of absolute shift vector length in map units

• MAE_X_M: mean absolute error of shift vector length in x-direction in map units

• MAE_Y_M: mean absolute error of shift vector length in y-direction in map units

• MAE_X_PX: mean absolute error of shift vector length in x-direction in pixel units

• MAE_Y_PX: mean absolute error of shift vector length in y-direction in pixel units

• MEAN_ABS_SHIFT: mean absolute shift vector length in map units

• MEAN_X_SHIFT_M: mean shift vector length in x-direction in map units

• MEAN_Y_SHIFT_M: mean shift vector length in y-direction in map units

• MEAN_X_SHIFT_PX: mean shift vector length in x-direction in pixel units

• MEAN_Y_SHIFT_PX: mean shift vector length in y-direction in pixel units

• MEAN_ANGLE: mean direction of the shift vectors in degrees from north

• MEAN_SSIM_BEFORE: mean structural similatity index within each matching window before co-registration

• MEAN_SSIM_AFTER: mean structural similatity index within each matching window after co-registration

• MEAN_RELIABILITY: mean tie point reliability in percent

• MEDIAN_ABS_SHIFT: median absolute shift vector length in map units

• MEDIAN_X_SHIFT_M: median shift vector length in x-direction in map units

• MEDIAN_Y_SHIFT_M: median shift vector length in y-direction in map units

• MEDIAN_X_SHIFT_PX: median shift vector length in x-direction in pixel units

• MEDIAN_Y_SHIFT_PX: median shift vector length in y-direction in pixel units

• MEDIAN_ANGLE: median direction of the shift vectors in degrees from north

• MEDIAN_SSIM_BEFORE: median structural similatity index within each matching window before co-registration

• MEDIAN_SSIM_AFTER: median structural similatity index within each matching window after co-registration

• MEDIAN_RELIABILITY: median tie point reliability in percent

• STD_ABS_SHIFT: standard deviation of absolute shift vector length in map units

• STD_X_SHIFT_M: standard deviation of shift vector length in x-direction in map units

• STD_Y_SHIFT_M: standard deviation of shift vector length in y-direction in map units

• STD_X_SHIFT_PX: standard deviation of shift vector length in x-direction in pixel units

• STD_Y_SHIFT_PX: standard deviation of shift vector length in y-direction in pixel units

• STD_ANGLE: standard deviation of direction of the shift vectors in degrees from north

• STD_SSIM_BEFORE: standard deviation of structural similatity index within each matching window before

  co-registration

• STD_SSIM_AFTER: standard deviation of structural similatity index within each matching window after

  co-registration

• STD_RELIABILITY: standard deviation of tie point reliability in percent

• MIN_ABS_SHIFT: minimal absolute shift vector length in map units

• MIN_X_SHIFT_M: minimal shift vector length in x-direction in map units

• MIN_Y_SHIFT_M: minimal shift vector length in y-direction in map units

• MIN_X_SHIFT_PX: minimal shift vector length in x-direction in pixel units

• MIN_Y_SHIFT_PX: minimal shift vector length in y-direction in pixel units

• MIN_ANGLE: minimal direction of the shift vectors in degrees from north

• MIN_SSIM_BEFORE: minimal structural similatity index within each matching window before co-registration

• MIN_SSIM_AFTER: minimal structural similatity index within each matching window after co-registration

• MIN_RELIABILITY: minimal tie point reliability in percent

• MIN_ABS_SHIFT: maximal absolute shift vector length in map units

• MAX_X_SHIFT_M: maximal shift vector length in x-direction in map units

• MAX_Y_SHIFT_M: maximal shift vector length in y-direction in map units

• MAX_X_SHIFT_PX: maximal shift vector length in x-direction in pixel units

• MAX_Y_SHIFT_PX: maximal shift vector length in y-direction in pixel units

• MAX_ANGLE: maximal direction of the shift vectors in degrees from north

• MAX_SSIM_BEFORE: maximal structural similatity index within each matching window before co-registration

• MAX_SSIM_AFTER: maximal structural similatity index within each matching window after co-registration

• MAX_RELIABILITY: maximal tie point reliability in percent

Parameters

include_outliers (bool) – whether to include tie points that have been marked as false-positives (if present)

Return type

dict

calc_rmse(include_outliers=False)

Calculate root mean square error of absolute shifts from the tie point grid.

Parameters

include_outliers (bool) – whether to include tie points that have been marked as false-positives (if present)

Return type

float

dump_CoRegPoints_table(path_out=None)

get_CoRegPoints_table()

property mean_x_shift_map

property mean_x_shift_px

property mean_y_shift_map

property mean_y_shift_px

plot_shift_distribution(include_outliers=True, unit='m', interactive=False, figsize=None, xlim=None, ylim=None, fontsize=12, title='shift distribution', savefigPath='', savefigDPI=96, showFig=True, return_fig=False)

Create a 2D scatterplot containing the distribution of calculated X/Y-shifts.

Parameters

• include_outliers (bool) – whether to include tie points that have been marked as false-positives

• unit (str) – ‘m’ for meters or ‘px’ for pixels (default: ‘m’)

• interactive (bool) – whether to use interactive mode (uses plotly for visualization)

• figsize (tuple) – (xdim, ydim)

• xlim (list) – [xmin, xmax]

• ylim (list) – [ymin, ymax]

• fontsize (int) – size of all used fonts

• title (str) – the title to be plotted above the figure

• savefigPath (str) – path where to save the figure

• savefigDPI (int) – DPI resolution of the output figure when saved to disk

• showFig (bool) – whether to show or to hide the figure

• return_fig (bool) – whether to return the figure and axis objects

Return type

tuple

test_if_singleprocessing_equals_multiprocessing_result()

to_GCPList()

to_PointShapefile(path_out=None, skip_nodata=True, skip_nodata_col='ABS_SHIFT')

Write the calculated tie point grid to a point shapefile (e.g., for visualization by a GIS software).

NOTE: The shapefile uses Tie_Point_Grid.CoRegPoints_table as attribute table.

Parameters

• path_out (str) – <str> the output path. If not given, it is automatically defined.

• skip_nodata (bool) – <bool> whether to skip all points where no valid match could be found

• skip_nodata_col (str) – <str> determines which column of Tie_Point_Grid.CoRegPoints_table is used to identify points where no valid match could be found

Return type

None

static to_Raster_using_Kriging(*args, **kwargs)

to_interpolated_raster(metric='ABS_SHIFT', method='RBF', plot_result=False, lowres_spacing=5, v=False)

Interpolate the point data of the given metric into space.

Parameters

• metric (str) – metric name to interpolate, i.e., one of the column names of Tie_Point_Grid.CoRegPoints_table, e.g., ‘ABS_SHIFT’.

• method (str) – interpolation algorithm - ‘RBF’ (Radial Basis Function) - ‘GPR’ (Gaussian Process Regression; equivalent to Simple Kriging) - ‘Kriging’ (Ordinary Kriging based on pykrige)

• plot_result (bool) – plot the result to assess the interpolation quality

• lowres_spacing (int) – by default, RBF, GPR, and Kriging run a lower resolution which is then linearly interpolated to the full output image resolution. lowres_spacing defines the number of pixels between the low resolution grid points (higher values are faster but less accurate, default: 5)

• v (bool) – enable verbose mode

Return type

ndarray

Returns

interpolation result as numpy array in the X/Y dimension of the target image of the co-registration

to_vectorfield(path_out=None, fmt=None, mode='md')

Save the calculated X-/Y-shifts to a 2-band raster file that can be used to visualize a vectorfield.

NOTE: For example ArcGIS is able to visualize such 2-band raster files as a vectorfield.

Parameters

• path_out (str) – the output path. If not given, it is automatically defined.

• fmt (str) – output raster format string

• mode (str) – The mode how the output is written (‘uv’ or ‘md’; default: ‘md’) - ‘uv’: outputs X-/Y shifts - ‘md’: outputs magnitude and direction

Return type

GeoArray