RSGISLib Image Registration Module

The image registration module contains algorithms for generating tie points matching two image and warping images based on tie points.

There are two 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
rsgislib.imageregistration.warpUseGCPsWithGDAL(inRefImg, inProcessImg, outImg, gdalFormat, interpMethod, useTPS=False, usePoly=True, polyOrder=3, useMutliThread=False)

A utility function to warp an image file (inProcessImg) 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 (inRefImg).

Where:

  • inRefImg is the input reference image to which the processing image is to resampled to.
  • inProcessImg is the image which is to be resampled.
  • outImg is the output image file.
  • gdalFormat is the gdal format for the output image.
  • interpMethod is the interpolation method used to resample the image [bilinear, lanczos, cubicspline, nearestneighbour, cubic, average, mode]
  • useTPS is a boolean specifying that the thin plated splines method of warping should be used (i.e., rubbersheet); Default False.
  • usePoly is a boolean specifying that a polynomial method of warpping is used; Default True
  • polyOrder is the order of the polynomial used to represent the transformation (1, 2 or 3). Only used if usePoly=True
  • useMutliThread is a boolean specifying whether multiple processing cores should be used for the warpping.

Tie Point Generation

rsgislib.imageregistration.basicregistration(reference, floating, pixelGap, threshold, window, search, stddevRef, stddevFloat, subpixelresolution, metric, outputType, output)

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

Where:

  • reference is a string providing reference image which to which the floating image is to be registered.n * floating is a string providing the floating image to be registered to the reference image
  • pixelGap 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.
  • window is an int providing the size of the window around each tie point which will be used for the matching
  • search is an int providing the distance (in pixels) from the tie point start point which will be searched.
  • stddevRef 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
  • stddevFloat 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
  • subpixelresolution 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 is an the similarity metric used to compare images of type rsgislib.imageregistration.METRIC_*
  • outputType is an the format of the output file of type rsgislib.imageregistration.TYPE_*
  • output is a string giving specifying the output file, containing the generated tie points

Example:

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.basicregistration(reference, floating, pixelGap, threshold, window, search, stddevRef, stddevFloat, subpixelresolution, metric, outputType, output)
rsgislib.imageregistration.singlelayerregistration(reference, floating, pixelGap, threshold, window, search, stddevRef, stddevFloat, subpixelresolution, distanceThreshold, maxiterations, movementThreshold, pSmoothness, metric, outputType, output)

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

Where:

  • reference is a string providing reference image which to which the floating image is to be registered.n * floating is a string providing the floating image to be registered to the reference image
  • pixelGap 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.
  • window is an int providing the size of the window around each tie point which will be used for the matching
  • search is an int providing the distance (in pixels) from the tie point start point which will be searched.
  • stddevRef 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
  • stddevFloat 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
  • subpixelresolution 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.
  • distanceThreshold is an int giving the distance (in pixels) to be connected within the layer.
  • maxiterations is an int giving the maximum number of iterations of the tie point grid to find an optimal set of tie points
  • movementThreshold is a float providing the threshold for the average amount of tie point movement for the optimisation to be terminated
  • pSmoothness is a float providing the ‘p’ parameter for the inverse weighted distance calculation. A value of 2 should be used by default
  • metric is an the similarity metric used to compare images of type rsgislib.imageregistration.METRIC_*
  • outputType is an the format of the output file of type rsgislib.imageregistration.TYPE_*
  • output is a string giving specifying the output file, containing the generated tie points

Example:

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.basicregistration(reference, floating, pixelGap, threshold, window, search, stddevRef, stddevFloat, subpixelresolution, metric, outputType, output)

Warping

rsgislib.imageregistration.nnwarp(inputimage, inputgcps, outputimage, wktStringFile, resolution, gdalformat, transformImage=False)

Warp image from tie points using a nearest neighbour interpolation.

Where:

  • inputimage is a string providing the input image.
  • inputgcps is a string providing the input text file containing the tie points.
  • outputimage is a string providing the output image.
  • wktStringFile is a file path to a text file containing the WKT string to use for the warped image.
  • resolution is a float providing the resolution of the output file
  • gdalformat is a string providing the output format (e.g., KEA).
  • transformImage is a bool, if set to true will generate an image providing the transform for each pixel, rather than warping the input image

