coreg Documentation

coreg - Subpixel registration of a pair of images
The first input image will be subpixel registered to the second input
image.  This program will normally be used on multispectral datasets.
There must be a reasonably strong positive correlation between the
input datasets for the algorithm to work properly.

COREG is only limited as to how much memory that it can allocate to
process the input bands.  For large 2-dimensional images, COREG may
have trouble allocating 2 floating point image planes plus a single
buffer for each side and bottom plane.

All bands from the input cube file (FROM) are spatially adjusted by
the indicated registration.  If the user selected to register to the
best whole pixel (REGLEV="PIXEL"), then the output image will not
be registered at the subpixel level.  A nearest neighbor pixel shift
is performed instead.  This option is useful if further more precise
subpixel corrections are to be made in later processing steps.  It
is better to reduce the amount of pixel averaging because it can
reduce data integrity.   Side, bottom and back backplanes are all
propagated with no modifications directly to the output cube file (TO).

COREG optionally allows the user to also apply the polynomial
coefficients to the output registered pixel.  This, in effect,
adjusts the registered output pixel to approximately the same
brightness levels or also referred to as histogram matching.
If APPLYCO=NO, then only the spatial registration will be
computed.

The values of LOW and HIGH are used to exclude pixel values from the
computation of the registration.  They are, however, processed
(shifted) along with all other pixels and written to the output file.
All input values that are already special pixel values will be
propagated to the output cube unchanged.

R, ADD, MULT and DYX parameters are so COREG can be run from within a
procedure PDF and returns the output parameters of COREG to the
calling PDF.  This is set up so that COREG can still be run as a
stand-alone program as well.  (This is accomplished by setting
these parameters to locally declared parameters that are simply
discarded after the run.) When running COREG directly, do not
modify the values of R, ADD, MULT and DYX.

Programmer: Kris Becker, USGS, Flagstaff, Arizona

File name of the cube
that will be registered

NONE

Subcube specified for
FROM file

--

Second input cube file
name.  Image will be
used to compute the
registration parameters

NONE

Subcube specified for
FROM2 file (Note: this
must select a single
band/image)

"::1"

Output file name

--

Output pixel type

0

Minimum and maximum
output pixel range

0.0,0.0

Maximum pixel misregistration
allowed in LINE dimension

10

Maximum pixel misregistration
allowed in SAMPLE dimension

10

Order of of polynomial fit

1

Band/image number from the
FROM (input) file that will
be used to calculate the
pixel registration

1

Lowest value of valid DN

--

Highest value of valid DN

--

Minimum number points
that can be used to compute
registration

5

Fractional minimum of total
points used to compute
registration

0.0

Apply the returned polynimial
coefficients to the output
cube

"NO"

Specifies the minimim
acceptable goodness of
fit/correlation between
the two images.  Correlation
range is 0 (worst) to 1
(best).

0.0

Specifies level of pixel
registration to apply
SUBPIXEL - sub-pixel level
PIXEL    - pixel level

"SUBPIXEL"

Returns the correlation of
fit computed for the two
images

LOCAL1

Parameter that returns the
additive component

LOCAL2

Array that returns the
multiplicative components

LOCAL3

Two element array that
returns the best registering
subpixel line and sample
offset

LOCAL4

Return parameter for coreg
exit status.  Negative values
indicate fatal error.  A
value of +1 is success.

LOCAL5

ADDITIONAL NOTES:

