chipper Documentation

chipper - Subpixel register a point in one image to point in another
chipper is a batch application that could otherwise be implemented
as an interactive application that subpixel registers points in two
images to one another.  If you've ever wanted to see how two arbitrary
points in two images correlate, chipper is your program!  It has the
ability to geometrically transform (project) one chip to match the
geometry of the other image, perform the registration to subpixel
accuracy and then translate the offsets back to the ungeomed space of
the input image.  Of course you can perform subpixel registration
without geoming and also on whole images of differing sizes.  It has
been coded to be very flexible and therefore has many parameters.

One must decide which image is the TRUTH image.  This image is one that
typically will have more than one other image matched to it.  It is
typically viewed as having the most accurate or desireable camera
pointing or its position in a final mosaic with its current geometric
location not subject to change.  The name of this ISIS cube file
should be given in FROMB.  All variable that end in "B" and have a
corresponding varible ending in "A" are associated with this cube file
and all operations thereon.

The other image is the image subject to UPDATE.  The point identified
in this image, when registered to the point in the TRUTH (FROMB) image,
will have its line and sample location adjusted to the results of the
subpixel registration.  The name of this ISIS cube should be provided in
the FROMA parameter.  And all variables that end in "A" with like
variables ending in "B" are associated with this file.  This image's
location related to camera pointing or a final mosaic are subject to
change based upon point refinement with a TRUTH image.  Chip image
subareas are typically subject to geometric transformations
(projections) (GEOMA = "YES") to the TRUTH geometry and will also
typically have its box size unrestricted (RESTA = "NO").  Unrestricted
boxes in a chip result in the maximum of LTOL (lines) or STOL (samples)
pixels to be added to the current size of a box so that total data
coverage is used in each box when computing the subpixel registration
at the cooresponding points of the two chips.

chipper provides several features to the user.  POINTA and POINTB can
be used to specify the line and sample of the UPDATE and TRUTH image
chips, respectively.  These points are mapped to the center pixel
of each chip even when geoming one of the chips.  Differences in
geometric mapping between the two points are compensated for in the
transformation equations so points can be provided that do not directly
map to the line, sample location given the latitude, longitude of a
point.

The user can alternatively provide latitude and longitude coordinates of
the points in both images.  LATLONA and LATLONB can be used to give the
latitude and longitude in the UPDATE and TRUTH images, respectively, to
be converted to a line and sample locatation where the registration will
occur.  These points must be located within image boundaries or the
geometric mapping is likely to fail.  POINTA and POINTB are then
determined by how the latitude and longitude coordinates map to each
image.

chipper furthermore has the ability to derive match points from a single
input POINT{A|B} or LATLON{A|B}.  Only one sample, line or latitude,
longitude coordinate in either image can be provided to chipper.  It
will use camera angles (SPICE) to resolve all remaining values.  Note
that this may have a larger tendency to fail because of unreliable
pointing or SPICE information.  This scenario can be used to determine
pointing error but only if sufficient LTOL and STOL search ranges are
provided to find a solution.  Note that this requires that SPICE be
initialized for both images.

BANDA and BANDB are used to specify which band of a multiband cube is
to be used in the registration process.  This is the absolute band
in FROMA and FROMB, respectively.

chipper can optionally write both image chips used in the registration
after processing to an ISIS cube file.  TOA and TOB should indicate new
file names of the UPDATE and TRUTH chips, respectively, that will be
created and the chip associated with each image written to it as a
single band image cube.  The output chip cubes will contain only the
image subarea that comprises the chip.  This will typically be the size
of MAXBOX at the given line and sample match points for each cube.  If
REST{A|B} is "NO" then the chip will also include further coverage equal
to twice the maximum of LTOL and STOL.  (BE AWARE that when looking at
these two chips in qview, they may have different scales when first
loaded and can throw you off.)

LTOL and STOL should be used to specify the maximum search range in
the two chips to find the best registration.  LTOL is the number of
lines and STOL is the number of samples to shift in all directions
the UPDATE chip about the TRUTH chip.  It is essential that LTOL and
STOL be large enough to find the best registering pixel.  Otherwise
the computation of the subpixel registration will yield wildly varying
results indicated by variations in the reported box solutions.

There will be roughly (MAXBOX-MINBOX+1)/BOXINC chip registrations
attempted for the chips.  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 registration of the chips.

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").

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

