| xregister | images.immatch | xregister |
xregister -- register 1 and 2D images using X-correlation techniques
xregister input reference regions shifts
By default the cross-correlation function is computed in a manner which removes the mean intensity in the reference and input image regions from the data. For many data sets this "correction" is sufficient to remove first order background level effects from the computed cross-correlation function and no additional background subtraction is required.
XREGISTER computes the x and y shifts required to register a list of input images input to a list of reference images reference using cross-correlation techniques. The computed x and y shifts are stored in the text file shifts , in the records records if databasefmt is "yes" or a single line of a simple text file if databasefmt is "no". One entry is made in the shifts file for each input image. If a non NULL list of output images output is supplied a shifted output image is written for each input image. XREGISTER is intended to solve 1D and 2D image registration problems where the images have the same size, the same pixel scale, are shifted relative to each other by simple translations in x and y, and contain one or more extended features in common that will produce a peak in the computed cross-correlation function.
The reference image regions used to compute the cross-correlation function shifts are defined by the parameter regions . Regions may be: 1) a list of one or more image sections, e.g. "[100:200,100:200] [400:500,400:500]" separated by whitespace, 2) the name of a text file containing a list of one or more image sections separated by whitespace and / or newline characters, or, 3) a string of the form "grid nx ny" specifying a grid of nx by ny image sections spanning the entire reference image. All reference image regions should be chosen so as to include at least one well-defined object or feature. Cross-correlation functions and x and y shifts are computed independently for each reference image region and averaged to produce the final x and y shift for each input image.
By default the initial x and y lags between the input and reference image are assumed to by 0.0 and 0.0 respectively and each reference image region is cross-correlated with the identical region in the input image, e.g reference image region [100:200,100:200] is cross-correlated with input image region [100:200,100:200].
Non-zero initial guesses for the x and y shifts for each input image can be input to XREGISTER using the coordinates file parameter coords . Coords is a simple text file containing the x and y coordinates of a single object in the reference image in columns one and two of line one, and the x and y coordinates of the same object in the first input image in columns one and two of line two, etc. If coords is defined there must be one coordinate file for every reference image. If there are fewer lines of text in coords than there are numbers of reference plus input images, then x and y shifts of 0.0 are assumed for the extra input images. For example, if the user specifies a single input and reference image, sets the regions parameter to "[100:200,100:200]", and defines a coordinates file which contains the numbers 50.0 50.0 in columns one and two of line one, and the numbers 52.0 and 52.0 in columns one and two of line two, then the initial x and y lags for the input image with respect to the reference image will be 2.0 and 2.0 respectively, and the reference image region [100:200,100:200] will be cross-correlated with the input image region [102:202,102:202].
If coords is NULL, the parameters xlag , ylag , dxlag , and dylag can be used to define initial x and y lags for each input image. Xlag and ylag define the x and y lags of the first input image with respect to the reference image. In the example above they would be set to 2.0 and 2.0 respectively. Initial shifts for succeeding images are computed by adding the values of the dxlag and dylag parameters to the values of xlag and ylag assumed for the previous image. If dxlag and dylag are 0.0 and 0.0 the same initial x and y lag will be used for all the input images. If dxlag and dylag are both finite numbers then these numbers will be added to the x and y lags assumed for the previous image. If these numbers are both INDEF then the computed x and y lags for the previous image will be used to compute the initial x and y lags for the current image. Both options can be useful for time series images where the x and y shifts between successive images display some regular behavior.
Prior to computing the cross-correlation function large mean background values and gradients should be removed from the input and reference image data as either can seriously degrade the peak of the cross-correlation function. To first order XREGISTER computes the cross-correlation function in a manner which removes the effect of large mean background values from the resulting function. For many if not most typical data sets the user can safely leave the parameter background at its default value of "none" and achieve reasonable results. For more demanding data sets the user should experiment with the "mean", "median", and "plane" background fitting algorithms which compute and subtract, the mean value, median value, and a plane from the input and reference image data respectively, before computing the cross-correlation function. The region used to compute the background fitting function can be restricted to a border around the reference and input image regions by setting the border parameter. Bad data can be rejected from the background fit by setting the loreject and hireject parameters.
A cosine bell function can be applied to the edges of the input and reference image data before computing the cross-correlation function by setting the apodize parameter.
If the filter parameter is set to "laplace" instead of its default value of "none" then a Laplacian filter is applied to the input and reference image data before the cross-correlation function is computed. This spatial filtering operation effectively removes both a background and a slope from the input and reference image data and highlights regions of the image where the intensity is changing rapidly. The effectiveness of this filtering operation in sharpening the correlation peak depends on the degree to which the intensity in adjacent pixels is correlated.
The cross-correlation function for each region is computed by discrete convolution, correlation = "discrete", Fourier convolution, correlation = "fourier", or by computing the error function, correlation = "difference". The x and y lag space in pixels around the initial x and y lag over which the cross-correlation function is searched for the correlation peak, is specified by the xwindow and ywindow parameters. These parameter define a range of x and y lags from -xwindow / 2 to xwindow / 2 and -ywindow / 2 to ywindow / 2 respectively. For a given input and reference image region, the execution time of XREGISTER will depend strongly on both the correlation algorithm chosen and the size of the search window. In general users should use discrete or difference correlation for small search windows and fourier correlation for large search windows.
The x and y lags for each input and reference image region are computed by computing the position of the peak of the cross-correlation function in the search window using one of the four centering algorithms: "none", "centroid", "sawtooth", and "parabolic".
The computed x and y shifts for each region and the final x and y shift for each input image (where the computed x and y shifts are just the negative of the computed x and y lags) are written to the shifts file shifts . If databasefmt is "yes" each results is written in a record whose name is either identical to the name of the input image or supplied by the user via the records parameter . If databasefmt is "no", then a single containing the input image name and the computed x and y shifts is written to the output shifts file.
If a list of output image names have been supplied then the x and y shifts will be applied to the input images to compute the output images using the interpolant type specified by interp_type and the boundary extension algorithm specified by boundary and constant .
If the correlation parameter is set to "file" then the shifts computed in a previous run of XREGISTER will be read from the shifts file and applied to the input images to compute the output images. If no record list is supplied by the user XREGISTER will for each input image search for a record whose name is the same as the input image name. If more than one record of the same name is found then the most recently written record will be used.
XREGISTER does not currently trim the input images but it computes and prints the region over which they all overlap in the form of an image section. Although XREGISTER is designed for use with same sized images, it may be used with images of varying size. In this case it is possible for the calculated overlap region to be vignetted, as XREGISTER currently preserves the size of the input image when it shifts it. For example if an image is much smaller than the reference image it is possible for the image to be shifted outside of its own borders. If the smallest image is used as a reference this will not occur. If vignetting is detected the vignetted image section is printed on the screen. Vignetting may also occur for a list of same-sized images if the reference image is not included in the input image list, and the computed shifts are all positive or negative as may occur in a time sequence. Choosing a reference image with a shift which is in the middle of the observed range of shifts in x and y will remove this problem.
In non-interactive mode the parameters are set at task startup and the input images are processed sequentially. If the verbose flag is set messages about the progress of the task are printed on the screen as the the task is running.
In interactive mode the user can mark the regions to be used to compute the cross-correlation function on the image display, define the initial shifts from the reference image to the input image on the image display, show/set the data and algorithm parameters, compute, recompute, and plot the cross-correlation function, experiment with the various peak fitting algorithms, and overlay row and column plots of the input and reference images with and without the initial and / or computed shifts factored in.
The following graphics cursor commands are currently available in XREGISTER.
Interactive Keystroke Commands
? Print help
: Colon commands
t Define the offset between the reference and the input image
c Draw a contour plot of the cross-correlation function
x Draw a column plot of the cross-correlation function
y Draw a line plot of the cross-correlation function
r Redraw the current plot
f Recompute the cross-correlation function
o Enter the image overlay plot submenu
w Update the task parameters
q Exit
Colon Commands
:mark Mark regions on the display
:show Show the current values of the parameters
Show/Set Parameters
:reference [string] Show/set the current reference image name
:input [string] Show/set the current input image name
:regions [string] Show/set the regions list
:shifts {string] Show/set the shifts database file name
:coords [string] Show/set the current coordinates file name
:output [string] Show/set the current output image name
:records [string] Show/set the current database record name
:xlag [value] Show/set the initial lag in x
:ylag [value] Show/set the initial lag in y
:dxlag [value] Show/set the incremental lag in x
:dylag [value] Show/set the incremental lag in y
:cregion [value] Show/set the current region
:background [string] Show/set the background fitting function
:border [value] Show/set border region for background fitting
:loreject [value] Show/set low side k-sigma rejection
:hireject [value] Show/set high side k-sigma rejection
:apodize [value] Show/set percent of end points to apodize
:filter [string] Show/set the default spatial filter
:correlation [string] Show/set cross-correlation function
:xwindow [value] Show/set width of correlation window in x
:ywindow [value] Show/set width of correlation window in y
:function [string] Show/set correlation peak centering function
:xcbox [value] Show/set the centering box width in x
:ycbox [value] Show/set the centering box width in y
The following submenu of image cursor commands is also available.
Image Overlay Plot Submenu ? Print help c Overlay the marked column of the reference image with the same column of the input image l Overlay the marked line of the reference image with the same line of the input image x Overlay the marked column of the reference image with the x and y lagged column of the input image y Overlay the marked line of the reference image with the x and y lagged line of the input image v Overlay the marked column of the reference image with the x and y shifted column of the input image h Overlay the marked line of the reference image with the x and y shifted line of the input image q Quit Image Overlay Sub-menu Colon Commands :c [m] [n] Overlay the middle [mth] column of the reference image with the mth [nth] column of the input image :l [m] [n] Overlay the middle [mth] line of the reference image with the mth [nth] line of the input image :x [m] Overlay the middle [mth] column of the reference image with the x and y lagged column of the input image :y [m] Overlay the middle [mth] line of the reference image with the x and y lagged line of the input image :v [m] Overlay the middle [mth] column of the reference image with the x and y shifted column of the input image :h [m] Overlay the middle [mth] line of the reference image with the x and y shifted line of the input image
The cross-correlation function is computed in the following manner. The symbols I and R refer to the input and reference images respectively.
correlation = discrete
<I> = SUMj SUMi { I[i+xlag,j+ylag] } / (Nx * Ny)
<R> = SUMj SUMi { R[i,j] } / (Nx * Ny)
sumsqI = sqrt (SUMj SUMi { (I[i+xlag,j+ylag] - <I>) ** 2 })
sumsqR = sqrt (SUMj SUMi { (R[i,j] - <R>) ** 2 })
X = SUMj SUMi { (I[i+xlag,j+ylag] - <I>) * (R[i,j] - <R>) }
----------------------------------------------------
sumsqI * sumsqR
correlation = fourier
<I> = SUMj SUMi { I[i,j] } / (Nx * Ny)
<R> = SUMj SUMi { R[i,j] } / (Nx * Ny)
sumsqI = sqrt (SUMj SUMi { (I[i,j] - <I>) ** 2 })
sumsqR = sqrt (SUMj SUMi { (R[i,j] - <R>) ** 2 })
FFTI = FFT { (I - <I>) / sumsqI }
FFTR = FFT { (R - <R>) / sumsqR }
X = FFTINV { FFTR * conj { FFTI } }
correlation = difference
<I> = SUMj SUMi { I[i+xlag,j+ylag] } / (Nx * Ny)
<R> = SUMj SUMi { R[i,j] } / (Nx * Ny)
X = SUMj SUMi { abs ((I[i+xlag,j+ylag] - <I>) - (R[i,j] - <R>)) }
X = 1.0 - X / max { X }
1. Register a list of images whose dimensions are all 256 by 256 pixels and whose shifts with respect to the reference image are all less than 5.0 pixels, using the discrete cross-correlation algorithm and a search window of 21 pixels in x and y.
cl> xregister @inimlist refimage [*,*] shifts.db out=@outimlist \ xwindow=21 ywindow=21
2. Register the previous list of images, but compute the cross_correlation function using boxcar smoothed versions of the input images.
cl> xregister @binimlist brefimage [*,*] shifts.db xwindow=21 \ ywindow=21 cl> xregister @inimlist refimage [*,*] shifts.db out=@outimlist \ records=@binimlist correlation=file
3. Register the previous list of images but write the results to a simple text file instead of a text database file and do the actual shifting with the imshift task.
cl> xregister @binimlist brefimage [*,*] shifts.db xwindow=21 \ ywindow=21 databasefmt- cl> fields shifts.db 2,3 > shifts cl> imshift @inimlist @outimlist shifts_file=shifts
4. Register list of 512 by 512 pixel square solar sunspot images that were observed as a time series. Compute the cross-correlation function using Fourier techniques, a search window of 21 pixels in x and y, an initial shift of 10 pixels in x and 1 pixel in y, and use the computed shift of the previous image as the initial guess for the current image.
cl> xregister @inimlist refimage [*,*] shifts.db out=@outimlist \ xlag=10 ylag=1 dxlag=INDEF dylag=INDEF correlation=fourier \ xwindow=21 ywindow=21
5. Register two 2K square images interactively using discrete cross-correlation and an initial search window of 15 pixels in x and y.
cl> display refimage cl> xregister inimage refimage [900:1100,900:1100] shifts.db \ xwindow=15 ywindow=15 interactive+ ... a contour plot of the cross-correlation function appears with the graphics cursor ready to accept commands ... type x and y to get line and column plots of the cross- correlation function at various points and c to return to the default contour plot ... type ? to get a list of the available commands ... type :mark to mark a new region on the image display ... type f to recompute the cross-correlation function using the new data ... increase the search window to 21 pixels in x and y with the :xwindow 21 and :ywindow 21 commands ... type f to recompute the cross-correlation function with the new search window ... type o to enter the image data overlay plot submenu, move the cursor to a line in the displayed reference image and type l to see of plot of the line in the input and reference image, type h to see a plot of the same line in the reference image and the x and y shifted line in the input image, type q to return to the main menu ... type q to quit the task, and q again to verify the previous q command
rv.fxcor,proto.imalign,images.imcombine,ctio.immatch,center1d,images.imshift