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:

Collaboration diagram for Isis::Equalization:

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

virtual	~Equalization ()
	Destructor. More...

void	addHolds (QString holdListName)
	Adds a list of images to be held in the equalization. More...

void	calculateStatistics (double samplingPercent, int mincnt, bool wtopt, LeastSquares::SolveMethod methodType)
	Calculates the image and overlap statistics, and then determines corrective factors if possible. More...

void	recalculateStatistics (QString inStatsFileName)
	Recalculates statistics for any new input images. More...

void	importStatistics (QString instatsFileName)
	Imports statistics for applying correction. More...

void	applyCorrection (QString toListName)
	Equalizes the input images. More...

PvlGroup	getResults ()
	Returns general information about the equalization. More...

void	write (QString outstatsFileName)
	Write the equalization information (results) to a file. More...

double	evaluate (double dn, int imageIndex, int bandIndex) const

Protected Member Functions
	Equalization ()
	Default constructor. More...

void	loadInputs (QString fromListName)
	Loads in the input images. More...

void	setInput (int index, QString value)

const FileList &	getInputs () const

void	calculateBandStatistics ()
	Calculates the image statistics on a band-by-band basis. More...

void	calculateOverlapStatistics ()
	Calculates the overlap statistics for each pair of input images. More...

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

void	generateOutputs (FileList &outList)
	Generates the names of the equalized cubes if no output list is provided. More...

void	loadOutputs (FileList &outList, QString toListName)
	Checks that the output image list is correct. More...

void	loadHolds (OverlapNormalization *oNorm)

void	setResults ()
	Creates the results pvl containing statistics and corrective factors. More...

void	clearAdjustments ()
	Frees image adjustments. More...

void	addAdjustment (ImageAdjustment *adjustment)
	Adds an image adjustment. More...

void	clearNormalizations ()
	Frees overlap normalizations. More...

void	clearOverlapStatistics ()
	Frees overlap statistics. More...

void	addValid (int count)
	Increments the number of valid overlaps by a given amount. More...

void	addInvalid (int count)
	Increments the number of invalid overlaps by a given amount. More...

void	fromPvl (const PvlObject &inStats)
	Loads a previous Equalization state from an input pvl object. More...

void	setSolved (bool solved)
	Sets solved state indicating if OverlapNormalizations (corrective factors) were solved. More...

bool	isSolved () const
	Indicates if the corrective factors were solved. More...

Private Member Functions
void	init ()
	Initializes member variables to default values. More...

QVector< int >	validateInputStatistics (QString instatsFileName)
	Validates the input statistics pvl file. More...

Private Attributes
bool	m_normsSolved
	Indicates if corrective factors were solved. More...

bool	m_recalculating
	Indicates if recalculating with loaded statistics. More...

bool	m_wtopt
	Whether or not overlaps should be weighted. More...

FileList	m_imageList

double	m_samplingPercent
	Percentage of the lines to consider when gathering cube and overlap statistics (process-by-line) More...

int	m_validCnt
	Number of valid overlaps. More...

int	m_invalidCnt
	Number of invalid overlaps. More...

int	m_mincnt
	Minimum number of pixels for an overlap to be considered valid. More...

int	m_maxCube
	Number of input images. More...

int	m_maxBand
	Number of bands in each input image. More...

QStringList	m_badFiles
	List of image names that don't overlap. More...

vector< ImageAdjustment * >	m_adjustments

vector< int >	m_holdIndices
	Indices of images being held. More...

vector< bool >	m_doesOverlapList
	Which images have a valid overlap. More...

vector< bool >	m_alreadyCalculated
	Which images that have statistics already calculated. More...

vector< OverlapNormalization * >	m_overlapNorms
	Normalization data for input images. More...

vector< OverlapStatistics * >	m_overlapStats
	Calculated overlap statistics. More...

OverlapNormalization::SolutionType	m_sType
	The normalization solution type for solving normalizations (offsets, gains, or both) More...

LeastSquares::SolveMethod	m_lsqMethod
	Least squares method for solving normalization correcitve factors. More...

Pvl *	m_results
	Calculation results and normalization corrective factors (if solved) More...

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

