This program can be used to tonematch or equalize the brightness and/or
contrast of a list of input cubes prior to mosaicking. All the input
cubes, which can include mosaics, must be in a common map projection as
this program will use the mapping information to gather statistics in
overlapping areas. This statistic gathering is done on a band-by-band
basis. The statistics are used in a least squares solution to
determine multiplicative (GAIN or MULT) and additive (OFFSET or BASE)
corrections for each image. In addition to simply calculating corrective
factors and applying said factors to each image in one run of the
program, the user has the option to stop the processing and examine the
gathered statistics in a text file. The program can then be run again,
using the file containing those statistics as an input, to apply
correction to any or all of the images without the need to recalculate
corrective factors.
The actual equation to be used for equalization, for ADJUST=BRIGHTNESS, CONTRAST or BOTH, on
each band in each cube is as follows:
newdn(s,l,b) = (olddn(s,l,b) - avg(b)) * GAIN(b) + (avg(b) + OFFSET(b))
where
s = sample index
l = line index
b = band index
The actual equation to be used for equalization, for ADJUST=GAIN, on
each band in each cube is
newdn(s,l,b) = olddn(s,l,b) * GAIN(b)
where
s = sample index
l = line index
b = band index
Prior to equalizing, the user can choose whether to adjust the
brightness and/or contrast of the cubes. The default is to adjust both;
however, if the brightness (average) of all the cubes is the same,
then simply adjusting the contrast may suffice. Likewise, if the
standard deviation of all the cubes is similar, then a contrast
adjustment is not necessary. Adjusting for contrast only implies
the OFFSET values will be held to zero. Similarly, adjusting for
brightness implies the GAIN values will be held to one.
The OFFSET and GAIN values are computed independently for each image,
therefore we have two least squares computations with N unknowns,
where N is the number of cubes to be equalized. The overlaps, M,
between all the cubes are computed, and in some cases M < N.
This implies an underdetermined system, and the program will report
an error if this occurs. You can hold one or more images to alleviate
this problem. Holding an image forces GAIN and OFFSET to 1.0 and 0.0
for that image, respectively.
If the user chooses to apply correction to the images, then a list
of output file names can be specified with the TOLIST parameter. If no
TOLIST is specified, the equalized cubes will be named the same as the
input cubes with the addition of a '.equ' prior to the '.cub'
extension, and placed in the same directories as their input files.
For the sake of efficiency, the user may choose to set the "sampling
percent" to be less than its default value of 100.0. By doing so, the
program will likely perform its statistic gathering noticeably faster,
but at the risk of losing accuracy in the results. It should
be noted that the user also runs the risk of encountering an error if
decreasing the sampling percent results in the amount of valid data in
the calculated overlaps being less than the minimum set by the
MINCOUNT parameter (default value of 1000). Sampling percent must be
a decimal value between 0.0 (exclusive) and 100.0 (inclusive).
This program defaults to solving the least-squares system using the
SPARSE matrix method. This method is able to find valid solutions, even
when no hold list is provided.
The QRD method is fairly accurate and fast, but does not
produce valid results in all cases, especially if no images are held.
Previous versions of equalizer used this method to solve.
Kay Edwards | 1994-05-24 |
Original version.
|
Elizabeth Ribelin | 2005-06-25 |
Ported to Isis 3.0.
|
Elizabeth Ribelin | 2005-10-04 |
Changed categoryItem to Photometry and Radiometry.
|
Brendan George | 2005-11-07 |
Added application test.
|
Elizabeth Miller | 2006-01-12 |
Made SD default contrast mode (PCA may have errors).
|
Jeff Anderson | 2007-07-16 |
Fixed memory leak.
|
Jeff Anderson | 2008-04-09 |
Modified to solve system using QRD which is faster the SVD.
|
Steven Lambright | 2008-05-12 |
Removed references to CubeInfo.
|
Tracie Sucharski | 2008-06-12 |
Modified call LeastSquares Solve due to change to LeastSquares
Solve method.
|
Travis Addair | 2009-03-12 |
Added user feedback during statistic gathering, modified existing progress
information, and moved error checking on number of bands and projection
parameters to be done prior to statistic gathering.
|
Travis Addair | 2009-06-24 |
Refactored for use with the new OverlapNormalization class, thus removing
the option to use the broken PCA contrast mode; the PVL output has been
modified to print all normalization information for a cube in one group
with OverlapStatistics information coming last in the file; added an
option to decrease the percentage of lines sampled in statistic gathering.
|
Travis Addair | 2009-07-17 |
Added a TOLIST parameter, allowing the user to specify a unique output
file name and location for each input file. The default is now to
place each output file in the same directory as its input file, not in
the current working directory.
|
Travis Addair | 2009-07-30 |
Added functionality allowing the user to run the program applying
corrections based off of previously gathered statistics obtained from
the program's output PVL file. The output PVL has also been changed
from "PVL" to "OUTSTATS". Results will now be placed into the print
file.
|
Travis Addair | 2009-11-19 |
Updated documentation and examples to reflect the most recent changes to
using the program.
|
Jeannie Backer | 2013-01-29 |
Added parameter SOLVEMETHOD to allow user to choose the method in which
the system of equations will be solved. Removed unnecessary error throws
from implementation file, now use xml to require OUTSTATS when
PROCESS=CALCULATE and require the PERCENT entered to be in the interval
(0, 100]. Improve test coverage to 100%. Fixes #962.
|
Jeannie Backer | 2013-02-04 |
Removed SVD option from the SOLVEMETHOD parameter since this option is
not producing correct results on MAC OS, see mantis ticket #1472.
If this bug is fixed and the option is reimplemented, the noHoldCalculateSparse
test data can be used to test the SVD method. Also, the documentation about
this method should be uncommented in the general description of the program,
in the QRD description. References #962.
|
Steven Lambright | 2013-02-06 |
Added the option "ADJUST=GAIN" based on a prototype developed by Jeff
Anderson. Fixes #911.
|
Jeannie Backer | 2013-02-27 |
Fixed user documentation. References #962.
|