coreg2 Documentation

coreg2 - 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.

There will be roughly (MAXBOX-MINBOX+1)/BOXINC chip registrations
attempted for the image.  They are then evaluated to determine which
one is the best registering box at the subpixel level.  This is done
by finding the box that satifies the selected BESTBOX method of
evaluating the resulting registrations for the image.

Both MINBOX and MAXBOX need not be specified by the user.  If this
is the case, then only one coregistration is performed and it is
done on the entire image size.  Specifying MINBOX and not MAXBOX will
result in MAXBOX being set to the maximum size of lines or samples
and the using BOXINC to determine how many boxes will be registered
in the range from MINBOX to MAXBOX.  If only MAXBOX is specified,
then MINBOX is set to MAXBOX and only one image coregistration is
performed limiting the image dimensions to MAXBOX square pixels.
For cases where only one box is computed, BESTBOX values have
little meaning as it is the only one considered ("BESTTOL").

The registration boxes are centered on the center of the FROM
image, i.e., LINE/2, SAMPLE/2.  The first image "chip" computed is
MINBOX in size.  Subsequent registration boxes are sized by
increments of BOXINC from MINBOX until the size of the box is greater
than MAXBOX.  Registrations are then terminated and the best fitting
box size is determined.  This is then used to shift the FROM image
cube (all bands) to spatially register it (them) to the FROM2 image.

Correlations can sometimes fluctuate up and down as the box size
decreases.  Hence, the best box is one that either has the highest
occuring correlation (BESTBOX="HIGH") or the last occuring
(BESTBOX="LAST", i.e., smallest-sized box) until all the boxes are
evaluated or a correlation coefficient drops below GOODFIT as specified
by the user.  Hence it is recomended to keep this value relatively
high, close to 1.0 (the maximum correlation indicating perfect
correlation).  The BESTBOX="AVERAGE" option is computed by using
all boxes that are greater than or equal to the GOODFIT and averaging
the line and sample offsets and the correlation coefficient.  These
averages are returned to the user as the solution.  On the other
hand, the BESTBOX="NEARAVG" option also computes the average of all
boxes with an acceptable level of tolerance but returns the box
that is nearest the average.  This option checks the absolute value
of difference between BOTH the line and sample offsets from the
average and returns the one closest.  The "BESTTOL" option is much
simpler as it simple scans through all boxes and finds the box
with the highest tolerance (correlation value sometimes referred
to as "R") greater than or equal to GOODFIT.  The "BESTFIT" option
uses the Chi-Square value of the least square difference.  This
option chooses the box with smallest chi-square value with the
correlation coefficient greater than or equal to GOODFIT.  Chi-Square
is defined to be the sum of the square of the difference between
the actual data and the modeled data.  This is most likely a
better indicator of a good least square model than the correlation
coefficient, R.

Note that the subpixel correlation coefficient is computed based
upon a mathematical model of the surface created by surrounding
correlations of the best registering whole pixel.  The surface
maximum is found and where this occurs is theoretically the location
of the line and sample of the best registering subpixel.  The
subpixel correlation coefficient can fluctuate above and below the
best registering whole pixel correlation based upon sensitivity of
the model to the data.  Because of this, the maximum of the subpixel
and best whole pixel correlation is used as a single representation
of the correlation coefficient for the current box.  Also, note that
the best registering box sample and line offsets cannot exceed the
value of MAX(STOL,LTOL) as specified by the user or it will be rejected.
This restricts the maximum amount the point can be moved in any
direction.  If you do not wish to apply this restriction, simply set
it to a value greater than the maximum of STOL or LTOL.  Furthermore,
if any shift in line exceeds LTOL or sample exceeds STOL, the box is
rejected regardless of correlation.  This would indicate the the
search range needs to be expanded to get a good registration result.

coreg2 is only limited as to how much memory that it can allocate to
process the input bands.  For large 2-dimensional images, coreg2 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).

coreg2 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.

CHISQ, R, ADD, MULT and DYX parameters are so coreg2 can be run from
within a procedure PDF and returns the output parameters of coreg2 to
the calling PDF.  This is set up so that coreg2 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 coreg2 directly, do not
modify the values of CHISQ, R, ADD, MULT, DYX, AVE, AVE2, STD, STD2,
and NPTS.

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
Starting sample to compute
pixel registration

10

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

0.0

Minimum box size

--

Maximum box size

--

Box size increment

1

Selects which box to use as
the best correlating box:
LAST    - Pick the last
          occuring box above
          GOODFIT
