Calculate the bases and multipliers for normalizing overlapping "data sets" (e.g., cubes). More...

#include <OverlapNormalization.h>

Collaboration diagram for Isis::OverlapNormalization:

Public Types
enum	AddStatus { Success, NoOverlap, NoContrast }
	The result of the attempt to add overlap data to the list of valid overlaps, where Success is a successful add, NoOverlap is a failure due to one or both Statistics objects containing no data, and NoContrast is a failure due to one or both averages being 0. More...

enum	SolutionType { Gains, Offsets, Both, GainsWithoutNormalization }
	Enumeration for whether user/programmer wants to calculate new gains, offsets, or both when solving. More...

Public Member Functions
	OverlapNormalization (std::vector< Statistics *> statsList)
	Constructs an OverlapNormalization object. More...

virtual	~OverlapNormalization ()
	Destroys the OverlapNormalization object, frees up pointers. More...

AddStatus	AddOverlap (const Statistics &area1, const unsigned index1, const Statistics &area2, const unsigned index2, double weight=1.0)
	Attempts to add the given overlap data to a collection of valid overlaps, and returns the success or failure of that attempt. More...

void	AddHold (unsigned holdIndex)
	Sets the list of files to be held during the solving process. More...

void	Solve (SolutionType type=Both, LeastSquares::SolveMethod method=LeastSquares::QRD)
	Attempts to solve the least squares equation for all data sets. More...

double	Average (const unsigned index) const
	Returns the calculated average DN value for the given data set. More...

double	Gain (const unsigned index) const
	Returns the calculated gain (multiplier) for the given data set. More...

double	Offset (const unsigned index) const
	Returns the calculated offset (base) for the given data set. More...

double	Evaluate (double dn, unsigned index) const
	Returns a new DN from an old using the calculated gains and offsets of the data set the pixel belongs to. More...

Detailed Description

Calculate the bases and multipliers for normalizing overlapping "data sets" (e.g., cubes).

Specifically, this class is designed for normalizing data in equalization applications such as equalizer and hiequal. Given collections for statistical data sets, overlapping statistics between these sets, and at least one data set to be "held", this class will use a least squares solution to calculate gain and offset coefficients for every set of data in the collection.

Once the multiplicative and additive corrections have been derived, this class can then be used to calculate new DN values for a known data set. The actual equation to be used for calculating new DN values with the derived gains and offsets is:

\[ newDN = (oldDN - avg(i)) * MULT(i) + avg(i) + BASE(i) \]

where i is the index of a known data set from the statistics list.

Author: 2009-05-07 Travis Addair

Member Enumeration Documentation

◆ AddStatus

enum Isis::OverlapNormalization::AddStatus

The result of the attempt to add overlap data to the list of valid overlaps, where Success is a successful add, NoOverlap is a failure due to one or both Statistics objects containing no data, and NoContrast is a failure due to one or both averages being 0.

Enumerator
Success	Overlap is valid and was added successfully.
NoOverlap	Data sets do not overlap one another.
NoContrast	One or both areas contain no valid average.

◆ SolutionType

enum Isis::OverlapNormalization::SolutionType

Enumeration for whether user/programmer wants to calculate new gains, offsets, or both when solving.

Enumerator
Gains	Calculate only the gains.
Offsets	Calculate only the offsets.
Both	Calculate both gains and offsets.
GainsWithoutNormalization	The equation being solved for Gains, Offsets, and Both is output = (input - average) * gain + offset + average. This solution type is for the equation output = input * gain

Constructor & Destructor Documentation

◆ OverlapNormalization()

Isis::OverlapNormalization::OverlapNormalization ( std::vector< Statistics *> statsList )

Constructs an OverlapNormalization object.

Compares and stores the vector, and initializes the basis and least squares functions. This object will also take ownership of the pointers in the vector parameter.

Parameters

statsList The list of Statistics objects corresponding to specific data sets (e.g., cubes)

◆ ~OverlapNormalization()

Isis::OverlapNormalization::~OverlapNormalization ( )

virtual

Destroys the OverlapNormalization object, frees up pointers.

Member Function Documentation

