RSGISLib Image Registration

The image registration module contains algorithms for matching images together, either to find a whole image shift or for generating tie points matching two image which can then be used to warp the input image.

There are two tie point generation algorithms are available for registration: basic, and singlelayer. The single layer algorithm is a simplified version of the algorithm proposed in:

Bunting, P.J., Labrosse, F. & Lucas, R.M., 2010. A multi-resolution area-based technique for automatic multi-modal image registration. Image and Vision Computing, 28(8), pp.1203-1219.

Image distance metrics:

  • METRIC_EUCLIDEAN = 1

  • METRIC_SQDIFF = 2

  • METRIC_MANHATTEN = 3

  • METRIC_CORELATION = 4

GCP Output Types:

  • TYPE_ENVI_IMG2IMG = 1

  • TYPE_ENVI_IMG2MAP = 2

  • TYPE_RSGIS_IMG2MAP = 3

  • TYPE_RSGIS_MAPOFFS = 4

Whole Image Shift

rsgislib.imageregistration.find_image_offset(in_ref_img: str, in_float_img: str, ref_img_bands: list, flt_img_bands: list, metric_type: int, x_search: int, y_search: int, sub_pxl_res: int)

Calculate and X/Y offset between the input reference and float images. This function will calculate the similarity intersecting regions of the two images and identified an X/Y where the similarity is greatest.

Parameters:

  • in_ref_img – is a string providing reference image which to which the floating image is to be registered.n:param in_float_img: is a string providing the floating image to be registered to the reference image

  • ref_img_bands – is a list of image bands which are to be used to calculate the image similarity from the reference image.

  • flt_img_bands – is a list of image bands which are to be used to calculate the image similarity from the floating image.

  • metric_type – is an the similarity metric used to compare images of type rsgislib.imageregistration.METRIC_*

  • x_search – is the number of pixels in the x-axis the image can be moved either side of the centre.

  • y_search – is the number of pixels in the y-axis the image can be moved either side of the centre.

  • sub_pxl_res – is an optional (if not specified then no sub-pixel component will be estimated) int specifying the sub-pixel resolution to which the pixel shifts are estimated. Note that the values are positive integers such that a value of 2 will result in a sub pixel resolution of 0.5 of a pixel and a value 4 will be 0.25 of a pixel.

Returns:

(x_offset, y_offset)

rsgislib.imageregistration.apply_offset_to_image(input_img: str, output_img: str, gdalformat: str, datatype: int, x_offset: float, y_offset: float)

Apply a linear X,Y offset to the image header - does not change the pixel values.

Parameters:

  • input_img – is a string providing the input image.

  • output_img – is a string providing the output image.

  • gdalformat – is a string providing the output format (e.g., KEA).

  • datatype – is a rsgislib.TYPE_* value providing the output data type.

  • x_offset – is a float specifying the X offset to be applied to the image.

  • y_offset – is a float specifying the Y offset to be applied to the image.

from rsgislib import imageregistration
inputImage = './Rasters/injune_p142_casi_sub_utm_single_band_offset3x3y.vrt'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_single_band_offset3x3y_fixed.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32INT
imageregistration.apply_offset_to_image(inputImage, outputImage, gdalformat, datatype, -3.0, -3.0)

Tie Point Generation

rsgislib.imageregistration.basic_registration(in_ref_img: str, in_float_img: str, out_gcp_file: str, pixel_gap: int, threshold: float, win_size: int, search_area: int, sd_ref_thres: float, sd_flt_thres: float, sub_pxl_res: float, metric_type: int, output_type: int)

Generate tie points between floating and reference image using basic algorithm.