History:: 2012-04-26 Jeannie Backer - Added includes to Filelist, Pvl, PvlGroup, and Statistics classes to the implementation file.

History:: 2013-01-29 Jeannie Backer - Added input parameter to calculateStatistics() method. Added error catch to improve thrown message. Fixes #962.

History:: 2013-01-29 Jeannie Backer - Fixed bugs from previous checkin. Improved test coverage by more than 23% for each coverage type.

History:: 2013-02-06 Steven Lambright - Made the OverlapNormalization::SolutionType into a member required upon instantiation in order to support gain adjustments without normalization, which uses a separate formula in evaluate() instead of just modifying how statistics are computed. Implemented the GainsWithoutNormalization solution type. References #911.

History:: 2016-07-15 Ian Humphrey - Added recalculateStatistics() method to allow for statistics to be calculated only for new input images, using previously calculated statistics for the rest of the input images. Added fromPvl() method to unserialize Equalization data from a pvl object. Refactored calculateStatistics() to separate functionality and allow for statistics recalculation. Added methods to properly free some of the vector members. Added new members to help with unserialization via the fromPvl() method and help with recalulating overlap statistics. Added API documentation. Updated unit test. Fixes #2282.

History:: 2017-05-19 Christopher Combs - Modified uniTest.cpp: truncated paths of NonOverlaps in output PVL on lines 100 and 123 to allow the test to pass when not using the standard data areas. Added ReportError method to remove paths when outputting errors. Fixes #4738.

Definition at line 122 of file Equalization.h.

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

sType	An integer value corresponding to the enumerated value of the OverlapNormalization::SolutionType to be used.
fromListName	Name of the input image list.

Definition at line 52 of file Equalization.cpp.

◆ ~Equalization()

Isis::Equalization::~Equalization ( )

virtual

Destructor.

Definition at line 63 of file Equalization.cpp.

◆ Equalization() [2/2]

Isis::Equalization::Equalization ( )

protected

Default constructor.

Definition at line 40 of file Equalization.cpp.

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.

Definition at line 748 of file Equalization.cpp.

◆ addHolds()

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

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

Parameters

holdListName Name 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"

Definition at line 84 of file Equalization.cpp.

References Isis::FileList::read().

◆ addInvalid()

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

protected

Increments the number of invalid overlaps by a given amount.

Parameters

count An integer value to increment the internally stored number of invalid overlaps

Definition at line 790 of file Equalization.cpp.

◆ addValid()

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

protected

Increments the number of valid overlaps by a given amount.

Parameters

count An integer value to increment the internally stored number of valid overlaps

Definition at line 780 of file Equalization.cpp.

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

Definition at line 496 of file Equalization.cpp.

References Isis::Cube::bandCount(), Isis::ProcessByBrick::EndProcess(), Isis::Cube::lineCount(), Isis::ProcessByLine::ProcessCube(), Isis::Process::Progress(), Isis::Cube::sampleCount(), Isis::ProcessByLine::SetInputCube(), Isis::ProcessByBrick::SetOutputCube(), Isis::Progress::SetText(), and Isis::toString().

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

Definition at line 212 of file Equalization.cpp.

References Isis::ProcessByBrick::EndProcess(), Isis::ProcessByLine::ProcessCubeInPlace(), Isis::Process::Progress(), Isis::ProcessByLine::SetInputCube(), Isis::Progress::SetText(), and Isis::toString().

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

Definition at line 252 of file Equalization.cpp.

References Isis::OverlapStatistics::GetMStats(), Isis::OverlapStatistics::HasOverlap(), Isis::Cube::open(), Isis::OverlapStatistics::SetMincount(), Isis::toString(), Isis::MultivariateStatistics::ValidPixels(), Isis::MultivariateStatistics::X(), and Isis::MultivariateStatistics::Y().

◆ 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

percent	Percentage of the lines to consider when gathering overall cube statistics and overlap statistics
mincnt	Minimum number of points in overlapping area required to be used in the solution
wtopt	Indicates whether overlaps should be weighted
methodType	An 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."

Definition at line 136 of file Equalization.cpp.

◆ clearAdjustments()

void Isis::Equalization::clearAdjustments ( )

