Home
About ISIS
Support
Download

ISIS 3

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents

Search

USGS

ISIS 3 Application Documentation


equalizer

Printer Friendly View | TOC | Home

Tone matches map projected cubes

Overview Parameters Example 1 Example 2 Example 3

Description

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.


Categories


Related Applications to Previous Versions of ISIS

This program replaces the following application existing in previous versions of ISIS:
  • b4equal

History

Kay Edwards1994-05-24 Original version.
Elizabeth Ribelin2005-06-25 Ported to Isis 3.0.
Elizabeth Ribelin2005-10-04 Changed categoryItem to Photometry and Radiometry.
Brendan George2005-11-07 Added application test.
Elizabeth Miller2006-01-12 Made SD default contrast mode (PCA may have errors).
Jeff Anderson2007-07-16 Fixed memory leak.
Jeff Anderson2008-04-09 Modified to solve system using QRD which is faster the SVD.
Steven Lambright2008-05-12 Removed references to CubeInfo.
Tracie Sucharski2008-06-12 Modified call LeastSquares Solve due to change to LeastSquares Solve method.
Travis Addair2009-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 Addair2009-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 Addair2009-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 Addair2009-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 Addair2009-11-19 Updated documentation and examples to reflect the most recent changes to using the program.
Jeannie Backer2013-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 Backer2013-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 Lambright2013-02-06 Added the option "ADJUST=GAIN" based on a prototype developed by Jeff Anderson. Fixes #911.
Jeannie Backer2013-02-27 Fixed user documentation. References #962.

Parameter Groups

Files

Name Description
FROMLIST List of cubes to equalize
HOLDLIST List of filenames to hold
TOLIST List of the equalized cubes to be created
OUTSTATS Output text file containing thorough equalization-related statistics
INSTATS Input text file containing thorough equalization-related statistics, used for applying correction

ProcessingOptions

Name Description
PROCESS Calculate statistics, apply correction, or do both
SOLVEMETHOD The solve method to be used to calculate the equalization statistics

CalculationOptions

Name Description
ADJUST Algorithm type used to adjust the pixel values
MINCOUNT Minimum number of points in overlapping area required to be used in the solution
WEIGHT Whether or not overlaps should be weighted
PERCENT Percentage of the lines to consider when gathering overall cube statistics and overlap statistics
X

Files: FROMLIST


Description

A list of map projected cubes to equalize. The Mapping groups must match in order to do the equalization.

Type filename
File Mode input
Close Window
X

Files: HOLDLIST


Description

List of cubes that are to be held in the equalization. An additive and a multiplicative factor of 0 and 1 will be applied to all cubes that were held. All cubes listed in this file must also be contained in FROMLIST.

Type filename
File Mode input
Internal Default None
Filter *.txt *.lis *.lst
Close Window
X

Files: TOLIST


Description

This list of output files must contain a file name to correspond to each input file in the FROMLIST. Input files will be associated with output files by index, so that the equalized product of the first file in the FROMLIST will be written to the name and location of the first file in the TOLIST, and so on. Each output file will be written to the exact location with the exact name specified, unless the location and name happen to be identical to those of its corresponding input file, in which case an error will be thrown. If this list is not specified, but the APPLY option is still selected, the output files will be placed in the directories of their input files, and named the same with the exception of an added ".equ" extension (e.g., "foobar.cub" becomes "foobar.equ.cub").

Type filename
File Mode input
Internal Default Automatic
Close Window
X

Files: OUTSTATS


Description

This file will contain the statistics of all of the overlapping areas in every band along with the computed equalizing factors (OFFSET and GAIN). Specifying this output file is optional.

Type filename
File Mode output
Internal Default None
Filter *.txt *.pvl *.lis *.lst
Close Window
X

Files: INSTATS


Description

This file must contain the statistics of all the overlapping areas in every band along with the computed equalizing factors (OFFSET and GAIN) for every image in the FROMLIST.

Type filename
File Mode input
Filter *.txt *.pvl *.lis *.lst
Close Window
X

ProcessingOptions: PROCESS


Description