Parameters:

  • in_ref_img – is a string providing reference image which to which the floating image is to be registered.n:param in_float_img: is a string providing the floating image to be registered to the reference image

  • out_gcp_file – is a string giving specifying the output file, containing the generated tie points

  • pixel_gap – is an int specifying the gap, in image pixels, between the initial tie points (this is for both the x and y axis)

  • threshold – is a float providing the threshold for the image metric above/below (depending on image metric) which matching is consider insufficient to be reliable and therefore the match will be ignored.

  • win_size – is an int providing the size of the window around each tie point which will be used for the matching

  • search_area – is an int providing the distance (in pixels) from the tie point start point which will be searched.

  • sd_ref_thres – is a float which defines the standard deviation for the window around each tie point below which it is deemed there is insufficient information to perform a match

  • sd_flt_thres – is a float which defines the standard deviation for the window around each tie point below which it is deemed there is insufficient information to perform a match. Note, that the tie point window has to be below the threshold for both the reference and floating image to be ignored

  • sub_pxl_res – is an int specifying the sub-pixel resolution to which the pixel shifts are estimated. Note that the values are positive integers such that a value of 2 will result in a sub pixel resolution of 0.5 of a pixel and a value 4 will be 0.25 of a pixel.

  • metric_type – is an the similarity metric used to compare images of type rsgislib.imageregistration.METRIC_*

  • output_type – is an the format of the output file of type rsgislib.imageregistration.TYPE_*

reference = 'ref.kea'
floating = 'float.kea'
pixelGap = 50
threshold = 0.4
window = 100
search = 5
stddevRef = 2
stddevFloat = 2
subpixelresolution = 4
metric = imageregistration.METRIC_CORELATION
outputType = imageregistration.TYPE_RSGIS_IMG2MAP
output = './TestOutputs/injune_p142_casi_sub_utm_tie_points.txt'
imageregistration.basic_registration(reference, floating, pixelGap, threshold, window, search, stddevRef, stddevFloat, subpixelresolution, metric, outputType, output)
rsgislib.imageregistration.single_layer_registration(in_ref_img: str, in_float_img: str, out_gcp_file: str, pixel_gap: int, threshold: float, win_size: int, search_area: int, sd_ref_thres: float, sd_flt_thres: float, sub_pxl_res: float, dist_threshold: float, max_n_iters: int, move_chng_thres: float, p_smooth: float, metric_type: int, output_type: int)

Generate tie points between floating and reference image using a single connected layer of tie points.

Parameters:

  • in_ref_img – is a string providing reference image which to which the floating image is to be registered.n:param in_float_img: is a string providing the floating image to be registered to the reference image

  • out_gcp_file – is a string giving specifying the output file, containing the generated tie points

  • pixel_gap – is an int specifying the gap, in image pixels, between the initial tie points (this is for both the x and y axis) which matching is consider insufficient to be reliable and therefore the match will be ignored.

  • threshold – is a float providing the threshold for the image metric above/below (depending on image metric) which matching is consider insufficient to be reliable and therefore the match will be ignored.

  • win_size – is an int providing the size of the window around each tie point which will be used for the matching

  • search_area – is an int providing the distance (in pixels) from the tie point start point which will be searched.

  • sd_ref_thres – is a float which defines the standard deviation for the window around each tie point below which it is deemed there is insufficient information to perform a match

  • sd_flt_thres – is a float which defines the standard deviation for the window around each tie point below which it is deemed there is insufficient information to perform a match. Note, that the tie point window has to be below the threshold for both the reference and floating image to be ignored

  • sub_pxl_res – is an int specifying the sub-pixel resolution to which the pixel shifts are estimated. Note that the values are positive integers such that a value of 2 will result in a sub pixel resolution of 0.5 of a pixel and a value 4 will be 0.25 of a pixel.

  • dist_threshold – is an int giving the distance (in pixels) to be connected within the layer.

  • max_n_iters – is an int giving the maximum number of iterations of the tie point grid to find an optimal set of tie points

  • move_chng_thres – is a float providing the threshold for the average amount of tie point movement for the optimisation to be terminated

  • p_smooth – is a float providing the ‘p’ parameter for the inverse weighted distance calculation. A value of 2 should be used by default

  • metric_type – is an the similarity metric used to compare images of type rsgislib.imageregistration.METRIC_*

  • output_type – is an the format of the output file of type rsgislib.imageregistration.TYPE_*

