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)[source]
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>.bsqfmt_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 = Falseout_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=Truetarget_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: cubicresamp_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 givenbinary_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_shift_reliability(scps)[source]
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'>)[source]
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
- _check_and_handle_metaRotation()[source]
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.
- _get_clip_window_properties()[source]
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
- _get_deshifted_otherWin()[source]
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
- Returns
GeoArray instance of de-shifted self.otherWin
- _get_image_windows_to_match()[source]
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
- _get_inverted_coreg_info()[source]
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
- _get_opt_winpos_winsize()[source]
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
- static _get_peakpos(scps)[source]
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]
- _handle_error(error, warn=False, warnMsg=None)[source]
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
- static _shrink_winsize_to_binarySize(win_shape_YX, target_size=None)[source]
Shrink a given window size to the closest binary window size (a power of 2).
NOTE: X- and Y-dimension are handled separately.
- _validate_ssim_improvement(v=False)[source]
Compute mean structural similarity index between reference and target image before and after co-registration.
- property are_pixGrids_equal
- calculate_spatial_shifts()[source]
Compute the global X/Y shift between reference and the target image within the matching window.
- Return type
- 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()[source]
Correct the already calculated X/Y shift of the target image.
- Return type
- Returns
COREG.deshift_results (dictionary)
- equalize_pixGrids()[source]
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
- show_cross_power_spectrum(interactive=False)[source]
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.
- show_image_footprints()[source]
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)[source]
Show the image content within the matching window.
- Parameters
figsize (
tuple
) – figure sizeinteractive (
bool
) – whether to return an interactive figure based on ‘holoviews’ libraryafter_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
- class arosics.CoReg.GeoArray_CoReg(CoReg_params, imID)[source]
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)[source]
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>.bsqfmt_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 datars_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 = Truematch_gsd (
bool
) – True: match the input pixel size to the reference pixel size, default = Falseout_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=Truetarget_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 shiftedcalc_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()[source]
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()[source]
Return the updated map info of the target image, shifted on the basis of the mean X/Y shifts.
- Return type
- check_if_fftw_works()[source]
Assign the attribute ‘fftw_works’ to self.COREG_obj by executing shift calculation once with muted output.
- Return type
- 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)[source]
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 usecliptoextent (
bool
) – whether to clip the output image to its real extentmin_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
- Returns
- show_image_footprints()[source]
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 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)[source]
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 mapattribute2plot (
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 failedbackgroundIm (
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 levelfigsize (
tuple
) – size of the figure to be viewed, e.g. (10, 10); automatically estimated if not givenfigsize_multiplier (
float
) – if given, the figure size is multiplied with this valuetitle (
str
) – plot titlevector_scale (
float
) – scale factor for shift vector length (default: 1 -> no scaling)savefigPath (
str
) – path where to save the figuresavefigDPI (
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 figurevmax (
float
) – maximum value of ‘attribute2plot’ to be included in the figurereturn_map (
bool
) – whether to return the figure and axis objects (default: False)
- Return type
- Returns
tuple of figure and axis objects or None in case return_map is set to False
arosics.DeShifter module
- class arosics.DeShifter.DESHIFTER(im2shift, coreg_results, **kwargs)[source]
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 objectcoreg_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)[source]
Check if the input image pixel grid is alignable to the output grid.
- Parameters
in_xgsd –
in_ygsd –
out_xgsd –
out_ygsd –
- Returns
- 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)[source]
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 objectcoreg_results (
dict
) – the results of the co-registration as given by COREG.coreg_info or COREG_LOCAL.coreg_info respectivelypath_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)[source]
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 classgrid_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 methodsCPUs (
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)[source]
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_imXY__mapXY_points(grid_res)[source]
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
- calc_overall_ssim(include_outliers=False, after_correction=True)[source]
Calculate the median value of all SSIM values contained in tie point grid.
- calc_overall_stats(include_outliers=False)[source]
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
- calc_rmse(include_outliers=False)[source]
Calculate root mean square error of absolute shifts from the tie point grid.
- 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)[source]
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-positivesunit (
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 fontstitle (
str
) – the title to be plotted above the figuresavefigPath (
str
) – path where to save the figuresavefigDPI (
int
) – DPI resolution of the output figure when saved to diskshowFig (
bool
) – whether to show or to hide the figurereturn_fig (
bool
) – whether to return the figure and axis objects
- Return type
- to_PointShapefile(path_out=None, skip_nodata=True, skip_nodata_col='ABS_SHIFT')[source]
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 foundskip_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
- to_interpolated_raster(metric='ABS_SHIFT', method='RBF', plot_result=False, lowres_spacing=5, v=False)[source]
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 qualitylowres_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
- class arosics.Tie_Point_Grid.Tie_Point_Grid_Interpolator(tiepointgrid, v=False)[source]
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 shiftsv (
bool
) – enable verbose mode
- _get_pointdata(metric)[source]
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)[source]
Run linear regular grid interpolation.
- static _interpolate_via_gpr(rows, cols, data, rows_full, cols_full)[source]
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)[source]
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)[source]
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)[source]
Plot the interpolation result together with the input point data.
- interpolate(metric, method='RBF', plot_result=False, lowres_spacing=5)[source]
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 qualitylowres_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)[source]
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)[source]
Detect geometric outliers between point cloud of source and estimated coordinates using RANSAC algorithm.
- _reliability_thresholding()[source]
Exclude all records where estimated reliability of the calculated shifts is below the given threshold.
- run_filtering(level=3)[source]
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.arosics_cli module
arosics.geometry module
- arosics.geometry.angle_to_north(XY)[source]
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)[source]
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)[source]
Return row_start,col_start,rows_count,cols_count and assumes boxImYX as [UL_YX,UR_YX,LR_YX,LL_YX).
- arosics.geometry.get_true_corner_mapXY(fPath_or_geoarray, band=0, noDataVal=None, mp=1, v=0, q=0)[source]
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.plotting module
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)[source]
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>.bsqfmt_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 = Falseout_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=Truetarget_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: cubicresamp_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 givenbinary_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_shift_reliability(scps)[source]
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'>)[source]
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
- _check_and_handle_metaRotation()[source]
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.
- _get_clip_window_properties()[source]
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
- _get_deshifted_otherWin()[source]
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
- Returns
GeoArray instance of de-shifted self.otherWin
- _get_image_windows_to_match()[source]
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
- _get_inverted_coreg_info()[source]
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
- _get_opt_winpos_winsize()[source]
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
- static _get_peakpos(scps)[source]
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]
- _handle_error(error, warn=False, warnMsg=None)[source]
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
- static _shrink_winsize_to_binarySize(win_shape_YX, target_size=None)[source]
Shrink a given window size to the closest binary window size (a power of 2).
NOTE: X- and Y-dimension are handled separately.
- _validate_ssim_improvement(v=False)[source]
Compute mean structural similarity index between reference and target image before and after co-registration.
- property are_pixGrids_equal
- calculate_spatial_shifts()[source]
Compute the global X/Y shift between reference and the target image within the matching window.
- Return type
- 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()[source]
Correct the already calculated X/Y shift of the target image.
- Return type
- Returns
COREG.deshift_results (dictionary)
- equalize_pixGrids()[source]
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
- show_cross_power_spectrum(interactive=False)[source]
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.
- show_image_footprints()[source]
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)[source]
Show the image content within the matching window.
- Parameters
figsize (
tuple
) – figure sizeinteractive (
bool
) – whether to return an interactive figure based on ‘holoviews’ libraryafter_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
- 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)[source]
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>.bsqfmt_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 datars_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 = Truematch_gsd (
bool
) – True: match the input pixel size to the reference pixel size, default = Falseout_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=Truetarget_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 shiftedcalc_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()[source]
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()[source]
Return the updated map info of the target image, shifted on the basis of the mean X/Y shifts.
- Return type
- check_if_fftw_works()[source]
Assign the attribute ‘fftw_works’ to self.COREG_obj by executing shift calculation once with muted output.
- Return type
- 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)[source]
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 usecliptoextent (
bool
) – whether to clip the output image to its real extentmin_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
- Returns
- show_image_footprints()[source]
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 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)[source]
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 mapattribute2plot (
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 failedbackgroundIm (
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 levelfigsize (
tuple
) – size of the figure to be viewed, e.g. (10, 10); automatically estimated if not givenfigsize_multiplier (
float
) – if given, the figure size is multiplied with this valuetitle (
str
) – plot titlevector_scale (
float
) – scale factor for shift vector length (default: 1 -> no scaling)savefigPath (
str
) – path where to save the figuresavefigDPI (
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 figurevmax (
float
) – maximum value of ‘attribute2plot’ to be included in the figurereturn_map (
bool
) – whether to return the figure and axis objects (default: False)
- Return type
- Returns
tuple of figure and axis objects or None in case return_map is set to False
- class arosics.DESHIFTER(im2shift, coreg_results, **kwargs)[source]
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 objectcoreg_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)[source]
Check if the input image pixel grid is alignable to the output grid.
- Parameters
in_xgsd –
in_ygsd –
out_xgsd –
out_ygsd –
- Returns
- 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)[source]
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 classgrid_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 methodsCPUs (
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)[source]
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_imXY__mapXY_points(grid_res)[source]
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
- calc_overall_ssim(include_outliers=False, after_correction=True)[source]
Calculate the median value of all SSIM values contained in tie point grid.
- calc_overall_stats(include_outliers=False)[source]
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
- calc_rmse(include_outliers=False)[source]
Calculate root mean square error of absolute shifts from the tie point grid.
- 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)[source]
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-positivesunit (
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 fontstitle (
str
) – the title to be plotted above the figuresavefigPath (
str
) – path where to save the figuresavefigDPI (
int
) – DPI resolution of the output figure when saved to diskshowFig (
bool
) – whether to show or to hide the figurereturn_fig (
bool
) – whether to return the figure and axis objects
- Return type
- to_PointShapefile(path_out=None, skip_nodata=True, skip_nodata_col='ABS_SHIFT')[source]
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 foundskip_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
- to_interpolated_raster(metric='ABS_SHIFT', method='RBF', plot_result=False, lowres_spacing=5, v=False)[source]
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 qualitylowres_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