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

#include <OverlapNormalization.h>

Collaboration diagram for Isis::OverlapNormalization:

Classes
class	Overlap
	Store statistics pertaining to the overlapping areas and indices (corresponding to the statistics list) for two data sets. More...

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.

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

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.

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

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

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

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

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

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.

Private Member Functions
OverlapNormalization &	operator= (const OverlapNormalization &)
	Cannot copy this object.

	OverlapNormalization (const OverlapNormalization &)
	Cannot copy this object.

Private Attributes
std::vector< Statistics * >	m_statsList
	Vector of Statistics objects for each data set.

std::vector< int >	m_idHoldList
	Vector of indices corresponding to the m_statsList vector representing data sets to be held in solution.

std::vector< Overlap >	m_overlapList
	Vector of valid overlaps collected.

std::vector< double >	m_deltas
	Vector of delta values (differences between the averages of two overlapping data sets) for every valid overlap.

std::vector< double >	m_weights
	Vector of weights for every valid overlap.

bool	m_solved
	Whether or not the least squares solution has been solved.

SolutionType	m_solutionType
	Whether the user of this class wants to solve for the offsets, the gains, or both.

std::vector< double >	m_gains
	Vector of calculated gains filled by the Solve method.

std::vector< double >	m_offsets
	Vector of calculated offsets filled by the Solve method.

BasisFunction *	m_gainFunction
	The gain function to be solved.

BasisFunction *	m_offsetFunction
	The offset function to be solved.

LeastSquares *	m_gainLsq
	The least squares object that solves for the new gains.

LeastSquares *	m_offsetLsq
	The least squares object that calculates offsets.

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

History

2009-06-05 Mackenzie Boyd - fixed unittest to work on all systems

2009-06-12 Travis Addair - changed public interface to use indices instead of file names and renamed from IntersectionStatistics

2009-06-15 Travis Addair - documented all variables/enums

2009-06-24 Travis Addair - changed gain and offset vectors to itialize to 1.0 and 0.0, respectively

2009-11-25 Travis Addair - held images are now weighted to ensure gain and offset of 1.0 and 0.0, respectively

2013-12-29 Jeannie Backer - Added LeastSquares::SolveMethod input parameter to Solve() method. Improved error message. Fixes #962,

2013-02-14 Steven Lambright - Added SolutionType GainsWithoutNormalization. Fixes #911.

2019-09-05 Makayla Shepherd & Jesse Mapel - Changed weight for hold images from 1E30 to 1E10 to avoid poorly conditioned normal matrix.

Definition at line 61 of file OverlapNormalization.h.

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.

Definition at line 75 of file OverlapNormalization.h.

◆ 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

Definition at line 111 of file OverlapNormalization.h.

Constructor & Destructor Documentation

◆ OverlapNormalization() [1/2]

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)

Definition at line 29 of file OverlapNormalization.cpp.

References m_gainFunction, m_gainLsq, m_gains, m_offsetFunction, m_offsetLsq, m_offsets, m_solved, and m_statsList.

◆ ~OverlapNormalization()

Isis::OverlapNormalization::~OverlapNormalization ( )

virtual

Destroys the OverlapNormalization object, frees up pointers.

Definition at line 56 of file OverlapNormalization.cpp.

References m_gainFunction, m_gainLsq, m_offsetFunction, m_offsetLsq, and m_statsList.

◆ OverlapNormalization() [2/2]

Isis::OverlapNormalization::OverlapNormalization ( const OverlapNormalization & )

private

Cannot copy this object.

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

Definition at line 103 of file OverlapNormalization.h.

References m_idHoldList.

◆ 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

Definition at line 90 of file OverlapNormalization.cpp.

References Isis::OverlapNormalization::Overlap::area1, Isis::Statistics::Average(), m_deltas, m_overlapList, m_solved, m_statsList, m_weights, NoContrast, NoOverlap, Isis::IException::Programmer, Success, and Isis::Statistics::ValidPixels().

◆ 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

Definition at line 293 of file OverlapNormalization.cpp.

References m_statsList, and Isis::IException::Programmer.

Referenced by Evaluate().

◆ 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

Definition at line 358 of file OverlapNormalization.cpp.

References Average(), Gain(), Isis::IsSpecial(), m_solved, Offset(), and Isis::IException::Programmer.

◆ 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

Definition at line 314 of file OverlapNormalization.cpp.

References m_gains, m_statsList, and Isis::IException::Programmer.

Referenced by Evaluate().

◆ 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

Definition at line 335 of file OverlapNormalization.cpp.

References m_offsets, m_statsList, and Isis::IException::Programmer.

Referenced by Evaluate().

◆ operator=()

OverlapNormalization & Isis::OverlapNormalization::operator= ( const OverlapNormalization & )

private

Cannot copy this object.

◆ 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

Definition at line 147 of file OverlapNormalization.cpp.