protected

Frees image adjustments.

Definition at line 733 of file Equalization.cpp.

◆ clearNormalizations()

void Isis::Equalization::clearNormalizations ( )

protected

Frees overlap normalizations.

Definition at line 756 of file Equalization.cpp.

◆ clearOverlapStatistics()

void Isis::Equalization::clearOverlapStatistics ( )

protected

Frees overlap statistics.

Definition at line 767 of file Equalization.cpp.

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

Definition at line 650 of file Equalization.cpp.

References Isis::Cube::bandCount(), Isis::Cube::open(), Isis::Cube::projection(), and Isis::toString().

◆ 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

const PvlObject& Input pvl object containing previous Equalization state

Definition at line 803 of file Equalization.cpp.

References Isis::OverlapStatistics::Bands(), Isis::PvlObject::beginObject(), Isis::PvlObject::endObject(), Isis::OverlapStatistics::FileNameX(), Isis::OverlapStatistics::FileNameY(), Isis::PvlObject::findGroup(), Isis::PvlObject::findObject(), Isis::OverlapStatistics::GetMStats(), Isis::MultivariateStatistics::ValidPixels(), Isis::MultivariateStatistics::X(), and Isis::MultivariateStatistics::Y().

◆ generateOutputs()

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

protected

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

Definition at line 684 of file Equalization.cpp.

References Isis::FileName::baseName(), Isis::FileName::extension(), and Isis::FileName::path().

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

Definition at line 549 of file Equalization.cpp.

References 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

instatsFileName Name of the input statistics pvl file

Definition at line 447 of file Equalization.cpp.

References Isis::PvlObject::findGroup(), Isis::PvlObject::findObject(), Isis::PvlObject::group(), Isis::PvlContainer::hasKeyword(), Isis::PvlContainer::keywords(), and Isis::toDouble().

◆ init()

void Isis::Equalization::init ( )

private

Initializes member variables to default values.

Definition at line 917 of file Equalization.cpp.

◆ isSolved()

bool Isis::Equalization::isSolved ( ) const

protected

Indicates if the corrective factors were solved.

Returns: bool Returns true if corrective factors were solved

Definition at line 909 of file Equalization.cpp.

◆ 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

fromListName Name of the file containing the input images

Exceptions

IException::User "The input file must contain at least 2 file names"

Definition at line 602 of file Equalization.cpp.

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

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

Definition at line 702 of file Equalization.cpp.

References Isis::FileList::read(), and Isis::toString().

◆ 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

instatsFileName Name of input pvl file containing previously calculated statistics

Definition at line 428 of file Equalization.cpp.

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

Definition at line 324 of file Equalization.cpp.

References Isis::PvlObject::addGroup(), Isis::PvlObject::addObject(), and Isis::toString().

◆ setSolved()

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

protected

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

Parameters

bool	Indiciates if corrective factors were solved

Definition at line 899 of file Equalization.cpp.

◆ validateInputStatistics()

QVector< int > Isis::Equalization::validateInputStatistics ( QString instatsFileName )

private

Validates the input statistics pvl file.

This method determines if each input image has a corresponding set of corrective factors (i.e. a normalization group). Throws an exception if this condition is not met.

Parameters

instatsFileName Name of the input statistics pvl file

Returns: QVector<int> The indices of the corrective factors for the input images

Exceptions

IException::User	"Each input file in the FROM LIST must have a corresponding input file in the INPUT STATISTICS."
IException::User	"The from list file does not have any corresponding file in the stats list."

Definition at line 956 of file Equalization.cpp.

References Isis::PvlObject::findObject(), Isis::PvlObject::group(), and Isis::PvlObject::groups().

◆ write()

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

Write the equalization information (results) to a file.

Parameters

outstatsFileName The name of the file to write the results to

Definition at line 582 of file Equalization.cpp.

Member Data Documentation

◆ m_alreadyCalculated

vector<bool> Isis::Equalization::m_alreadyCalculated

private

Which images that have statistics already calculated.

Definition at line 313 of file Equalization.h.

◆ m_badFiles

QStringList Isis::Equalization::m_badFiles

private

List of image names that don't overlap.

Definition at line 308 of file Equalization.h.