Example:

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_nnwarp.kea'
wktStringFile = './Vectors/injune_p142_crowns_utm.prj'
resolution = 1
gdalformat = 'KEA'
imageregistration.nnwarp(inputImage,inputGCPs, outputImage, wktStringFile, resolution, gdalformat)
rsgislib.imageregistration.triangularwarp(inputimage, inputgcps, outputimage, wktStringFile, resolution, gdalformat, transformImage=False)

Warp image from tie points using triangular interpolation.

Where:

  • inputimage is a string providing the input image.
  • inputgcps is a string providing the input text file containing the tie points.
  • outputimage is a string providing the output image.
  • wktStringFile is a file path to a text file containing the WKT string to use for the warped image.
  • resolution is a float providing the resolution of the output file
  • gdalformat is a string providing the output format (e.g., KEA).
  • transformImage is a bool, if set to true will generate an image providing the transform for each pixel, rather than warping the input image

Example:

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_twarp.kea'
wktStringFile = './Vectors/injune_p142_crowns_utm.prj'
resolution = 1
gdalformat = 'KEA'
imageregistration.triangularwarp(inputImage,inputGCPs, outputImage, wktStringFile, resolution, gdalformat)
rsgislib.imageregistration.polywarp(inputimage, inputgcps, outputimage, wktStringFile, resolution, polyOrder, gdalformat, transformImage=False)

Warp image from tie points using a polynomial interpolation.

Where:

  • inputimage is a string providing the input image.
  • inputgcps is a string providing the input text file containing the tie points.
  • outputimage is a string providing the output image.
  • wktStringFile is a file path to a text file containing the WKT string to use for the warped image.
  • resolution is a float providing the resolution of the output file
  • polyOrder is an int specifying the order of polynomial to use.
  • gdalformat is a string providing the output format (e.g., KEA).
  • transformImage is a bool, if set to true will generate an image providing the transform for each pixel, rather than warping the input image

Example:

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_polywarp.kea'
wktStringFile = './Vectors/injune_p142_crowns_utm.prj'
resolution = 1
polyOrder = 3
gdalformat = 'KEA'
imageregistration.polywarp(inputImage,inputGCPs, outputImage, wktStringFile, resolution, polyOrder, gdalformat)
rsgislib.imageregistration.applyOffset2Image(inputImage, outputImage, gdalformat, gdaltype, xOff, yOff)

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

Where:

  • inputImage is a string providing the input image.
  • outputImage is a string providing the output image.
  • gdalformat is a string providing the output format (e.g., KEA).
  • gdaltype is a rsgislib.TYPE_* value providing the output data type.
  • xOff is a float specifying the X offset to be applied to the image.
  • yOff is a float specifying the Y offset to be applied to the image.

Example:

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.applyOffset2Image(inputImage, outputImage, gdalformat, datatype, -3.0, -3.0)
rsgislib.imageregistration.warpUseGCPsWithGDAL(inRefImg, inProcessImg, outImg, gdalFormat, interpMethod, useTPS=False, usePoly=True, polyOrder=3, useMutliThread=False)

A utility function to warp an image file (inProcessImg) 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 (inRefImg).

Where:

  • inRefImg is the input reference image to which the processing image is to resampled to.
  • inProcessImg is the image which is to be resampled.
  • outImg is the output image file.
  • gdalFormat is the gdal format for the output image.
  • interpMethod is the interpolation method used to resample the image [bilinear, lanczos, cubicspline, nearestneighbour, cubic, average, mode]
  • useTPS is a boolean specifying that the thin plated splines method of warping should be used (i.e., rubbersheet); Default False.
  • usePoly is a boolean specifying that a polynomial method of warpping is used; Default True
  • polyOrder is the order of the polynomial used to represent the transformation (1, 2 or 3). Only used if usePoly=True
  • useMutliThread is a boolean specifying whether multiple processing cores should be used for the warpping.

Other

rsgislib.imageregistration.gcp2gdal(inputimage, inputgcps, outputimage, gdalformat, datatype)

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

Where:

  • inputimage is a string providing the input image.
  • inputgcps is a string providing the input text file containing the tie points.
  • outputimage 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.

Example:

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.gcp2gdal(inputImage,inputGCPs, outputImage, gdalformat, gdaltype)