Isis Developer Reference
Isis::Equalization Class Reference

This class can be used to calculate, read in, and/or apply equalization statistics for a list of files. More...

#include <Equalization.h>

Inheritance diagram for Isis::Equalization:
Inheritance graph
Collaboration diagram for Isis::Equalization:
Collaboration graph

Classes

class  ApplyFunctor
 This class is used as a functor to apply adjustments (equalize) to an image. More...
 
class  CalculateFunctor
 This class is used as a functor calculate image statistics. More...
 
class  ImageAdjustment
 

Public Member Functions

 Equalization (OverlapNormalization::SolutionType sType, QString fromListName)
 Constructs an Equalization with the specified solution type and loads input images.
 
virtual ~Equalization ()
 Destructor.
 
void addHolds (QString holdListName)
 Adds a list of images to be held in the equalization.
 
void calculateStatistics (double samplingPercent, int mincnt, bool wtopt, LeastSquares::SolveMethod methodType)
 Calculates the image and overlap statistics, and then determines corrective factors if possible.
 
void recalculateStatistics (QString inStatsFileName)
 Recalculates statistics for any new input images.
 
void importStatistics (QString instatsFileName)
 Imports statistics for applying correction.
 
void applyCorrection (QString toListName)
 Equalizes the input images.
 
PvlGroup getResults ()
 Returns general information about the equalization.
 
void write (QString outstatsFileName)
 Write the equalization information (results) to a file.
 
double evaluate (double dn, int imageIndex, int bandIndex) const
 

Protected Member Functions

 Equalization ()
 Default constructor.
 
void loadInputs (QString fromListName)
 Loads in the input images.
 
void setInput (int index, QString value)
 
const FileListgetInputs () const
 
void calculateBandStatistics ()
 Calculates the image statistics on a band-by-band basis.
 
void calculateOverlapStatistics ()
 Calculates the overlap statistics for each pair of input images.
 
virtual void fillOutList (FileList &outList, QString toListName)
 
virtual void errorCheck (QString fromListName)
 Checks that the input images have the same mapping groups and same number of bands.
 
void generateOutputs (FileList &outList)
 Generates the names of the equalized cubes if no output list is provided.
 
void loadOutputs (FileList &outList, QString toListName)
 Checks that the output image list is correct.
 
void loadHolds (OverlapNormalization *oNorm)
 
void setResults ()
 Creates the results pvl containing statistics and corrective factors.
 
void clearAdjustments ()
 Frees image adjustments.
 
void addAdjustment (ImageAdjustment *adjustment)
 Adds an image adjustment.
 
void clearNormalizations ()
 Frees overlap normalizations.
 
void clearOverlapStatistics ()
 Frees overlap statistics.
 
void addValid (int count)
 Increments the number of valid overlaps by a given amount.
 
void addInvalid (int count)
 Increments the number of invalid overlaps by a given amount.
 
void fromPvl (const PvlObject &inStats)
 Loads a previous Equalization state from an input pvl object.
 
void setSolved (bool solved)
 Sets solved state indicating if OverlapNormalizations (corrective factors) were solved.
 
bool isSolved () const
 Indicates if the corrective factors were solved.
 

Detailed Description

This class can be used to calculate, read in, and/or apply equalization statistics for a list of files.

  • Calculating equalization statistics
    • An optional list of images to hold may be given before calculations.
    • In order to calculate statistics, the class will need to know the following:
      • percentage of lines to be used for calculations,
      • the minimum number of points in overlapping area to be used,
      • whether overlapping areas should be weighted based on number of valid pixels,
      • whether to calculate gain, offset, or both
      • which LeastSquares solve method.
    • Once calculated, these statistics can be returned as a PvlGroup, written to a text file, and/or applied to the images in the input file list.
  • Importing equalization statistics
    • Statistics may be imported from a given file name and then applied to the images in the input file list.
  • Applying equalization statistics
    • Statistics must be calculated or imported before they can be applied to the images in the input file list.

Code example for calculating statistics, writing results to a Pvl, writing results to a file, and applying results: Equalization eq(inputCubeListFileName); // calculate eq.addHolds(holdListFileName); eq.calculateStatistics(samplingPercent, mincnt, wtopt, sType, methodType); // write to PvlGroup PvlGroup resultsGroup = eq.getResults(); // write to file eq.write(outputStatisticsFileName); // apply corrections to cubes in input list eq.applyCorrection();

Code example for importing statistics and applying them. Equalization eq(listFileName); eq.importStatistics(inputStatisticsFileName); // create new output cubes from equalized cube list and apply corrections eq.applyCorrection(equalizedCubeListFileName);

This class contains the classes ImageAdjustment, CalculateFunctor, and ApplyFunctor.

Author
????-??-?? Unknown

Constructor & Destructor Documentation

◆ Equalization() [1/2]

Isis::Equalization::Equalization ( OverlapNormalization::SolutionType sType,
QString fromListName )

Constructs an Equalization with the specified solution type and loads input images.

Parameters
sTypeAn integer value corresponding to the enumerated value of the OverlapNormalization::SolutionType to be used.
fromListNameName of the input image list.