References Isis::LeastSquares::AddKnown(), Isis::BasisFunction::Coefficient(), Isis::BasisFunction::Coefficients(), Gains, GainsWithoutNormalization, Isis::OverlapNormalization::Overlap::index1, m_deltas, m_gainFunction, m_gainLsq, m_gains, m_idHoldList, m_offsetFunction, m_offsetLsq, m_offsets, m_overlapList, m_solved, m_statsList, m_weights, Offsets, Isis::LeastSquares::Solve(), Isis::LeastSquares::SPARSE, and Isis::IException::User.

Member Data Documentation

◆ m_deltas

std::vector<double> Isis::OverlapNormalization::m_deltas

private

Vector of delta values (differences between the averages of two overlapping data sets) for every valid overlap.

Definition at line 204 of file OverlapNormalization.h.

Referenced by AddOverlap(), and Solve().

◆ m_gainFunction

BasisFunction* Isis::OverlapNormalization::m_gainFunction

private

The gain function to be solved.

Definition at line 237 of file OverlapNormalization.h.

Referenced by OverlapNormalization(), Solve(), and ~OverlapNormalization().

◆ m_gainLsq

LeastSquares* Isis::OverlapNormalization::m_gainLsq

private

The least squares object that solves for the new gains.

Definition at line 247 of file OverlapNormalization.h.

Referenced by OverlapNormalization(), Solve(), and ~OverlapNormalization().

◆ m_gains

std::vector<double> Isis::OverlapNormalization::m_gains

private

Vector of calculated gains filled by the Solve method.

Definition at line 226 of file OverlapNormalization.h.

Referenced by Gain(), OverlapNormalization(), and Solve().

◆ m_idHoldList

std::vector<int> Isis::OverlapNormalization::m_idHoldList

private

Vector of indices corresponding to the m_statsList vector representing data sets to be held in solution.

Definition at line 158 of file OverlapNormalization.h.

Referenced by AddHold(), and Solve().

◆ m_offsetFunction

BasisFunction* Isis::OverlapNormalization::m_offsetFunction

private

The offset function to be solved.

Definition at line 242 of file OverlapNormalization.h.

Referenced by OverlapNormalization(), Solve(), and ~OverlapNormalization().

◆ m_offsetLsq

LeastSquares* Isis::OverlapNormalization::m_offsetLsq

private

The least squares object that calculates offsets.

Definition at line 252 of file OverlapNormalization.h.

Referenced by OverlapNormalization(), Solve(), and ~OverlapNormalization().

◆ m_offsets

std::vector<double> Isis::OverlapNormalization::m_offsets

private

Vector of calculated offsets filled by the Solve method.

Definition at line 231 of file OverlapNormalization.h.

Referenced by Offset(), OverlapNormalization(), and Solve().

◆ m_overlapList

std::vector<Overlap> Isis::OverlapNormalization::m_overlapList

private

Vector of valid overlaps collected.

Definition at line 198 of file OverlapNormalization.h.

Referenced by AddOverlap(), and Solve().

◆ m_solutionType

SolutionType Isis::OverlapNormalization::m_solutionType

private

Whether the user of this class wants to solve for the offsets, the gains, or both.

Definition at line 221 of file OverlapNormalization.h.

◆ m_solved

bool Isis::OverlapNormalization::m_solved

private

Whether or not the least squares solution has been solved.

Definition at line 215 of file OverlapNormalization.h.

Referenced by AddOverlap(), Evaluate(), OverlapNormalization(), and Solve().

◆ m_statsList

std::vector<Statistics *> Isis::OverlapNormalization::m_statsList

private

Vector of Statistics objects for each data set.

Definition at line 152 of file OverlapNormalization.h.

Referenced by AddOverlap(), Average(), Gain(), Offset(), OverlapNormalization(), Solve(), and ~OverlapNormalization().

◆ m_weights

std::vector<double> Isis::OverlapNormalization::m_weights

private

Vector of weights for every valid overlap.

Definition at line 209 of file OverlapNormalization.h.

Referenced by AddOverlap(), and Solve().

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

src/base/objs/OverlapNormalization/OverlapNormalization.h
src/base/objs/OverlapNormalization/OverlapNormalization.cpp

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ AddStatus

◆ SolutionType

Constructor & Destructor Documentation

◆ OverlapNormalization() [1/2]

◆ ~OverlapNormalization()

◆ OverlapNormalization() [2/2]

Member Function Documentation

◆ AddHold()

◆ AddOverlap()

◆ Average()

◆ Evaluate()

◆ Gain()

◆ Offset()

◆ operator=()

◆ Solve()

Member Data Documentation

◆ m_deltas

◆ m_gainFunction

◆ m_gainLsq

◆ m_gains

◆ m_idHoldList

◆ m_offsetFunction

◆ m_offsetLsq

◆ m_offsets

◆ m_overlapList

◆ m_solutionType

◆ m_solved

◆ m_statsList

◆ m_weights