equalizer

This program tone matches or equalizes the brightness and/or contrast of a list of input cubes prior to mosaicking. All the input cubes, including mosaics, must be in identical map projection since equalizer uses the mapping information to gather statistics in overlapping areas.

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 (BOTH), the user has the option to only calculate statistics (CALCULATE) and then examine these gathered statistics in a text file (OUTSTATS). Then, equalizer can be run again using that statistics file as input (INSTATS) to apply correction to any or all of the images without the need to calculate corrective factors again.

Corrective factors will be undetermined if there are insufficient valid overlaps or if there are any images that have no overlaps. If an output statistics file is provided (OUTSTATS), images that do not overlap will appear in the file.

When corrective factors are undetermined, the user can use the RECALCULATE process option to try to solve them. To do this, images can be added to the input list to try to create more overlaps or images without overlaps can be removed. An input statistics file (INSTATS) containing previously calculated image statistics must be provided. These statistics will be reloaded so overlap statistics will only be recalculated for new images in the modified input list. If all the images have overlaps and sufficient valid overlaps exist, corrective factors will be determined. Statistics can be recalculated as many times as desired by repeating the above steps.

Additionally, the RETRYBOTH process option may be used to recalculate statistics and then apply corrective factors. This requires the user to provide an INSTATS file containing previously calculated statistics. It is also suggested that the user provide an OUTSTATS file in case corrective factors cannot be determined. If the corrective factors are determined, they will then be applied to the input images.

The addition of these RETRYBOTH and RECALCULATE parameters has modified the content of the output statistics. Additional information is included in the output statistics so that previously calculated overlap statistics can be reloaded when using these parameters. Note that statistics files created with previous versions of ISIS can still be used as input statistics.

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

        s = sample index
        l = line index
        b = band index
      

        newdn(s,l,b)   =   olddn(s,l,b) * GAIN(b)
      

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

Description

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

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.

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

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.

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.

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.

Description

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

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.

                output = (input - average(input)) * gain + offset + average(input)
              

                output = offset + average(input)
              

                output = input * gain + average(input) * gain
              

                output = input * gain
              

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.

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.

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