◆ AddHold()

void Isis::OverlapNormalization::AddHold ( unsigned holdIndex )

inline

Sets the list of files to be held during the solving process.

Parameters

holdIndex The index of a set of data from the list of Statistics objects to be held

Referenced by Isis::Equalization::loadHolds().

◆ AddOverlap()

OverlapNormalization::AddStatus Isis::OverlapNormalization::AddOverlap	(	const Statistics &	area1,
		const unsigned	index1,
		const Statistics &	area2,
		const unsigned	index2,
		double	weight = `1.0`
	)

Attempts to add the given overlap data to a collection of valid overlaps, and returns the success or failure of that attempt.

Parameters

area1	The statistics for the overlap area of the first overlapping data set
index1	The index in the list of Statistics of the first data set
area2	The statistics for the overlap area of the second data set
index2	The index in the list of Statistics of the second overlapping data set
weight	Relative significance of this overlap. Default value = 1.0

Returns: AddStatus An enumeration representing either a successful add, or the reason for failure

Exceptions

Isis::iException::Programmer	- Identifying index 1 must exist in the statsList
Isis::iException::Programmer	- Identifying index 2 must exist in the statsList
Isis::iException::Programmer	- Weights must be all positive real numbers

References _FILEINFO_, Isis::Statistics::Average(), and Isis::Statistics::ValidPixels().

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

◆ Average()

double Isis::OverlapNormalization::Average ( const unsigned index ) const

Returns the calculated average DN value for the given data set.

Parameters

index The index in the Statistics list corresponding to the data set desired

Returns: double The average for the data

Exceptions

Isis::iException::Programmer - Identifying index must exist in the statsList

References _FILEINFO_.

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

◆ Evaluate()

double Isis::OverlapNormalization::Evaluate	(	double	dn,
		unsigned	index
	)		const

Returns a new DN from an old using the calculated gains and offsets of the data set the pixel belongs to.

Parameters

dn	The value of the pixel prior to equalization
index	The index in the Statistics list corresponding to the data set for the pixel

Returns: double The newly calculated DN value

Exceptions

Isis::iException::Programmer - Least Squares equation must be solved before returning the gain

References _FILEINFO_, and Isis::IsSpecial().

◆ Gain()

double Isis::OverlapNormalization::Gain ( const unsigned index ) const

Returns the calculated gain (multiplier) for the given data set.

Parameters

index The index in the Statistics list corresponding to the data set desired

Returns: double The gain for the data

Exceptions

Isis::iException::Programmer - Identifying index must exist in the statsList

References _FILEINFO_.

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

◆ Offset()

double Isis::OverlapNormalization::Offset ( const unsigned index ) const

Returns the calculated offset (base) for the given data set.

Parameters

index The index in the Statistics list corresponding to the data set desired

Returns: double The offset for the data

Exceptions

Isis::iException::Programmer - Identifying index must exist in the statsList

References _FILEINFO_.

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

◆ Solve()

void Isis::OverlapNormalization::Solve	(	SolutionType	type = `Both`,
		LeastSquares::SolveMethod	method = `LeastSquares::QRD`
	)

Attempts to solve the least squares equation for all data sets.

Parameters

type	The enumeration clarifying whether the offset, gain, or both should be solved here
method	The enumeration clarifying the LeastSquares::SolveMethod to be used.

Returns: bool Is the least squares equation now solved

Exceptions

Isis::iException::User - Number of overlaps and holds must be greater than the number of data sets

References _FILEINFO_.

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

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

/usgs/pkgs/isis3.9.0_docs/ISIS3/isis/src/base/objs/OverlapNormalization/OverlapNormalization.h
/usgs/pkgs/isis3.9.0_docs/ISIS3/isis/src/base/objs/OverlapNormalization/OverlapNormalization.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ AddStatus

◆ SolutionType

Constructor & Destructor Documentation

◆ OverlapNormalization()

◆ ~OverlapNormalization()

Member Function Documentation

◆ AddHold()

◆ AddOverlap()

◆ Average()

◆ Evaluate()

◆ Gain()

◆ Offset()

◆ Solve()