chipper will allow the user to forego computation of the subpixel
registration by setting REGISTER="NO".  This is a special feature that
is designed to be used when the caller would simply like to see how
points map to images.  Under this scenario, the user typically will
provide one coordinate in one image and (implicitly) request to have
the other point resolved using camera angles and SPICE.  When ran this
way, POINTA and POINTB are returned in OLDMPT and NEWMPT respectively.

As mentioned before, geometric transformations of one chip to the
geometry of the other is supported.  One cannot geom both chips -
attempting to do so will result in a error.  Typically, the UPDATE chip
is the one subject to geoming.  This is specified by setting
GEOMA = "YES" and GEOMB = "NO".  The default is to not geom either chip.

The TRANSFRM parameter is used to allow the caller to specify which
geometric transform equation to use.  The general form of all equations
is:

  T(1) + T(2)*X + T(3)*Y + T(4)*X*Y

  where X cooresponds to the desired output chip sample and Y is the
        desired output chip line.

There are transforms computed for both line and sample and the inverse
of each one to provide mapping back to ungeomed space.  The inverse is
needed to convert the offsets of a transformed image chip back to actual
line and sample coordinates in ungeomed space.  Currently there are two
geometric transform methods implemented in the match point software.
The Affine transform (TRANSFRM = "AFFINE") is a variation of the above
equation in that essentially the X*Y (T(4)) term is excluded.  This is
an equation of degree 1.  The other method is the old Fit4 algorithm
(TRANSFRM = "FIT4") using the X*Y term.  It has been deemed less
reliable in some situations and therefore the Affine transform is
recommended.  The default transform is the Affine transform.

The processing involved in computing the transform is as follows:

  a)  The match points for both chips are translated to latitude
      and longitude values.

  b)  The latitude and longitude for the match point for the truth
      (not neccessarily TRUTH in this context) is used to find the
      cooresponding line and sample in the geom image.

      The offset between the actual point provided by the user and
      this line, sample is used as the offset in the mapping of the
      geom chip to the truth (one of three offsets required!).

  c)  Next, starting at a box size of MAXBOX plus 2 * MAX(LTOL,STOL)
      if one of the chips is unrestricted, we iterate using a binary
      search algorithm until the corners of the truth box map to
      cooresponding line, sample locations in the geom image.

  d)  Forward transforms are computed for line and sample that convert
      output lines and samples in the projected chip to line, sample
      coordinates in the ungeomed image.

  e)  Scale and rotation differences are computed for the geomed chip.

  f)  Average and maximum pixel errors are computed at the four box
      corners of the geom chip and the center point using the forward
      transforms.

  g)  The error at the center point is applied to the additive component
      of the line and sample transforms (T(1)) to ensure that the users
      point is at the exact center of the geomed chip (second of three
      offsets).

  h)  Compute the inverse transform that converts the line and sample
      locations of geomed space back to original ungeomed image
      coordinates.

  i)  The error at the match point provided by the user is computed
      using the inverse line and sample transforms.  It is then applied
      to the additive components of inverse line and sample transforms
      to ensure a one-to-one mapping of the match point (third of three
      offsets).

Here is visually what the task of a geometric transform must perform:


              Input                           Output

                +1                         +1            +2

          +3             +2                        .
                 .

                                           +3            +4

            +4


"Input" is the raw ungeomed image line and sample locations that is to
be mapped to the "Output" coordinates.  The "." in both illustrations
represent the match point in ungeomed and geomed space.  A "fast"
transform is then applied to the input image to result in the output
image using bilinear interpolation.  Scaling and rotations are also
inherently performed using this technique.

The two chips are subpixel registered and the resulting offsets in each
box apply to geomed space.  This is what you will see when the box set
of solutions are reported in chipper.  If the UPDATE chip is geomed, the
offsets are applied to the match point and the inverse transforms are
used to compute the point in the input image that coorespond to the new
subpixel registered match point.

When the subpixel registration is completed, the original point (POINTA)
and the new point are returned to the calling PDF for the convenience
of the caller.  The original line and sample coordinate in FROMA is
returned in OLDMPT.  The new adjusted point is returned in NEWMPT.
If REGISTER = "NO", then the original POINTA is returned in OLDMPT and
the original POINTB is returned in NEWMPT.  This is primarily for a
case where the caller wishes one or both points to be computed using
latitude and longitude coordinates.

chipper is only limited as to how much memory that it can allocate to
process the input bands.  For large 2-dimensional images, chipper may
have trouble allocating 2 floating point image planes.