This option allows the user to decide whether they want to do the equalization calculations and then go on to apply correction afterwards, apply correction to the images off previously gathered statistics, or do the calculations but not apply correction. If the APPLY option is not selected, you must specify an OUTSTATS file. If it is selected you can still optionally specify an OUTSTATS file and the GAIN/OFFSET values will be applied to each input cube. The names and locations of the output cubes are specified by the TOLIST file.

Type string
Default BOTH
Option List:
Option Brief Description
BOTH Calculate statistics and apply correction This option will calculate image statistics and then apply corrections from the results.

Exclusions

  • INSTATS
CALCULATE Calculate statistics only This option will calculate image statistics and print them to an output PVL file, but image corrections will not be applied.

Exclusions

  • TOLIST
  • INSTATS

Inclusions

  • OUTSTATS
APPLY Apply correction only This option will use previously generated statistics to apply correction to the images.

Exclusions

  • HOLDLIST
  • OUTSTATS
  • ADJUST
  • MINCOUNT
  • WEIGHT
  • PERCENT
  • SOLVEMETHOD

Inclusions

  • INSTATS
Close Window
X

ProcessingOptions: SOLVEMETHOD


Description

This option allows the user to choose the solve method for the least-squares system. The default is SPARSE.

Type string
Default SPARSE
Option List:
Option Brief Description
QRD The QR Decomposition method is least accurate when no hold list is provided. Solve the least-squares system using QR decomposition. This method is likely to result in invalid values when no hold list is provided
SPARSE The SPARSE is the most accurate when no hold list is provided. Solve the least-squares system using a sparse matrix formulation of the LU decomposition. This is the best method to use if no hold list is provided.
Close Window
X

CalculationOptions: ADJUST


Description

This option allows the user to select the algorithm that will be used to adjust the pixel values. The BRIGHTNESS mode will equalize using only an offset (the gain will be set to 1.0), and the CONTRAST mode will equalize using only a gain (the offset will be set to 0.0) but keeping the images around their current average. The GAIN option will equalize using only a gain and will not normalize the output values. The BOTH option will equalize using both an offset and a gain. In most cases this option will give you the best results.

Type string
Default BOTH
Option List:
Option Brief Description
BOTH Adjust the brightness and contrast of the images. This option will use an algorithm that equalizes both the brightness and contrast of the images. The equation this option uses is:
                output = (input - average(input)) * gain + offset + average(input)
              
BRIGHTNESS Adjust the brightness of the images using calculated offsets This option will use an algorithm that only equalizes the brightness of the images by calculating the offset for each. This option should be used only if the variances/standard deviations of the images are close. The equation this option uses is:
                output = offset + average(input)
              
CONTRAST Adjust the contrast of the images only using calculated gains This option will use an algorithm that only equalizes the contrast of the images by calculating the gain for each. This option should only be used if the brightnesses of the images are already close. The equation this option uses is:
                output = input * gain + average(input) * gain
              
GAIN Adjust the contrast of the images without normalization This option will use an algorithm that only equalizes the contrast of the images by calculating the gain for each. No offsets will be applied; the resulting image will only have a gain adjustment and no normalization. This option should only be used if the brightnesses of the images are already close. The equation this option uses is:
                output = input * gain
              
Close Window
X

CalculationOptions: MINCOUNT


Description

If the number of points in the overlapping area meets or exceeds this value, the area will go into the least-squares solution as a "known." Otherwise it will not be included in the calculations.

Type integer
Default 1000
Close Window
X

CalculationOptions: WEIGHT


Description

This option allows the user to decide whether they want to weight the least squares solution based on how large the overlap area is, or if they want no weighting at all. If this parameter is set to "true," then larger overlapping areas will have more of an impact on the corrective factors than smaller overlaps.

Type boolean
Default FALSE
Close Window
X

CalculationOptions: PERCENT


Description

The percentage of the lines in each area to consider in the process-by-line solutions for finding overall cube statistics and overlap statistics. This value must be a decimal value between 0.0 (exclusive) and 100.0 (inclusive).

Type double
Default 100.0
Minimum 0.0 (exclusive)
Maximum 100.0 (inclusive)
Close Window

Example 1

Calculate Statistics and Apply Correction

Description

This example shows the most typical use of the equalizer application. The defaults are to perform both calculation and adjustment for both the gain and offset.

Command Line