◆ m_doesOverlapList

vector<bool> Isis::Equalization::m_doesOverlapList

private

Which images have a valid overlap.

Definition at line 312 of file Equalization.h.

◆ m_holdIndices

vector<int> Isis::Equalization::m_holdIndices

private

Indices of images being held.

Definition at line 311 of file Equalization.h.

◆ m_invalidCnt

int Isis::Equalization::m_invalidCnt

private

Number of invalid overlaps.

Definition at line 302 of file Equalization.h.

◆ m_lsqMethod

LeastSquares::SolveMethod Isis::Equalization::m_lsqMethod

private

Least squares method for solving normalization correcitve factors.

Definition at line 320 of file Equalization.h.

◆ m_maxBand

int Isis::Equalization::m_maxBand

private

Number of bands in each input image.

Definition at line 306 of file Equalization.h.

◆ m_maxCube

int Isis::Equalization::m_maxCube

private

Number of input images.

Definition at line 305 of file Equalization.h.

◆ m_mincnt

int Isis::Equalization::m_mincnt

private

Minimum number of pixels for an overlap to be considered valid.

Definition at line 303 of file Equalization.h.

◆ m_normsSolved

bool Isis::Equalization::m_normsSolved

private

Indicates if corrective factors were solved.

Definition at line 292 of file Equalization.h.

◆ m_overlapNorms

vector<OverlapNormalization *> Isis::Equalization::m_overlapNorms

private

Normalization data for input images.

Definition at line 314 of file Equalization.h.

◆ m_overlapStats

vector<OverlapStatistics *> Isis::Equalization::m_overlapStats

private

Calculated overlap statistics.

Definition at line 315 of file Equalization.h.

◆ m_recalculating

bool Isis::Equalization::m_recalculating

private

Indicates if recalculating with loaded statistics.

Definition at line 293 of file Equalization.h.

◆ m_results

Pvl* Isis::Equalization::m_results

private

Calculation results and normalization corrective factors (if solved)

Definition at line 322 of file Equalization.h.

◆ m_samplingPercent

double Isis::Equalization::m_samplingPercent

private

Percentage of the lines to consider when gathering cube and overlap statistics (process-by-line)

Definition at line 298 of file Equalization.h.

◆ m_sType

OverlapNormalization::SolutionType Isis::Equalization::m_sType

private

The normalization solution type for solving normalizations (offsets, gains, or both)

Definition at line 318 of file Equalization.h.

◆ m_validCnt

int Isis::Equalization::m_validCnt

private

Number of valid overlaps.

Definition at line 301 of file Equalization.h.

◆ m_wtopt

bool Isis::Equalization::m_wtopt

private

Whether or not overlaps should be weighted.

Definition at line 294 of file Equalization.h.

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

src/base/objs/Equalization/Equalization.h
src/base/objs/Equalization/Equalization.cpp

Classes

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Equalization() [1/2]

◆ ~Equalization()

◆ Equalization() [2/2]

Member Function Documentation

◆ addAdjustment()

◆ addHolds()

◆ addInvalid()

◆ addValid()

◆ applyCorrection()

◆ calculateBandStatistics()

◆ calculateOverlapStatistics()

◆ calculateStatistics()

◆ clearAdjustments()

◆ clearNormalizations()

◆ clearOverlapStatistics()

◆ errorCheck()

◆ fromPvl()

◆ generateOutputs()

◆ getResults()

◆ importStatistics()

◆ init()

◆ isSolved()

◆ loadInputs()

◆ loadOutputs()

◆ recalculateStatistics()

◆ setResults()

◆ setSolved()

◆ validateInputStatistics()

◆ write()

Member Data Documentation

◆ m_alreadyCalculated

◆ m_badFiles

◆ m_doesOverlapList

◆ m_holdIndices

◆ m_invalidCnt

◆ m_lsqMethod

◆ m_maxBand

◆ m_maxCube

◆ m_mincnt

◆ m_normsSolved

◆ m_overlapNorms

◆ m_overlapStats

◆ m_recalculating

◆ m_results

◆ m_samplingPercent

◆ m_sType

◆ m_validCnt

◆ m_wtopt