Command line interface reference
arosics
At the command line, arosics provides the arosics command:
Perform automatic subpixel co-registration of two satellite image datasets based on an image matching approach working in the frequency domain, combined with a multistage workflow for effective detection of false-positives. Python implementation by Daniel Scheffler (daniel.scheffler [at] gfz-potsdam [dot] de). The scientific background is described in the paper Scheffler D, Hollstein A, Diedrich H, Segl K, Hostert P. AROSICS: An Automated and Robust Open-Source Image Co-Registration Software for Multi-Sensor Satellite Data. Remote Sensing. 2017; 9(7):676.” (https://www.mdpi.com/2072-4292/9/7/676)
usage: arosics [-h] [--version] {global,local} ...
Named Arguments
- --version
show program’s version number and exit
Sub-commands
global
Detects and corrects global X/Y shifts between a target and refernce image. Geometric shifts are calculated at a specific (adjustable) image position. Correction performs a global shifting in X- or Y direction.
arosics global [-h] [-o [PATH_OUT]] [-fmt_out [FMT_OUT]] [-br [BR]] [-bs [BS]]
[-ws X size Y size] [-max_iter [MAX_ITER]]
[-max_shift [MAX_SHIFT]]
[-rsp_alg_deshift [{0,1,2,3,4,5,6,7,8,9,10,11}]]
[-rsp_alg_calc [{0,1,2,3,4,5,6,7,8,9,10,11}]]
[-cor0 UL-X UL-Y UR-X UR-Y LR-X LR-Y LL-X LL-Y]
[-cor1 UL-X UL-Y UR-X UR-Y LR-X LR-Y LL-X LL-Y]
[-calc_cor [{0,1}]] [-nodata im0 im1] [-bin_ws [{0,1}]]
[-quadratic_win [{0,1}]] [-mask_ref [file path]]
[-mask_tgt [file path]] [-mp [{0,1}]] [-progress [{0,1}]]
[-v [{0,1}]] [-q [{0,1}]] [-ignore_errors [{0,1}]] [-wp X Y]
[-align_grids [{0,1}]] [-match_gsd [{0,1}]]
[-out_gsd xgsd ygsd] [-vo [{0,1}]]
path_ref path_tgt
Positional Arguments
- path_ref
source path of reference image (any GDAL compatible image format is supported)
- path_tgt
source path of image to be shifted (any GDAL compatible image format is supported)
Named Arguments
- -o
target path of the coregistered image If ‘auto’ (default: /dir/of/im1/<im1>__shifted_to__<im0>.bsq)
Default: “auto”
- -fmt_out
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)
Default: “ENVI”
- -br
band of reference image to be used for matching (starts with 1; default: 1)
Default: 1
- -bs
band of shift image to be used for matching (starts with 1; default: 1)
Default: 1
- -ws
custom matching window size [pixels] (default: (256,256))
Default: (256, 256)
- -max_iter
maximum number of iterations for matching (default: 5)
Default: 5
- -max_shift
maximum shift distance in reference image pixel units (default: 5 px)
Default: 5
- -rsp_alg_deshift
Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
the resampling algorithm to be used for shift correction (if neccessary) (valid algorithms: 0=nearest neighbour, 1=bilinear, 2=cubic, 3=cubic_spline, 4=lanczos, 5=average, 6=mode, 7=max, 8=min, 9=med, 10=q1, 11=q3), default: 2
Default: 2
- -rsp_alg_calc
Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
the resampling algorithm to be used for all warping processes during calculation of spatial shifts (valid algorithms: 0=nearest neighbour, 1=bilinear, 2=cubic, 3=cubic_spline, 4=lanczos, 5=average, 6=mode, 7=max, 8=min, 9=med, 10=q1, 11=q3), default: 2 (highly recommended)
Default: 2
- -cor0
map coordinates of data corners within reference image:
- -cor1
map coordinates of data corners within image to be shifted:
- -calc_cor
Possible choices: 0, 1
calculate true positions of the dataset corners in order to get a useful matching window position within the actual image overlap (default: 1; deactivated if ‘-cor0’ and ‘-cor1’ are given
Default: 1
- -nodata
no data values for reference image and image to be shifted
Default: (None, None)
- -bin_ws
Possible choices: 0, 1
use binary X/Y dimensions for the matching window (default: 1)
Default: 1
- -quadratic_win
Possible choices: 0, 1
force a quadratic matching window (default: 1)
Default: 1
- -mask_ref
path to a 2D boolean mask file for the reference image where all bad data pixels (e.g. clouds) are marked with True or 1 and the remaining pixels with False or 0. Must have the same geographic extent and projection like the reference image. 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_tgt
path to a 2D boolean mask file for the image to be shifted where all bad data pixels (e.g. clouds) are marked with True or 1 and the remaining pixels with False or 0. Must have the same geographic extent and projection like the the image to be shifted. 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.
- -mp
Possible choices: 0, 1
enable multiprocessing (default: 1)
Default: 1
- -progress
Possible choices: 0, 1
show progress bars (default: 1)
Default: 1
- -v
Possible choices: 0, 1
verbose mode (default: 0)
Default: 0
- -q
Possible choices: 0, 1
quiet mode (default: 0)
Default: 0
- -ignore_errors
Possible choices: 0, 1
Useful for batch processing. (default: 0) In case of error COREG(_LOCAL).success == False and COREG(_LOCAL).x_shift_px/COREG(_LOCAL).y_shift_px is None
Default: 0
- -wp
custom matching window position as map values in the same projection like the reference image (default: central position of image overlap)
Default: (None, None)
- -align_grids
Possible choices: 0, 1
align the coordinate grids of the output image to the reference image (default: 0)
Default: 0
- -match_gsd
Possible choices: 0, 1
match the output pixel size to the pixel size of the reference image (default: 0)
Default: 0
- -out_gsd
xgsd ygsd: set the output pixel size in map units (default: original pixel size of the image to be shifted)
- -vo
Possible choices: 0, 1
an optional output directory for outputs of verbose mode(if not given, no outputs are written to disk)
Default: 0
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.
arosics local [-h] [-o [PATH_OUT]] [-fmt_out [FMT_OUT]] [-br [BR]] [-bs [BS]]
[-ws X size Y size] [-max_iter [MAX_ITER]]
[-max_shift [MAX_SHIFT]]
[-rsp_alg_deshift [{0,1,2,3,4,5,6,7,8,9,10,11}]]
[-rsp_alg_calc [{0,1,2,3,4,5,6,7,8,9,10,11}]]
[-cor0 UL-X UL-Y UR-X UR-Y LR-X LR-Y LL-X LL-Y]
[-cor1 UL-X UL-Y UR-X UR-Y LR-X LR-Y LL-X LL-Y]
[-calc_cor [{0,1}]] [-nodata im0 im1] [-bin_ws [{0,1}]]
[-quadratic_win [{0,1}]] [-mask_ref [file path]]
[-mask_tgt [file path]] [-mp [{0,1}]] [-progress [{0,1}]]
[-v [{0,1}]] [-q [{0,1}]] [-ignore_errors [{0,1}]]
[-max_points [MAX_POINTS]] [-projectDir [PROJECTDIR]]
[-tieP_filter_level [{0,1,2,3}]]
[-min_reliability [MIN_RELIABILITY]]
[-rs_max_outlier [RS_MAX_OUTLIER]]
[-rs_tolerance [RS_TOLERANCE]]
path_ref path_tgt grid_res
Positional Arguments
- path_ref
source path of reference image (any GDAL compatible image format is supported)
- path_tgt
source path of image to be shifted (any GDAL compatible image format is supported)
- grid_res
tie point grid resolution in pixels of the target image
Named Arguments
- -o
target path of the coregistered image If ‘auto’ (default: /dir/of/im1/<im1>__shifted_to__<im0>.bsq)
Default: “auto”
- -fmt_out
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)
Default: “ENVI”
- -br
band of reference image to be used for matching (starts with 1; default: 1)
Default: 1
- -bs
band of shift image to be used for matching (starts with 1; default: 1)
Default: 1
- -ws
custom matching window size [pixels] (default: (256,256))
Default: (256, 256)
- -max_iter
maximum number of iterations for matching (default: 5)
Default: 5
- -max_shift
maximum shift distance in reference image pixel units (default: 5 px)
Default: 5
- -rsp_alg_deshift
Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
the resampling algorithm to be used for shift correction (if neccessary) (valid algorithms: 0=nearest neighbour, 1=bilinear, 2=cubic, 3=cubic_spline, 4=lanczos, 5=average, 6=mode, 7=max, 8=min, 9=med, 10=q1, 11=q3), default: 2
Default: 2
- -rsp_alg_calc
Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
the resampling algorithm to be used for all warping processes during calculation of spatial shifts (valid algorithms: 0=nearest neighbour, 1=bilinear, 2=cubic, 3=cubic_spline, 4=lanczos, 5=average, 6=mode, 7=max, 8=min, 9=med, 10=q1, 11=q3), default: 2 (highly recommended)
Default: 2
- -cor0
map coordinates of data corners within reference image:
- -cor1
map coordinates of data corners within image to be shifted:
- -calc_cor
Possible choices: 0, 1
calculate true positions of the dataset corners in order to get a useful matching window position within the actual image overlap (default: 1; deactivated if ‘-cor0’ and ‘-cor1’ are given
Default: 1
- -nodata
no data values for reference image and image to be shifted
Default: (None, None)
- -bin_ws
Possible choices: 0, 1
use binary X/Y dimensions for the matching window (default: 1)
Default: 1
- -quadratic_win
Possible choices: 0, 1
force a quadratic matching window (default: 1)
Default: 1
- -mask_ref
path to a 2D boolean mask file for the reference image where all bad data pixels (e.g. clouds) are marked with True or 1 and the remaining pixels with False or 0. Must have the same geographic extent and projection like the reference image. 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_tgt
path to a 2D boolean mask file for the image to be shifted where all bad data pixels (e.g. clouds) are marked with True or 1 and the remaining pixels with False or 0. Must have the same geographic extent and projection like the the image to be shifted. 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.
- -mp
Possible choices: 0, 1
enable multiprocessing (default: 1)
Default: 1
- -progress
Possible choices: 0, 1
show progress bars (default: 1)
Default: 1
- -v
Possible choices: 0, 1
verbose mode (default: 0)
Default: 0
- -q
Possible choices: 0, 1
quiet mode (default: 0)
Default: 0
- -ignore_errors
Possible choices: 0, 1
Useful for batch processing. (default: 0) In case of error COREG(_LOCAL).success == False and COREG(_LOCAL).x_shift_px/COREG(_LOCAL).y_shift_px is None
Default: 0
- -max_points
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.
- -projectDir
- -tieP_filter_level
Possible choices: 0, 1, 2, 3
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
Default: 3
- -min_reliability
Tie point filtering: minimum reliability threshold, below which tie points are marked as false-positives (default: 60 percent) - 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
Default: 60
- -rs_max_outlier
RANSAC tie point filtering: proportion of expected outliers (default: 10 percent)
Default: 10
- -rs_tolerance
RANSAC tie point filtering: percentage tolerance for max_outlier_percentage (default: 2.5 percent)
Default: 2.5
DETAILED DESCRIPTION: AROSICS detects and corrects global as well as local misregistrations between two input images in the subpixel scale, that are often present in satellite imagery. The input images can have any GDAL compatible image format (https://gdal.org/drivers/raster/index.html). Both of them must be approximately geocoded. In case of ENVI files, this means they must have a ‘map info’ and a ‘coordinate system string’ as attributes of their header file. The input images must have a geographic overlap but clipping them to same geographical extent is NOT neccessary. Please do not perform any spatial resampling of the input images before applying this algorithm. Any needed resampling of the data is done automatically. Thus, the input images may have different spatial resolutions. The current algorithm will not perform any ortho-rectification. So please use ortho-rectified input data in order to minimize local shifts in the input images. AROSICS supports local and global co-registration. LOCAL CO-REGISTRATION: A dense grid of tie points is automatically computed, whereas tie points are subsequently validated using a multistage workflow. Only those tie points not marked as false-positives are used to compute the parameters of an affine transformation. Warping of the target image is done using an appropriate resampling technique (cubic by default). GLOBAL CO-REGISTRATION: Only a global X/Y translation is computed within a small subset of the input images (window position is adjustable). This allows very fast co-registration but only corrects for translational (global) X/Y shifts. The calculated subpixel-shifts are (by default) applied to the geocoding information of the output image. No spatial resampling is done automatically as long as both input images have the same projection. If you need the output image to be aligned to the reference image coordinate grid (by using an appropriate resampling algorithm), use the ‘-align_grids’ option. AROSICS is designed to robustly handle the typical difficulties of multi-sensoral/multi-temporal images. Clouds are automatically handled by the implemented outlier detection algorithms. The user may provide user-defined masks to exclude certain image areas from tie point creation. The image overlap area is automatically calculated. Thereby, no-data regions within the images are automatically respected. Providing the map coordinates of the actual data corners lets you save some calculation time, because in this case the automatic algorithm can be skipped. The no-data value of each image is automatically derived from the image corners. The verbose program mode gives some more output about the interim results, shows some figures and writes the used footprint and overlap polygons to disk. Note, that maybe the figures must be manually closed in in order to continue the processing (depending on your Python configuration). For further details regarding the implemented algorithm, example use cases, quality assessment and benchmarks refer to the above mentioned paper (Scheffler et al. 2017).
Note
The verbose program mode gives some more output about the interim results, shows some figures and writes the used footprint and overlap polygons to disk. Maybe the figures must be manually closed in in order to continue the processing (depending on your Python configuration).