equalizer fromlist= FromList.lst holdlist= HoldList.lst
Specify a list of images to equalize along with a holding list that enables the necessary calculations to be performed. All other options are at default values.

GUI Screenshot

Equalizer Gui

Example GUI

Screenshot of the GUI with parameters set to calculate the gain and offset and then to apply corrections. Because the TOLIST parameter is set to its default value of "Automatic," each output image will be placed into the directory of its corresponding input image. Also, because the OUTSTATS parameter is set to its default value of "None", a record of the calculations performed will only be written to the print file.

Input Image

Mosaic of unequalized input images

Mosaic of the input images for equalizer

Parameter Name: FROMLIST

This is a small section of the input images for the equalizer example mosaicked together.

Data Files

Links open in a new window.
Click here to see the list of input images to be equalized This list contains the names of three files to calculate statistics upon, and then equalize. The file names are separated by new lines.
Click here to see the list of input images to be held This list contains the name of one file from the FROMLIST to be held during calculations. When multiple images are held, their file names are likewise separated by new lines.

Output Image

Mosaic showing results of the equalizer application.

Mosaic of the output images for equalizer

Parameter Name: TOLIST

This is a small section of the equalized output images mosaicked together.


Example 2

Calculate Statistics

Description

This example shows how to use the equalizer application to calculate equalization statistics and write them to a file, without applying the corrections to the input images.

Command Line

equalizer fromlist= FromList.lst holdlist=/HoldList.lst outstats= stats.pvl process= calculate
In addition to specifying a fromlist and a holdlist, we must also specify a location to write the output statistics pvl, and set the process type to "calculate." Since no output images will be created, we do not (and cannot), specify a tolist. All other options are at default values.

GUI Screenshot

Equalizer GUI

Example GUI

Screenshot of the GUI with parameters set to calculate equalization statistics on a set of input images.

Input Image

Mosaic of unequalized input images.

Mosaic of the input images for equalizer

Parameter Name: FROMLIST

This is a small section of the input images for the equalizer example mosaicked together.

Data Files

Links open in a new window.
Click here to see the list of images to calculate statistics upon This list contains the names of three files to calculate statistics upon. The file names are separated by new lines.
Click here to see the list of input images to be held This list contains the name of one file from the FROMLIST to be held during calculations. When multiple images are held, their file names are likewise separated by new lines.
Click here to see the output text file containing statistics for equalizing This pvl contains thorough equalization-related statistics that can be used for applying correction to any or all images used to generate this file.

Example 3

Apply Correction

Description

This example shows the use of the equalizer application for applying correction to a subset of the images used to produce a specified input statistics file.

Command Line

equalizer fromlist= Input.lst tolist= Output.lst instats= stats.pvl process= apply
Specify a fromlist that is a sublist of the fromlist from Example 2. Because calculations have already been performed, no holdlist is specified, and since we want to place the output images in a specific location with specific names, a tolist is specified. Finally, we set the value of the instats parameter to be the output statistics file generated in Example 2, and set the process to "apply." All other options are at default values.

GUI Screenshot

Equalizer Gui

Example GUI

Screenshot of the GUI with parameters set to apply correction to a subset of the images used to produce a specified input statistics file.

Data Files

Links open in a new window.
Click here to see the list of images to be equalized This list contains the names of two files to equalize. Both file names appear in the FROMLIST file from the previous example, and both file names have calculated gain and offset coefficients calculated for them in the INSTATS file. Since we do not wish to create a new file for the held image, however, we chose not to include it in this new list. The file names are separated by new lines.
Click here to see the list of images to write after equalization This list contains the names of two files to be written as outputs from the equalization process. The index of each file name corresponds to the index of a file from this example's FROMLIST file. Here, the output images retain their original names, but are written to the current directory.
Click here to see the input text file containing statistics for equalizing This pvl contains thorough equalization-related statistics for applying correction to any or all images used to generate this file. In this example, two of the three files used to generate these statistics have been selected for equalization.

Output Image

Mosaic showing results of the equalizer application.

Mosaic of the output images for equalizer

Parameter Name: TOLIST

This is a small section of the equalized output images and the held image from Example 2 mosaicked together. Note that since we only chose to omit the held image from Example 2 when applying correction, that the results are the same as those in Example 1.