Parm	Description
FROM	The name of the input cube file. This file will be registered if the correlation is acceptable. (Default extention is .cub)
SFROM	The input subcube specifier. Allows the user to select a subarea of the input cube for processing. The dimensions of the output cube are a function of this specification. The default " " selects the entire cube.
FROM2	The name of the secondary input cube file. This file contains the image that will be used to compute the pixel registration for the input (FROM) file. (Default extention is .cub)
SFROM2	The secondary input subcube specifier. Allows the user to select a subarea of the second (FROM2) input cube for processing. This specifier must select a single band/image and the spatial dimensions of this input file must be equivalent to the input file (FROM). The default "::1" selects all LINES, SAMPLES and the FIRST band from this file.
TO	The output cube file created by COREG. Will be the same pixel type as the input file. Note that if a file name is not provided then one will not be created and only the correlation will be computed and reported. (Default extension is .cub) Example: output
OTYPE	Output pixel data type. Permitted values are: 0 - output type is same as input file pixel type 1 - 8-bit (integer with type conversion parameters) 2 - 16-bit (integer with type conversion parameters) 3 - 32-bit (floating point) When processed data are being written back into the input file, the output pixel type must be the same as the existing pixel type in the input file.
ORANGE	Output pixel data range. If the output pixel type is 1 (8-bit integer with type conversion parameters) or 2 (16-bit integer with type conversion parameters), then the type conversion parameters in the output file will be set to values that allow representing the specified range of output values. Output values outside this range will be stored as the special "representation saturation" value. The ORANGE parameter is ignored if the output pixel type is 3 (32-bit floating point) since type conversion parameters are not applicable to floating point pixel values. If both ORANGE(1) and ORANGE(2) are 0.0, then the type conversion parameters in the output file will automatically be set to represent the minimum and maximum values that the output bit type can store. (The user will be required to supply a specific range for ORANGE if the input pixel type is 3 (32-bit floating point) and the output pixel type is 1 (8-bit with type conversion parameters) or 2 (16-bit with type conversion parameters)).
LTOL	The maximum estimated pixel misregistration in the LINE dimension. LTOL must be greater than zero. If LTOL is less than or equal to zero, COREG will assign LTOL=5.
STOL	The maximum estimated pixel misregistration in the SAMPLE dimension. STOL must be greater than zero. If STOL is less than or equal to zero, COREG will assign STOL=5.
EQORDER	EQORDER is the order of the polynomial equation used. Valid values are 1-8.
BAND	This parameter selects the BAND/image from the input cube file (FROM) that will be used to compute the pixel registration.
LOW	The lowest value of valid DNs. If LOW = 11, then pixels with DN values less than 11 will be excluded from registration computations.
HIGH	The highest value of valid DNs. If HIGH = 200, then values greater that 200 will be excluded from registration computations.
MIN	Specifies the minimum number of points that can be used to compute the pixel registration. This value should be such that a least square fit function can return resonable results. Note that FRAC may also be used to give an additional option on specifying this value. Note, however, that BOTH MIN and FRAC cannot be used. If this case does occur, the value of MIN will be used.
FRAC	This parameter can also be used to specify a fractional miniumum of the total points that can be used to compute the pixel registration. For example, if COREG uses 2000 points maximum to compute the correlation and FRAC is 0.05, then the minimum number of points that can be used is MIN = (0.05 * 2000) = 100. Note, however, that BOTH MIN and FRAC cannot be used. If this case does occur, the value of MIN will be used.
APPLYCO	Specifies that the returned polynomial coeffecients be applied to the output cube. Based upon the order of the equation specified in EQORDER, the output registered pixel will be computed using: DNOUT = COEF(1) + COEF(2)*DNREG^1 + COEF(3)*DNREG^2 + ... COEF(EQORDER+1)*DNREG^EQORDER Note that the coefficients are applied if requested even when whole pixel registration is selected (REGLEV="PIXEL").
GOODFIT	This parameter allows the user to specify a minimum acceptable goodness of fit. If the correlation bewteen the two images is less that GOODFIT, the no output file will be generated and the program returns an error condition. If the correlation coeeficient is greater than or equal to GOODFIT, then an output file will be generated using the returned pixel registration parameters. Note that the correlation coeeficient will range from 0 to 1 where 0 is the worst fit, 1 is the best fit.
REGLEV	Allows the user to select the level of pixel registration that will be applied to the image. coreg always computes the best registering sub-pixel to the best fifth pixel. If REGLEV="SUBPIXEL", sub-pixel registration of up to four surrounding valid pixels will contribute to the output pixel value. If REGLEV="PIXEL", then nearest neighbor whole pixel registration will be performed. Note that this will be the best registering whole pixel as reported after the registration computations.
R	R is a parameter that will receive the correlation coeeficient computed by COREG. This parameter is needed ONLY if COREG is run from a procedure PDF an the calling PDF wants the parameters to be returned. This is a single scalar value.
ADD	ADD is a parameter that will receive the additive component of the COREG. This parameter is needed ONLY if COREG is run from a procedure PDF an the calling PDF wants the parameters to be returned. This is a single scalar value.
MULT	MULT is a parameter that will receive the multiplicative component of the COREG. This parameter is needed ONLY if COREG is run from a procedure PDF an the calling PDF wants the parameters to be returned. This is an array of up to eight values. Note that MULT must be at least as large as EQORDER.
DYX	DYX is a parameter that will receive the best registering sub-pixel offsets in the line and sample, respectively. If the user selects whole pixel registration only (REGLEV="PIXEL"), then this returns the best registering line and sample rather than the sub-pixel offsets.
STATUS	This parameter returns the exit status of the coreg application. It is (hopefully) a temporary fix for a problem with the DEC Alpha Digital Unix version of TAE. It is not getting the proper exit status of the program and it is used extensively in the Clementine decision making image processing activities. Any negative return value for STATUS indicates a program failure. A value of +1 indicates a successful completion of coreg.