STScI Logo

xregister images.immatch


NAME · USAGE · PARAMETERS · DESCRIPTION · CURSOR_COMMANDS · ALGORITHMS
EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

xregister -- register 1 and 2D images using X-correlation techniques

USAGE

xregister input reference regions shifts

PARAMETERS

input
The list of input images to be registered.
reference
The list of reference images to which the input images are to be registered. The number of reference images must be one or equal to the number of input images.
regions
The list of reference image region(s) used to compute the x and y shifts. Regions may be: 1) a list of one or more image sections separated by whitespace, 2) the name of a text file containing a list of one or more image sections separated by whitespace and/or newlines, 3) a string of the form "grid nx ny" defining a grid of nx by ny equally spaced and sized image sections spanning the entire image. Shifts are computed for each specified region individually and averaged to produce the final x and y shift.
shifts
The name of the text file where the computed x and y shifts are written. If databasefmt is "yes", a single record containing the computed x and y shifts for each image region and the final average x and y shift is written to a text database file for each input image. If databasefmt = "no", a single line containing the image name and the final average x and y shift is written to a simple text file for each input image.
output = ""
The list of output shifted images. If output is the NULL string then x and y shifts are computed for each input image and written to shifts but no output images are written. If output is not NULL then the number of output images must equal the number of input images.
databasefmt = yes
If databasefmt is "yes the results are written to a text database file, otherwise they are written to a simple text file.
records = ""
The list of records to be written to or read from shifts for each input image. If records is NULL then the output or input record names are assumed to be the names of the input images. If records is not NULL then the record names in records are used to write / read the records. This parameter is useful for users who, wish to compute the x and y shifts using images that have been processed in some manner (e.g. smoothed), but apply the computed x and y shifts to the original unprocessed images. If more then one record with the same name exists in shifts then the most recently written record takes precedence. The records parameter is ignored if databasefmt is "no".
append = yes
Append new records to an existing shifts file or start a new shifts file for each execution of XREGISTER? The append parameter is ignored if databasefmt is "no".
coords = ""
An optional list of coordinates files containing the x and y coordinates of an object in the reference image on the first line and the x and y coordinates of the same object in the input image(s) on succeeding lines. The number of coordinate files must be equal to the number of reference images. The input coordinates are used to compute initial values for the x and y lags between the input image and the reference image, and supersede any non-zero values of xlag , ylag , dxlag , and dylag supplied by the user.
xlag = 0, ylag = 0
The initial x and y lags of the input image with respect to the reference image. Positive values imply that the input image is shifted in the direction of increasing x and y values with respect to the reference image. Xlag and ylag are overridden if an offset has been determined using the x and y coordinates in the coords file.
dxlag = 0, dylag = 0
The increment in xlag and ylag to be applied to successive input images. If dxlag and dylag are set to INDEF then the computed x and y lags for the previous image are used as the initial x and y lags for the current image. This option is useful for images which were taken as a time sequence and whose x and y the shifts increase or decrease in a systematic manner. Dxlag and dylag are overridden if an offset has been determined using x and y coordinates in the coords file.
background = none
The default background function to be subtracted from the input and reference image data in each region before the cross-correlation function is computed. The options are:
none
no background subtraction is done.
mean
the mean of the reference and input image region is computed and subtracted from the image data.
median
the median of the reference and input image region is computed and subtracted from the data.
plane
a plane is fit to the reference and input image region and subtracted from the data.

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.