The values of LOW and HIGH are used to exclude pixel values from the
computation of the registration.  If the user does not provide values
for these parameters they are set to the minimum and maximum
representable floating point values, respectively.

Programmer: Kris Becker, USGS, Flagstaff, Arizona

Name of cube file for
registration chip POINTA.
This is the point subject
to UPDATE

NONE

Name of cube file for
TRUTH chip POINTB

NONE

Line, Sample coordinate
of point to register
in FROMA. Alternative
to LATLONA

--

Latitude, Longitude
coordinate to register
in FROMA.  Alternative
to POINTA

--

Line, Sample coordinate
of point to register
in FROMB.  Alternative
to LATLONB

--

Latitude, Longitude
coordinate to register
in FROMB.  Alternative
to POINTB

--

Optional name of file to
write the chip in FROMA
used in registration

--

Optional name of file to
write the chip in FROMB
used in registration

--

Maximum pixel misregistration
allowed in LINE dimension

10

Maximum pixel misregistration
allowed in SAMPLE dimension

10

Specifies the minimim
acceptable goodness of
fit/correlation between
the two chips.  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"

Proceed with registration
or just get/report coordinates

"YES"

Geom FROMA chip (Yes,No)

"NO"

Geom FROMB chip (Yes,No)

"NO"

Type of geometric transform
to use (X=Sample, Y=Line):
AFFINE  - Equation of form
          T(1) + T(2)*X           T(3)*Y
FIT4    - Equation of form
          T(1) + T(2)*X           T(3)*Y + T(4)*X*Y

DEFAULT - Either AFFINE or FIT4

"DEFAULT"

Band/image number from the
FROMA chip file that will
be used to calculate the
pixel registration

1

Band/image number from the
FROMB chip file that will
be used to calculate the
pixel registration

1

Size of chip in FROMA is
restricted to current BOXSIZE
rather than including
MAX(LTOL,STOL) extension

"NO"

Size of chip in FROMB is
restricted to current BOXSIZE
rather than including
MAX(LTOL,STOL) extension

"YES"

Lowest value of valid DN

--

Highest value of valid DN

--

Dump a large amount of
information about the
geom chip

"NO"

Returns the original
match point provided
by caller or one computed
by chipper (POINTA)

LOCALA

Returns the new subpixeled
point after the chips have
been registered

LOCALN

ADDITIONAL NOTES:

