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:

Parameters

  • 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 warping.

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:

Parameters

  • reference – is a string providing reference image which to which the floating image is to be registered.n:param 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:

Parameters

  • reference – is a string providing reference image which to which the floating image is to be registered.n:param 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:

Parameters

  • 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:

Parameters

  • 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:

Parameters

  • 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:

Parameters

  • 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:

Parameters

  • 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 warping.

Other

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

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

Where:

Parameters

  • 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)