from rsgislib import imageregistration
reference = 'ref.kea'
floating = 'float.kea'
pixelGap = 50
threshold = 0.4
window = 100
search = 5
stddevRef = 2
stddevFloat = 2
subpixelresolution = 4
metric = imageregistration.METRIC_CORELATION
outputType = imageregistration.TYPE_RSGIS_IMG2MAP
output = './TestOutputs/injune_p142_casi_sub_utm_tie_points.txt'
imageregistration.single_layer_registration(reference, floating, pixelGap, threshold, window, search, stddevRef, stddevFloat, subpixelresolution, metric, outputType, output)

Warping

rsgislib.imageregistration.warp_with_gcps_with_gdal(in_ref_img: str, in_process_img: str, output_img: str, gdalformat: str, interp_method: int = 0, use_tps: bool = False, use_poly: bool = True, poly_order: int = 3, use_multi_thread: bool = False)

A utility function to warp an image file (in_process_img) using GCPs defined within the image header - this is the same as using the gdalwarp utility. However, the output image will have the same pixel grid and dimensions as the input reference image (in_ref_img).

Parameters:

  • in_ref_img – is the input reference image to which the processing image is to resampled to.

  • in_process_img – is the image which is to be resampled.

  • output_img – is the output image file.

  • gdalformat – is the gdal format for the output image.

  • interp_method – is the interpolation method used to resample the image [bilinear, lanczos, cubicspline, nearestneighbour, cubic, average, mode]

  • use_tps – is a boolean specifying that the thin plated splines method of warping should be used (i.e., rubbersheet); Default False.

  • use_poly – is a boolean specifying that a polynomial method of warping is used; Default True

  • poly_order – is the order of the polynomial used to represent the transformation (1, 2 or 3). Only used if use_poly=True

  • use_multi_thread – is a boolean specifying whether multiple processing cores should be used for the warping.

Other

rsgislib.imageregistration.gcp_to_gdal(input_img: str, in_gcp_file: str, output_img: str, gdalformat: str, datatype: int)

Adds tie points to GDAL file, suitable for warping using the gdalwarp command.

Parameters:

  • input_img – is a string providing the input image.

  • in_gcp_file – is a string providing the input text file containing the tie points.

  • output_img – is a string providing the output image.

  • gdalformat – is a string providing the output format (e.g., KEA).

  • datatype – is a rsgislib.TYPE_* value providing the output data type.

from rsgislib import imageregistration
inputImage = './Rasters/injune_p142_casi_sub_utm_single_band_offset3x3y.vrt'
inputGCPs = './TestOutputs/injune_p142_casi_sub_utm_tie_points_basic.txt'
outputImage = './TestOutputs/injune_p142_casi_sub_utm_single_band_offset3x3y_gcps.kea'
gdalformat = 'KEA'
datatype = rsgislib.TYPE_32INT
imageregistration.gcp_to_gdal(inputImage,inputGCPs, outputImage, gdalformat, gdaltype)
rsgislib.imageregistration.add_vec_pts_as_gcps_to_img(input_img: str, output_img: str, vec_file: str, vec_lyr: str = None, gcp_x_col: str = 'x_match', gcp_y_col: str = 'y_match', gcp_z_col: str = None, gcp_epsg: int = None)

A function which uses a points vector layer to specify GCP locations within the image with attributes to the vector layer used to specify the GCP spatial location.

Note. input_img and output_img can be the same file path if you do not want an new output image to be created (i.e., for the input file to be edited)

Parameters:

  • input_img – The input image file path

  • output_img – The output image path

  • vec_file – the vector file path

  • vec_lyr – the vector layer name

  • gcp_x_col – column within the vector layer specifying the GCP x coordinates

  • gcp_y_col – column within the vector layer specifying the GCP y coordinates

  • gcp_z_col – column within the vector layer specifying the GCP x coordinates. The Z coordinate is optional, Default is None.

  • gcp_epsg – Optionally specify an EPSG code for the projection the GCP points. If None (Default) then the projection of the input image will used.