HIGH    - Pick the highest
          correlating box
          of all boxes above
          GOODFIT
AVERAGE - Compute the average
          of all boxes with a
          correlation
          coefficient greater
          than or equal to
          GOODFIT
NEARAVG - Same as AVERAGE but
          returns the actual box
          that is closest to
          this average
BESTTOL - Selects the box that
          has the highest sub-
          pixel correlation
          value (GOODFIT)
BESTFIT - Selects the box that
          has the lowest Chi-
          Square value, an
          indicator of how
          well the data fits
          the least square
          model.

"BESTTOL"

Starting line to compute
pixel registration

Starting sample to compute
pixel registration

Number of samples to use
for pixel registration

Number of lines to use
for pixel registration

Line increment for the box
LINC=0 will result in
LINC set to NLINES

Sample increment for the box
SINC=0 will result in
SINC set to NSAMPS

Geom data (Yes,No)

"NO"

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

--

Fraction of data to use
in statistical sampling

0.0

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 level of pixel
registration to apply
SUBPIXEL - sub-pixel level
PIXEL    - pixel level

"SUBPIXEL"

Name of text file to append
result of registration

--

Chi-square value of the
correlation computed for
the two images

LOCAL0

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

Returns the average of the FROM
image at the best fitting whole
pixel solution

LOCAL5

Returns the average of the FROM2
image at the best fitting whole
pixel solution

LOCAL6

Returns the standard deviation
of the FROM image at the best
fitting whole pixel solution

LOCAL7

Returns the standard deviation
of the FROM2 image at the best
fitting whole pixel solution

LOCAL8

Returns the number of pixels
used in the statistics for
AVE, AVE2, STD and STD2.