Parm	Description
FROMA	The name of the ISIS cube file associated with POINTA. This file should be viewed as the UPDATE file. This is the point that will have the result of the registration applied and returned to the caller.
FROMB	The name of the ISIS cube file associated with POINTB. This file should be viewed as the TRUTH file. The point in this file and all other associated entities should be viewed as being "held" or fixed, not subject to change or alteration.
POINTA	The line and sample, respectively, in FROMA of the match point to be registered. This point is the center of the chip that will be registered to POINTB in FROMB. It will be subject to adjustments based upon the result of the subpixel registration of the two chips. This parameter is optional. Alternatively, LATLONA can be used to derive this point from camera angles and SPICE. When used in conjunction with information about the point in FROMB, neither POINTA or LATLONA is required. Only one of POINTA, LATLONA, POINTB or LATLONB need be provided. In this case all other values are derived from whichever one is provided. Note that one cannot specify both POINTA and LATLONA as this can be conflicting information.
LATLONA	Optional latitude and longitude, respectively, coordinates of a point in FROMA. These coordinates can be provided as an alternative to POINTA but cannot be provided in addition to POINTA. Only one parameter can be used but not both.
POINTB	The line and sample, respectively, in FROMB of the match point to be used to register a point in FROMA. This point is the center of the TRUTH chip that will be used to register POINTA in FROMA. This parameter is optional. Alternatively, LATLONB can be used to derive this point from camera angles and SPICE. When used in conjuction with information about the point in FROMA, neither POINTB or LATLONB is required. Only one of POINTA, LATLONA, POINTB or LATLONB need be provided. In this case all other values are derived from whichever one is provided. Note that one cannot specify both POINTB and LATLONB as this can be conflicting information.
LATLONB	Optional latitude and longitude, respectively, coordinates of a point in FROMB. These coordinates can be provided as an alternative to POINTB but cannot be provided in addition to POINTB. Only one parameter can be used but not both.
TOA	[Optional] Name of output file where the chip used in FROMA to compute the subpixel registration is written. This chip can be used to get a visual image of what was actually used in the registration of the FROMA image.
TOB	[Optional] Name of output file where the chip used in FROMB to compute the subpixel registration is written. This chip can be used to get a visual image of what was actually used in the registration of the FROMB image.
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, chipper 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, chipper will assign STOL=5.
GOODFIT	This parameter allows the user to specify a minimum acceptable goodness of fit. If the correlation between the two chips is less that GOODFIT, the no solution will be found and the program returns an error condition. If the correlation coefficient is greater than or equal to GOODFIT, then a solution is derived from the best box from the returned pixel registration parameters. Note that the correlation coefficient will range from 0 to 1 where 0 is the worst fit, 1 is the best fit.
MINBOX	Minimum box size. The smallest box size to be used to compute subpixel registrations for the chip pair. If this parameter is not provided, then it will be set to MAXBOX and only one image coregistration will be computed for the match points.
MAXBOX	Maximum box size. The largest box size to be used to compute subpixel registrations for the chip pair. If this parameter is not given, will be set to the maximum of the lines and samples, which ever is larger, of the FROMA 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 box size.
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 report 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.
REGISTER	The parameter allows the caller to skip subpixel registration of the two chips. It is useful when providing information for only one input file. To skip subpixel registration, set REGISTER = "NO". In this case, chipper will compute the two matchpoints from provided information and return POINTA in the OLDMPT parameter and POINTB in the NEWMPT return parameter. The default is to compute subpixel registration.
GEOMA	This indicates whether the chip in FROMA is to be geomed before trying to subpixel register. This will need to be done if the images are rotated or scaled differently from one another. For IMP images, it is best not to geom.
GEOMB	This indicates whether the chip in FROMB is to be geomed before trying to subpixel register. This will need to be done if the images are rotated or scaled differently from one another. For IMP images, it is best not to geom.
TRANSFRM	Allows the user to select which geometric transform method to use in the geoming of one of the input chips. Forward and inverse transforms are computed for both the line and sample mapping. The general form of all equations is: T(1) + T(2)*X + T(3)*Y + T(4)*X*Y where X is output sample and Y is output line One can use the Affine or Fit4 transform. Affine uses a three term polynomial of degree 1 to model the mapping of output line and sample coordinates to input coordinates. This transform essential does not use the T(4) term. It is set to 0.0 and does not contribute to the mapping. The FIT4 transform uses the the full form of the general equation utilizing the T(4) term. It is computed differently and may be less sound in certain conditions.
BANDA	This parameter selects the BAND/image in the FROMA cube file that will be used to compute the pixel registration.
BANDB	This parameter selects the BAND/image in the FROMB cube file that will be used to compute the pixel registration.
RESTA	This parameter is used to restrict the box around POINTA to a maximum size of the MAXBOX. This concept is extended to each size box used in the course of computing registrations at MINBOX to MAXBOX. Data in the chip in FROMA is restricted to the current box size surrounding POINTA. If RESTA = "NO", then the box size is allowed to be as large as the current box size plus twice the maximum of LTOL and STOL. This is so that the maximum amount of data is used for each registration.
RESTB	This parameter is used to restrict the box around POINTB to a maximum size of the MAXBOX. This concept is extended to each size box used in the course of computing registrations at MINBOX to MAXBOX. Data in the chip in FROMB is restricted to the current box size surrounding POINTB. If RESTB = "NO", then the box size is allowed to be as large as the current box size plus twice the maximum of LTOL and STOL. This is so that the maximum amount of data is used for each 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.
BARF	This parameter, when set to "YES", will report a lot of additional information about the geometric properties of the chip set when GEOM = "YES". It can be quite lengthy and detailed but informative to the inquiring mind.
OLDMPT	This return parameter reports the value of POINTA in the FROMA file used as the center of the chip. It may be redundant if the caller provides POINTA but may be needed if POINTA is derived from an alternative method.
NEWMPT	This return parameter reports the value of the adjusted POINTA after successful subpixel registration of the two chips. It is the point in FROMA that is produced from the subpixel registration result with the point in FROMB. If REGISTER = "YES", the new point is returned. If REGISTER = "NO", then NEWMPT will return POINTB. This duality is provided for cases where testing of camera pointing and SPICE is desired. POINTA will always be returned in OLDMPT. POINTB is returned in NEWMPT only when REGISTER = "NO", otherwise it returns an updated POINTA.