border = INDEF
The width of the border region around the input and reference image data regions used to compute the background function if background is not "none". By default the entire region is used.
loreject = INDEF, ls hireject = INDEF
The k-sigma rejection limits for removing the effects of bad data from the background fit.
apodize = 0.0
The fraction of the input and reference image data endpoints in x and y to apodize with a cosine bell function before the cross-correlation function is computed.
filter = none
The spatial filter to be applied to the reference and input image data before the cross-correlation function is computed. The options are:
none
no spatial filtering is performed.
laplace
a Laplacian filter is applied to the reference and input image data.
correlation = discrete
The algorithm used to compute the cross-correlation function. The options are:
discrete
The cross-correlation function is calculated by computing the discrete convolution of the reference and imput image regions over the x and y window of interest. This technique is most efficient method for small cross-correlation function x and y search windows.
fourier
The cross-correlation function is calculated by computing the convolution of the reference and input image regions using Fourier techniques. This technique is the most efficient method for computing the cross-correlation function for small x and y search windows.
difference
The cross-correlation function is calculated by computing the error function of the reference and input images as a function of position in the x and y search window.
file
No cross-correlation function is computed. Instead the previously computed x and y shifts are read from record record in the text database file shifts if databasefmt is "yes", or the next line of a simple text file if databasefmt is "no".
xwindow = 11, ywindow = 11
The x and y width of the cross-correlation function region to be computed and/or searched for peaks. The search window corresponds to shifts of - xwindow / 2 <= xshift <= xwindow /2 and - ywindow / 2 <= yshift <= ywindow / 2. Xwindow and ywindow are automatically rounded up to the next nearest odd number.
function = centroid
The algorithm used to compute the x and y position of the cross-correlation function peak. The options are:
none
the position of the cross-correlation function peak is set to x and y position of the maximum pixel.
centroid
the position of the cross-correlation function peak is calculated by computing the intensity-weighted mean of the marginal profiles of the cross-correlation function in x and y.
sawtooth
the position of the cross-correlation function peak is calculated by convolving 1D slices in x and y through the cross-correlation function with a 1D sawtooth function and using the point at which the peak is bisected to determine the x and y position of the cross-correlation peak.
parabolic
a 1D parabola is fit to 1D slices in x and y through the cross-correlation function and the fitted coefficients are used to compute the peak of the cross-correlation function.
mark
mark the peak of the cross-correlation function with the graphics cursor. This option will only work if interactive = "yes".
xcbox = 5, ycbox = 5
The width of the box centered on the peak of the cross-correlation function used to compute the fractional pixel x and y center.
interp_type = "linear"
The interpolant type use to computed the output shifted image. The choices are the following:
nearest
nearest neighbor.
linear
bilinear interpolation in x and y.
poly3
third order interior polynomial in x and y.
poly5
fifth order interior polynomial in x and y.
spline3
bicubic spline.
sinc
2D sinc interpolation. Users can specify the sinc interpolant width by appending a width value to the interpolant string, e.g. sinc51 specifies a 51 by 51 pixel wide sinc interpolant. The sinc width input by the user will be rounded up to the nearest odd number. The default sinc width is 31 by 31.
drizzle
2D drizzle resampling. Users can specify the drizzle pixel fractions in x and y by appending values between 0.0 and 1.0 in square brackets to the interpolant string, e.g. drizzle[0.5]. The default value is 1.0. The value 0.0 is increased to 0.001. Drizzle resampling with a pixel fraction of 1.0 in x and y is identical to bilinear interpolation.
boundary_type = "nearest"
The boundary extension algorithm used to compute the output shifted image. The choices are:
nearest
use the value of the nearest boundary pixel.
constant
use a constant value.
reflect
generate a value by reflecting about the boundary.
wrap
generate a value by wrapping around to the opposite side of the image.
constant = 0
The default constant for constant boundary extension.
interactive = no
Compute the cross-correlation function and the shifts for each image interactively using graphics cursor and optionally image cursor input.
verbose
Print messages about the progress of the task during task execution in non-interactive mode.
graphics = "stdgraph"
The default graphics device.
display = "stdimage"
The default image display device.
gcommands = ""
The default graphics cursor.
icommands = ""
The default image display cursor.

DESCRIPTION

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.

CURSOR COMMANDS

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

ALGORITHMS

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 }

EXAMPLES

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

TIME REQUIREMENTS

BUGS

SEE ALSO

rv.fxcor,proto.imalign,images.imcombine,ctio.immatch,center1d,images.imshift


Source Code · Search Form · STSDAS