References loadInputs().

◆ ~Equalization()

Isis::Equalization::~Equalization ( )
virtual

◆ Equalization() [2/2]

Isis::Equalization::Equalization ( )
protected

Default constructor.

Member Function Documentation

◆ addAdjustment()

void Isis::Equalization::addAdjustment ( ImageAdjustment * adjustment)
protected

Adds an image adjustment.

This method adds an image adjustment to be used for equalizing.

Parameters
adjustment- ImageAdjustment pointer to add.

Referenced by calculateOverlapStatistics(), Isis::HiEqualization::calculateStatistics(), and importStatistics().

◆ addHolds()

void Isis::Equalization::addHolds ( QString holdListName)

Adds a list of images to be held in the equalization.

Parameters
holdListNameName of the file containing a list of images to hold.
Exceptions
IException::User"The list of identifiers to be held must be less than or equal to the total number of identifiers."
IException::User"The hold list file does not match a file in the from list"

References _FILEINFO_, Isis::FileList::read(), and Isis::IException::User.

◆ addInvalid()

void Isis::Equalization::addInvalid ( int count)
protected

Increments the number of invalid overlaps by a given amount.

Parameters
countAn integer value to increment the internally stored number of invalid overlaps

◆ addValid()

void Isis::Equalization::addValid ( int count)
protected

Increments the number of valid overlaps by a given amount.

Parameters
countAn integer value to increment the internally stored number of valid overlaps

Referenced by Isis::HiEqualization::calculateStatistics().

◆ applyCorrection()

void Isis::Equalization::applyCorrection ( QString toListName = "")

Equalizes the input images.

This method applies corretive factors to the input images, thereby equalizing them.

Parameters
toListName(Default value is "") List of cube names to save the equalized images as
Exceptions
IException::User"Corrective factors have not yet been determined. Fix any " "non-overlapping images and recalculate the image statistics."

References _FILEINFO_, fillOutList(), isSolved(), Isis::Process::Progress(), Isis::Progress::SetText(), Isis::toString(), and Isis::IException::User.

◆ calculateBandStatistics()

void Isis::Equalization::calculateBandStatistics ( )
protected

Calculates the image statistics on a band-by-band basis.

This method calculates statistics by band for the input images. Each set of band statistics is used to initialize the OverlapNormalizations that will be used to determine gains and offsets for equalization.

References loadHolds(), and Isis::toString().

Referenced by calculateStatistics(), and fromPvl().

◆ calculateOverlapStatistics()

void Isis::Equalization::calculateOverlapStatistics ( )
protected

Calculates the overlap statistics for each pair of input images.

This method calculates any overlap statistics that have not been previously calculated for the input images.

References addAdjustment(), Isis::Cube::open(), and Isis::toString().

Referenced by calculateStatistics().

◆ calculateStatistics()

void Isis::Equalization::calculateStatistics ( double percent,
int mincnt,
bool wtopt,
LeastSquares::SolveMethod methodType )

Calculates the image and overlap statistics, and then determines corrective factors if possible.

This method calculates image statistics on a band-by-band basis and calculates overlap statistics for the input images. Overlaps are considered valid if the number of valid pixels in the overlapping area is greater than or equal to the provided mincnt parameter. Corrective factors will only be determined if all of the input images have at least one valid overlap.

Parameters
percentPercentage of the lines to consider when gathering overall cube statistics and overlap statistics
mincntMinimum number of points in overlapping area required to be used in the solution
wtoptIndicates whether overlaps should be weighted
methodTypeAn integer value corresponding to the enumerated value of the desired LeastSquares::SolveMethod to be used.
Exceptions
IException::User"There are input images that do not overlap with enough valid pixels." "See application log or Nonoverlaps keyword in output statistics file"
IException::Unknown"Calculation for equalization statistics failed. Gain = 0."
IException::Unknown"Unable to calculate the equalization statistics. You may " "want to try another LeastSquares::SolveMethod."

References _FILEINFO_, calculateBandStatistics(), calculateOverlapStatistics(), setResults(), Isis::IException::Unknown, and Isis::IException::User.

Referenced by recalculateStatistics().

◆ clearAdjustments()

void Isis::Equalization::clearAdjustments ( )
protected

◆ clearNormalizations()

void Isis::Equalization::clearNormalizations ( )
protected

Frees overlap normalizations.

Referenced by ~Equalization().

◆ clearOverlapStatistics()

void Isis::Equalization::clearOverlapStatistics ( )
protected

Frees overlap statistics.

Referenced by ~Equalization().

◆ errorCheck()

void Isis::Equalization::errorCheck ( QString fromListName)
protectedvirtual

Checks that the input images have the same mapping groups and same number of bands.

Exceptions
IException::User"Number of bands do not match between cubes"
IException::User"Mapping groups do not match between cubes"

Reimplemented in Isis::HiEqualization.

References _FILEINFO_, Isis::Cube::open(), Isis::toString(), and Isis::IException::User.

Referenced by loadInputs().

