pntreg Documentation

pntreg - Subpixel register list of match points
pntreg reads a list of match points and registers each one to a truth
point at the subpixel level.  It also requires a PIC file or a list
of cube files.  This PIC file can be generated from "implab2jig" for
the Imager for Mars Pathfinder (IMP) mission.  For generality, one
can instead provide a list of ISIS cube files in FROMLIST.  One
cannot use both files, however.

Each match point entry in the match point file (MATFROM) will have a
point identifier and image number that uniquely identifies it.  There
can be numerous measurements of a point with the same point id, but
only one with the same point id and image number.  The input file,
whether it be the PIC file (PICFILE) or the list of files (FROMLIST),
should contain all the image cubes that are referred to in the match
point file.  The entire match point file is read in and all cube
files will be opened and labels read for verification.  ALTPATH
can be used to specify an alternative directory where the ISIS
cube image files can be found.

Once all the match points and image cubes are read in, the points are
sorted into point sets.  That is all points that have the same point
id are collected into a set.  Each set is evaluated for the existance
of a "truth" or "ground" point.  This point is denoted in the match
point file with a "T" or "G" class designation in the last column of
the file.  Each point can have any one of the following point class
designations:

   'A' - Approximate point.   Designates simply that the point has
         been identified to be approximately at the same location
         as the truth or ground point.
   'G' - Ground point.  Is a point identified by a publication or in
         literature.  Its coordinates are not subject to change.
   'T' - Truth point.  Designated by the user as a fixed point that
         all other points in the set are to be registered to.
   'M' - Measured point.  Usually denotes a point where previous
         attempts to register it to the truth or ground point have
         not been successful and is accepted as "as good as it
         gets".  This also can be used to designate a point that
         the user has selected and does not wish it to be subjected
         to modification by further processing.
   'S' - Successfully registered point.  Designates a point that
         has been successfully subpixel registered to the truth
         or ground point and was updated as a result of the
         registration.  These points are not subject to further
         modification.
   'U' - Unmeasured point.  The catchall class specifies the point
         has no measurement or is so bad it shouldn't be used.
         These points are not subject to modification unless they
         are reclassified.

Note that "truth" and "ground" points are taken to mean the same thing
in this application.  They are used as the fixed point that all other
points designated as Approximated ("A") are registered to.  Because
of this there can be only one truth or ground point in a set.  A set
cannot contain more than one truth or ground point since it cannot
be determined which is used as the truth.  These sets are reported
and not processed by pntreg.  Only points classified as Approximate
("A") are subpixel registered.  All other points are not modified
by pntreg and are rewritten to the output match point file (MATTO) as
they were read in.

SPECIAL NOTE:  It is extremely important to use the same point as
truth or ground point for the entire life of a point set.  Changing
the truth/ground point and subjecting it to further processing will
undoubtedly yield different results.  If this is deemed necessary,
then all points in the set should be reclassified and re-registered.

pntreg will read the old format of the match point file that did not
have point classification fields.  For this case where no points
are classified, pntreg classifies them all as "A", Approximate.  When
pntreg encounters a point set with no truth and no ground point, it
will determine a truth ("T") point by find the point nearest to but
not exceeding the edge of an image if the user sets SELECT="EDGE" or
uses the point closest to the center (farthest from edge) if they set
SELECT="CENTER".  The "EDGE" selection criteria is recommended over
"CENTER" because it is possible that points really close to the edge
could register off the image.  "EDGE"'ing, however, can make
registering more difficult for points extremely close (within a few
pixels) to the edge because of reduced numbers of pixels used in the
statistics.

Boxes of data surrounding both the truth and registering points are
read from the images identified by image number.  Sometimes referred
to as "chips", the size of the chips are varied based upon minimum and
maximum sizes of the box as provided by the user via MINBOX and MAXBOX,
respectively.  The user can choose which point is restricted in data
coverage by the RESTRICT parameter.  It is recommended that TRUTH be
restricted since data from the approximated point will be shifted in
and correlation should peak when areas in the approximated point are
more like the truth area.  A restricted chip is a chip where the
size never exceeds the evaluating box size in samples and lines.  The
other chip being registered may have as many as BOXSIZE + (2 * STOL)
samples and BOXSIZE + (2 * LTOL) lines.  This is to accomodate the
user specified search/shift range in sample (STOL) and line (LTOL) so
all available pixel data will be shifted into the area of coverage to
achieve maximum statistical quality.  Note that there can always be
less than these nominal chip sizes used when they exceed available
lines and samples due to proximity to image edges.

pntreg supports images that require geometric rectification to the
truth image.  By setting GEOM="YES", pntreg will apply a "fast"
geometric projection of approximated point data into truth image
space prior to chip registration.  All updates will be translated
back to actual image space prior to application and acceptance of
the results.  Setting GEOM="NO" assumes all the images require
no projection and are very simliar in viewing angle and resolution.

There will be roughly (MAXBOX-MINBOX+1)/BOXINC chip registrations
attempted for each point.  They are then evaluated to determine which
one is the best registering chip at the subpixel level.  This is done
by finding the box where "plateauing" occurs.  Analysis has
determined that as the box size decreases, correlation coefficients
increase.  Hence, we expect a gradually increasing correlation until
it decreases below the user specified tolerance (TOL) or becomes
erratic.  When this occurs, the highest correlation coefficient above
the user specified tolerance (TOL) is taken as the best registering
box and the approximated point is updated by the shift in line and
sample.  Note that the largest box size will never be used as the
best registering box.  Plateauing effects cannot be assessed in this
case.  Neither will boxes where only 9 valid pixels were used to
compute the statistics because it is deemed statistically unreliable.
Chips that are not successfully computed are ignored in the
evaluation process.

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 TOL 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 option for AVERAGE is computed by using
all boxes that are greater than or equal to the TOL 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 option "NEARAVG" 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 TOL.  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 TOL.  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 PIXTOL 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.

pntreg can produce a large volume of information for each point that is
registered.  The user should provide the name of a an error file in the
ERRFILE parameter where points that could not be registered will be
reported.  The first four lines for each pair of points that were not
successfully registered will contain the truth point and its file name,
followed by the same for the approximated point.  Then the results of
each registered box will follow from MINBOX to MAXBOX.  This can prove
valuable in determining if some points do have a solution but can only
be successfully registered if the input parameters to pntreg are
adjusted.  As is implicated here, pntreg can be ran multiple times on
the same point set only registering those points that have not been
succesfully registered in previous attempts.  The output match point
file (MATTO) from a previous run can be used in a subsequent run after
parameter adjustments are determined.  Once the user has determined
that subsequent runs will be fruitless, the user has the option to set
FINAL="YES" and pntreg will reclassify all unsuccessfully registered
points as Measured ("M").

SUCFILE is optional and is provided as a means to see which boxes are
evaluated as the best registering box.  It dumps information almost
identical to the format of the ERRFILE, but you will see "<--" in the
far rightmost field of the box evaluated as the best registering chip.
Note that its size, and even ERRFILE, can be quite large for a large
number of points.

PROGRAMMER: Kris Becker, USGS, Flagstaff AZ

Input match file name
(No default extension)

NONE

Output match file name
(No default extension)

NONE

Picture file name.  Use
this instead of FROMLIST
(No default extension)

--

List of cube files. Use
this instead of PICFILE
(no default extension)

--

Optional file to record
and identify successfully
registered points

--

Optional alternative path
to PIC cube files

--

Error file name
(No default extension)

NONE

Maximum pixel misregistration
allowed in LINE dimension

3

Maximum pixel misregistration
allowed in SAMPLE dimension

3

Tolerance for subpixel
registration

0.90

Pixel tolerance	

2.0

Minimum box size

5

Maximum box size

21

Box size increment

1

Geom data (Yes,No)

"NO"

Selects which point is to
be restricted to the
dimensions of the box size:
TRUTH    - Point used as the
           truth point which
           all other points
           are registered to
REGISTER - Point subject to
           registration to
           the TRUTH point
BOTH     - Both TRUTH and
           REGISTER points

"TRUTH"

Should the truth point need
to be selected for any point
set use:
EDGE   - Point closest to edge
         of image
CENTER - Point nearest center
         of image

"EDGE"

Selects which box to use as
the best correlating box:
LAST    - Pick the last
          occuring box above
          TOL
HIGH    - Pick the highest
          correlating box
          of all boxes above
          TOL
AVERAGE - Compute the average
          of all boxes with a
          correlation
          coefficient greater
          than or equal to TOL
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 (TOL)
BESTFIT - Selects the box that
          has the lowest Chi-
          Square value, an
          indicator of how
          well the data fits
          the least square
          model.

"LAST"

Is this run the final attempt?
If so, unsuccessful
registrations will be set to
a measured point rather than
automated.

NO  - Not final run, preserve
      class

YES - Is final, set to measured
      ("M") if unsuccessful
      registration

"NO"

Band/image number from the
input files that will be used
to calculate the pixel
registration

1

Lowest value of valid DN

--

Highest value of valid DN

--

Point id of the set to
perform a detailed dump
of chip registration
solution suitable for
plotting.  A special
value of "ALL" will
dump all point sets

--

Output directory where
to create point dumps

--

ADDITIONAL NOTES:

Parm	Description
MATFROM	Input match file name. Contains the list of points to match. It has fields containing a point id, image number, line and sample coordinate and image class.
MATTO	Output match file name. Will be generated from the contents of the MATFROM file. Same format as MATFROM only successfully registered points will have line, sample and class modified.
PICFILE	Picture file name. Contains a list of image cubes in a specific complex format (see "implab2jig"). It is typically used for the Imager for Mars Pathfinder (IMP) mission but may exist for other missions as well. If this file does not exist, then use FROMLIST (and see its associated help). Each match point read from the MATFROM file has an image identifier (IMAGE_NUMBER) associated with it. One of the PIC cube files must contain this identifier. These cubes will be used to retrieve image point data chips and register them to one another.
FROMLIST	ISIS cube list file name. Contains a list of image cubes, one file name per line. This file is used as an alternative to PICFILE and makes this application more generally useful. If a PICFILE does exist, it should be used. Note that if this option is used then each ISIS cube file in the list file must have the IMAGE_NUMBER keyword in the label. Each match point read from the MATFROM file has an image identifier (IMAGE_NUMBER) associated with it. One of the ISIS cube files must contain this identifier. These cubes will be used to retrieve image point data chips and register them to one another.
ALTPATH	Allows the user to specify an additional path to look for cubes specified in the PICFILE for point resolution. Note that the file will always be searched for first with the name as specified in the PICFILE, then the ALTPATH will be prepended to the name and then attempted to be opened using it.
ERRFILE	Error file name where unsuccessful point registrations occured. This file records every pair of points that could not be successufully registered. The truth and approximated points have the match point record and image file name recorded followed by the registration results for each box size. Its fields are box size, return code, subpixel line and sample coordinates, subpixel correlation coefficient, best registering whole pixel line and sample coordinates, correlation coefficient at whole pixel and the number of (valid) pixels used in the statistics.
SUCFILE	Same format as ERRFILE but will show which box/chip size is the one selected as the best. This will be denoted with a "<--" in the far rightmost field of the box that was deemed to be the best registering box.
LTOL	The maximum estimated pixel misregistration in the LINE dimension. Specifies the maximum search range to shift each chip up and down to find the best registering line. LTOL must be greater than zero. If LTOL is less than or equal to zero, regtest will assign LTOL=5.
STOL	The maximum estimated pixel misregistration in the SAMPLE dimension. Specifies the maximum search range to shift each chip left and right to find the best registering sample. STOL must be greater than zero. If STOL is less than or equal to zero, regtest will assign STOL=5.
TOL	Specifies the minimum acceptable correlation coefficient for each box size. Only boxes with correlation coefficients equal to or greater than this value should be evaluated and applied to update a point's coordinates.
PIXTOL	The maximum amount of samples or lines pixels allowed for the point to be adjusted when sub-pixel registered. Box registrations cannot exceed this amount in order for it to be applied to an approximated point matched to a truth point.
MINBOX	Minimum box size. The smallest box size to be used to compute subpixel registrations for a pair of points.
MAXBOX	Maximum box size. The largest box size to be used to compute subpixel registrations for a pair of points.
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.
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.
RESTRICT	In various tests, it has been shown, and should be intuitive, that statistics are sensitive to volume (population) and data used to compute them. This parameter provides a way to allow the user to have a little bit of control over what data are used in the chip registration statistics. At least one of the input chips surrounding the actual match point must be subject to the size of the box being used to compute the statistics. The smaller the box, the less data will be used. To restrict the data around a point means that the size of the chip read from the image will never be larger than MAXBOX. Conversely, an unrestricted point will be at least as large as MAXBOX plus twice the line (LTOL) and twice the sample (STOL) tolerances. This will result in total data coverage when the restricted point is shifted -LTOL to +LTOL and -STOL to +STOL.
SELECT	This parameter allows the user to choose how a truth point is determined in pntreg. This option only applies to point sets that have no truth or ground point designated in the MATFROM file. These points have a "T" or "G" class assigned to it. To select the point in a set closest to the edge, set SELECT to "EDGE". To select the point closest to the center set SELECT to "CENTER". Sometimes it is best to select the one closest to the edge so it becomes fixed and preventing it from being updated whereby it is shifted off the edge of the image.
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 TOL. 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 TOL. 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 TOL. 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 TOL selecting the box with the highest TOL 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 TOL. Note that the "BESTTOL" and "BESTFIT" options will not always return the same box but will more times than not.
FINAL	Set this parameter to "YES" when the user is making the last run of a match point file through pntreg. It will reclassify all unsuccessfully registered points as Measured ("M"). This essentially tells subsequent applications that this point is as good as it gets and is accepted with the current coordinates.
BAND	This parameter selects the BAND/image from the input cube file that will be used to compute the pixel registration. For multi-band cubes, this allows the user to specify which band to use. It assumes that all input files have the same number of bands. The same band will be used for all input files.
LOW	The lowest value of valid DNs. If LOW = 11, then pixels with DN values below 11 will be excluded from processing.
HIGH	The highest value of valid DNs. If HIGH = 200, then values greater that 200 will be excluded from processing.
DMPPNT	This is the point identifier that is to have a more detailed data dump of registration computations. A special value of DMPPNT="ALL" will produce a dump of all point sets specified in the input match file. A file name will be generated of the form DMPPNT_xx.dat where "DMPPNT" is the value of the unique point identifier, "xx" refers to each point in the set that is matched to the truth. Each file will contain 8 lines of general information about the truth point and registering point followed by a line for each box containing 17 fields. Here is a detailed description of each line: Line 1: Contains MINBOX, MAXBOX, BOXINC and NBOXES, the number of boxes used in correlating the chip. Line 2: Contains LTOL, STOL, EQORDER, MINP and FRAC. Line 3: Contains SAMPLING, GOODFIT (or TOL) and PIXTOL. Line 4: Contains the truth point MAT file information. Line 5: Contains the name of the truth point file. Line 6: Contains the register point MAT file information. Line 7: Contains the name of the registering point file. Line 8: Contains a header line with the name of each field for each registering box for the chip. All the above lines will have a '#' sign in the first column to indicate an information line. All subsequent lines will contain 17 fields of data from each box used to register the truth to the subject point. These fields and their (FORTRAN) formats are as follows: Field 1: Boxsize (I4) - This is the size of the box used to register the points. Field 2: Return status (I4) - The status of the registration for this box. A value of 0 indicates a sucessful registration. A value of 1 (typically) indicates an unsucessful registration. Field 3: Subpixel Line Offset (F9.4) - The subpixel line offset computed from this box. Field 4: Subpixel Sample Offset (F9.4) - The subpixel sample offset computed from this box. Field 5: Subpixel Correlation Coefficient (R) (F7.4) - This is the computed correlation value for the least squares model for this box. A value of 1.0 is a perfect correlation, a value of 0.0 indicates no correlation. Field 6: Subpixel Chi-Square (E16.6) - The Chi-Square value at the subpixel level. Field 7: Surface Correlation Coefficent (E16.6) - The subpixel values are determined by fitting whole pixel correlation coefficent values to a surface and solving for the maximum point on the surface. This field is an indication of how well this surface model fits the actual whole pixel correlation coefficient values at each observed point. Field 8: Surface Chi-Square (E16.6) - The subpixel values are determined by fitting whole pixel Chi-Square values to a surface and solving for the maximum point on the surface. This field is an indication of how well this surface model fits the actual whole pixel Chi-Square values at each observed point. Field 9: Whole Pixel Line Offset (F9.4) - The whole pixel line offset computed from this box. Field 10: Whole Pixel Sample Offset (F9.4) - The whole pixel sample offset computed from this box. Field 11: Whole Pixel Correlation Coefficient (F7.4) - This is the computed correlation value for the least squares model for this box. A value of 1.0 is a perfect correlation, a value of 0.0 indicates no correlation. Field 12: Whole Pixel Chi-Square (E16.6) - The Chi-Square value at the whole pixel level. Field 13: Truth Chip Average (E16.6) - Average of all pixels in the truth chip at the whole pixel shift for this box. Field 14: Truth Chip Standard Deviation (F10.4) - Standard deviation of a the pixels at the whole pixel shift in this box. Field 15: Registering Chip Average (E16.6) - Average of all pixels in the registering chip at the whole pixel shift for this box. Field 16: Registering Chip Standard Deviation (F10.4) - Standard deviation of the pixels at the whole pixel shift in this box. Field 17: Number Valid Pixels (I10) - Total number of pixels used to compute the registration for this box at the current shift.
DMPPATH	Specifies a directory where to dump a detailed description of a point set. If provided, it will dump point sets to the directory as specified in this parameter, otherwise any points sets specified in DMPPNT will be dumped to the current directory. See DMPPNT help for details about the files generated when using this option. It is not for the faint of heart!