LOCAL9

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 coreg2. Will be the same pixel type as the input file. (Default extenstion is .cub) Note that this parameter need not be specified. For this case, only the coregistration values are computed and the application terminates normally. This option is commonly used to simply acquire the coregistration and apply it in later processing. 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, coreg2 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, coreg2 will assign STOL=5.
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 GOODNES, 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. This parameter is very useful for simply testing correlation between two images. This can be easily achieved setting GOODFIT to any value greater than 1.0 (GOODFIT=2.0).
MINBOX	Minimum box size. The smallest box size to be used to compute subpixel registrations for the image pair. If this parameter is not provided, then it will be set to MAXBOX and only one image coregistration will be computed at the center of the image.
MAXBOX	Maximum box size. The largest box size to be used to compute subpixel registrations for the image pair. If this parameter is not given, will be set to the maximum of the lines and samples, which ever is larger, of the FROM image.
BOXINC	Specifies the increment of the "chip" box from MINBOX to MAXBOX. BOXINC=1 will compute a chip registration at every size box from MINBOX to MAXBOX. It can increment in any whole number greater than 0. The first "chip" registered will be done using MINBOX as the square size of the box. Each subsequent registration chip will be incremented by BOXINC and computed until the size of the box exceeds MAXBOX. Then all the boxes are evaluated to determine the best registering chip.
BESTBOX	This parameter allows the user to choose which box is the best representation of a match. "LAST" will select the last occuring box in the first occuring span of registration correlations above GOODFIT. This cooresponds to the smallest box size in that span. "HIGH" will select the highest correlating box of all registrations in the first occuring span of value above GOODFIT. This is not always, or necessarily, the smallest box size. The "AVERAGE" option is computed using all boxes that have a correlation coefficient greater than or equal to GOODFIT. The average line and sample offsets are computed as well as the average of the correlation coefficient. The "NEARAVG" option is similar to the "AVERAGE" option except the actual box that is closest to the average is returned. This box is determined by the smallest absolute difference of the sums of both the line and sample offsets from the average. Note that the "AVERAGE" option will generate a completely separate box. With this option, the selected box will always show up in the SUCFILE as the last box indicated as the one selected. It will inherit many characteristics of the box nearest to this average as defined by the "NEARAVG" option. The "BESTTOL" option will select the box that has the highest tolerance value. The highest possible value that can be attained is 1.0 indicating perfect correlation between the two chips. It will only consider correlation coefficients greater than or equal to GOODFIT selecting the box with the highest GOODFIT value. It considers all boxes. The "BESTFIT" option will select the box that has the lowest Chi-Square value. Chi-Square is an indicator of how well the data fits the least square fit model. It is defined as the mean difference between the observed data and the least square model of the data at each point. A lower value indicates a better model. All boxes must also have a correlation coefficient greater than or equal to GOODFIT. Note that the "BESTTOL" and "BESTFIT" options will not always return the same box but will more times than not.
LINE	Specifies the starting line in BOTH input cubes where the registration is to be computed. Together with NLINES this determines the height of the box.
SAMP	This parameter specifies the starting sample in BOTH input cubes. Together with NSAMPS, this will determine the width of the box to use to register the two images.
NLINES	This specifies the number of lines in each box used to compute the registration.
NSAMPS	This specifies the number of samples in each box used to compute the registration.
LINC	Line increment for the box. This value is the amount of line each registration box is moved down the image. This value may be used to define overlapping boxes or a single box in the line dimension. If LINC = 0, then it will be set to the value of NLINES.
SINC	Sample increment for the box. This value is the amount of samples each registration box is moved across the image. This value may be used to define overlapping boxes or a single box in the sample dimension. If SINC = 0, then it will be set to the value of NSAMPS.
GEOM	This indicates whether the data needs to be geomed before trying to subpixel register. This will need to be done if the images are rotated from each other. For IMP images, it is best not to geom. Note that the truth point chip is always held fixed. The point being registered to the truth point is always the one that has the "fast" geometric transform applied to match truth point geometry.
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.
SAMPLING	This parameter specifies the fraction of common image data overlap that will used to compute the registration coefficients. Valid values range greater than 0.0 to 1.0. A value of 1.0 will result in usage of all possible valid data values. Any other value will be MAXPTS = (SAMPLING * (NLINES * NSAMPS)) as the maximum possible data values to use. Note that values other than 1.0 may actually result in substantially less data values used because of the way the sampling set is determined. There is an offset and increment computed based upon the following formula: IF (MAXPTS .GE. (NL*NS)) THEN INC = 1 INCH = 0 ELSE XINC=SQRT(REAL(NL*NS)/REAL(MAXPTS)) INC=INT(XINC)+1 INCH=INC/2+1 ENDIF Sampling collection loops are as follows: N = 0 DO 101 IL2=INL1+INCH,INL2-INCH,INC DO 101 IS2=INS1+INCH,INS2-INCH,INC IF(RBUF2(IS2,IL2) .LT. DMIN) GO TO 101 IF(RBUF2(IS2,IL2) .GT. DMAX) GO TO 101 IL1=IL2+L IS1=IS2+K IF(RBUF1(IS1,IL1) .LT. DMIN) GO TO 101 IF(RBUF1(IS1,IL1) .GT. DMAX) GO TO 101 C Add the pixel to the points array N=N+1 A1(A1NDX+N)=RBUF1(IS1,IL1) A2(A2NDX+N)=RBUF2(IS2,IL2) 101 CONTINUE where L and K and the current LINE and SAMPLE offset being considered, respectively.
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 coreg2 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").
REGLEV	Allows the user to select the level of pixel registration that will be applied to the image. coreg2 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.
REGFILE	This is the name of the file where the subpixel registration result is written. If it is not given, it will not be recorded. If provided by the user, the current result of the registration will be appended to this file. The result is written in the following format: FROM_IMGID FROM2_IMGID LINE_OFFSET SAMP_OFFSET R COEF_ARRAY Note that the COEF_ARRAY will be ADD and MULT parameters that are returned to the caller's PDF. This number of values that are written is EQORDER+1. If the specified file does not exist, it will be created.
CHISQ	CHISQ is a parameter that will receive the Chi-square value computed by coreg2. This parameter is needed ONLY if coreg2 is run from a procedure PDF an the calling PDF wants the parameters to be returned. This is a single scalar value.
R	R is a parameter that will receive the correlation coefficient computed by coreg2. This parameter is needed ONLY if coreg2 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 coreg2. This parameter is needed ONLY if coreg2 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 coreg2. This parameter is needed ONLY if coreg2 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.
AVE	AVE is a parameter that will receive the average of all the pixels used from the FROM image to compute the coregistration.
AVE2	AVE2 is a parameter that will receive the average of all the pixels used from the FROM2 image to compute the coregistration.
STD	STD is a parameter that will receive the standard deviation of the pixels used from the FROM image to compute the coregistration.
STD2	STD2 is a parameter that will receive the standard deviation of the pixels used from the FROM2 image to compute the coregistration.
NPTS	Returns the total number of points used in the computation of the coregistration at the best registering box. All returned parameters are from this box.