◆ evaluate()

double Isis::Equalization::evaluate ( double dn,
int imageIndex,
int bandIndex ) const

◆ fillOutList()

void Isis::Equalization::fillOutList ( FileList & outList,
QString toListName )
protectedvirtual

Reimplemented in Isis::HiEqualization.

References generateOutputs(), and loadOutputs().

Referenced by applyCorrection().

◆ fromPvl()

void Isis::Equalization::fromPvl ( const PvlObject & inStats)
protected

Loads a previous Equalization state from an input pvl object.

This method will unserialize Equalization data from an input pvl, obtaining any previously calculated overlap statistics and corrective factors (if solved).

Parameters
constPvlObject& Input pvl object containing previous Equalization state

References calculateBandStatistics(), and Isis::PvlObject::findObject().

Referenced by recalculateStatistics().

◆ generateOutputs()

void Isis::Equalization::generateOutputs ( FileList & outList)
protected

Generates the names of the equalized cubes if no output list is provided.

Referenced by fillOutList(), and Isis::HiEqualization::fillOutList().

◆ getInputs()

const FileList & Isis::Equalization::getInputs ( ) const
protected

◆ getResults()

PvlGroup Isis::Equalization::getResults ( )

Returns general information about the equalization.

This method returns general information about the equalization, including number of valid and invalid overlaps, any non-overlapping images, the LeastSquares solution type, the type of equalization adjustmnet, and corrective factors (if solved).

References Isis::PvlObject::findObject(), and Isis::toString().

◆ importStatistics()

void Isis::Equalization::importStatistics ( QString instatsFileName)

Imports statistics for applying correction.

This method obtains corrective factors from an input statistics pvl file so that input images can be equalized. These corrective factors are obtained from Normalization groups within the EqualizationInformation object in the input pvl.

See also
Equalization::applyCorrection()
Parameters
instatsFileNameName of the input statistics pvl file

References addAdjustment(), clearAdjustments(), Isis::PvlObject::findObject(), and Isis::toDouble().

◆ isSolved()

bool Isis::Equalization::isSolved ( ) const
protected

Indicates if the corrective factors were solved.

Returns
bool Returns true if corrective factors were solved

Referenced by applyCorrection().

◆ loadHolds()

void Isis::Equalization::loadHolds ( OverlapNormalization * oNorm)
protected

◆ loadInputs()

void Isis::Equalization::loadInputs ( QString fromListName)
protected

Loads in the input images.

This method loads in the input images contained in the provided file name.

Parameters
fromListNameName of the file containing the input images
Exceptions
IException::User"The input file must contain at least 2 file names"

References _FILEINFO_, errorCheck(), Isis::Cube::open(), Isis::FileList::read(), Isis::toString(), and Isis::IException::User.

Referenced by Equalization(), and Isis::HiEqualization::HiEqualization().

◆ loadOutputs()

void Isis::Equalization::loadOutputs ( FileList & outList,
QString toListName )
protected

Checks that the output image list is correct.

Exceptions
IException::User"Each input file in the FROM LIST must have a corresponding output file in the TO LIST."
IException::User"The to list file has the same name as its corresponding from list fil."

References _FILEINFO_, Isis::toString(), and Isis::IException::User.

Referenced by fillOutList(), and Isis::HiEqualization::fillOutList().

◆ recalculateStatistics()

void Isis::Equalization::recalculateStatistics ( QString instatsFileName)

Recalculates statistics for any new input images.

This method loads a previous Equalization state from an input pvl file and calculates overlap statistics for any new input images. Corrective factors will also be calculated if there are no non-overlapping images and there are enough valid overlaps.

Parameters
instatsFileNameName of input pvl file containing previously calculated statistics

References calculateStatistics(), and fromPvl().

◆ setInput()

void Isis::Equalization::setInput ( int index,
QString value )
protected

◆ setResults()

void Isis::Equalization::setResults ( )
protected

Creates the results pvl containing statistics and corrective factors.

This method creates the results pvl containing what is essentially serialized Equalization data, which can be unserialized via the fromPvl() method. Note that the overlap statistics in the results pvl may not be ordered if recalculating statistics with a modified input image list.

References Isis::PvlObject::addObject(), Isis::OverlapNormalization::Both, Isis::OverlapNormalization::Gains, Isis::OverlapNormalization::GainsWithoutNormalization, Isis::OverlapNormalization::Offsets, Isis::Pvl::setTerminator(), and Isis::toString().

Referenced by Isis::HiEqualization::calculateStatistics(), and calculateStatistics().

◆ setSolved()

void Isis::Equalization::setSolved ( bool solved)
protected

Sets solved state indicating if OverlapNormalizations (corrective factors) were solved.

Parameters
boolIndiciates if corrective factors were solved

Referenced by Isis::HiEqualization::calculateStatistics().

◆ write()

void Isis::Equalization::write ( QString outstatsFileName)

Write the equalization information (results) to a file.

Parameters
outstatsFileNameThe name of the file to write the results to

References Isis::Pvl::write().


The documentation for this class was generated from the following files: