Isis 3 Programmer Reference
Isis::OverlapNormalization Class Reference

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

#include <OverlapNormalization.h>

Collaboration diagram for Isis::OverlapNormalization:
Collaboration graph

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

Private Member Functions

OverlapNormalizationoperator= (const OverlapNormalization &)
 Cannot copy this object. More...
 
 OverlapNormalization (const OverlapNormalization &)
 Cannot copy this object. More...
 

Private Attributes

std::vector< Statistics * > m_statsList
 Vector of Statistics objects for each data set. More...
 
std::vector< int > m_idHoldList
 Vector of indices corresponding to the m_statsList vector representing data sets to be held in solution. More...
 
std::vector< Overlapm_overlapList
 Vector of valid overlaps collected. More...
 
std::vector< double > m_deltas
 Vector of delta values (differences between the averages of two overlapping data sets) for every valid overlap. More...
 
std::vector< double > m_weights
 Vector of weights for every valid overlap. More...
 
bool m_solved
 Whether or not the least squares solution has been solved. More...
 
SolutionType m_solutionType
 Whether the user of this class wants to solve for the offsets, the gains, or both. More...
 
std::vector< double > m_gains
 Vector of calculated gains filled by the Solve method. More...
 
std::vector< double > m_offsets
 Vector of calculated offsets filled by the Solve method. More...
 
BasisFunctionm_gainFunction
 The gain function to be solved. More...
 
BasisFunctionm_offsetFunction
 The offset function to be solved. More...
 
LeastSquaresm_gainLsq
 The least squares object that solves for the new gains. More...
 
LeastSquaresm_offsetLsq
 The least squares object that calculates offsets. 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
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 77 of file OverlapNormalization.h.

Member Enumeration Documentation

◆ 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 91 of file OverlapNormalization.h.

◆ 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 127 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
statsListThe list of Statistics objects corresponding to specific data sets (e.g., cubes)

Definition at line 45 of file OverlapNormalization.cpp.

◆ ~OverlapNormalization()

Isis::OverlapNormalization::~OverlapNormalization ( )
virtual

Destroys the OverlapNormalization object, frees up pointers.

Definition at line 72 of file OverlapNormalization.cpp.

◆ 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
holdIndexThe index of a set of data from the list of Statistics objects to be held

Definition at line 119 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
area1The statistics for the overlap area of the first overlapping data set
index1The index in the list of Statistics of the first data set
area2The statistics for the overlap area of the second data set
index2The index in the list of Statistics of the second overlapping data set
weightRelative 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 106 of file OverlapNormalization.cpp.

References _FILEINFO_, Isis::OverlapNormalization::Overlap::area1, Isis::OverlapNormalization::Overlap::area2, Isis::Statistics::Average(), Isis::OverlapNormalization::Overlap::index1, Isis::OverlapNormalization::Overlap::index2, 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
indexThe 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 309 of file OverlapNormalization.cpp.

References _FILEINFO_.

◆ 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
dnThe value of the pixel prior to equalization
indexThe 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 374 of file OverlapNormalization.cpp.

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
indexThe 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 330 of file OverlapNormalization.cpp.

References _FILEINFO_.

◆ Offset()

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

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

Parameters
indexThe 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 351 of file OverlapNormalization.cpp.

References _FILEINFO_.

◆ 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
typeThe enumeration clarifying whether the offset, gain, or both should be solved here
methodThe 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 163 of file OverlapNormalization.cpp.

References _FILEINFO_, Isis::OverlapNormalization::Overlap::area1, Isis::OverlapNormalization::Overlap::area2, Isis::Statistics::Average(), Isis::OverlapNormalization::Overlap::index1, Isis::OverlapNormalization::Overlap::index2, and Isis::Statistics::StandardDeviation().

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 220 of file OverlapNormalization.h.

◆ m_gainFunction

BasisFunction* Isis::OverlapNormalization::m_gainFunction
private

The gain function to be solved.

Definition at line 253 of file OverlapNormalization.h.

◆ m_gainLsq

LeastSquares* Isis::OverlapNormalization::m_gainLsq
private

The least squares object that solves for the new gains.

Definition at line 263 of file OverlapNormalization.h.

◆ m_gains

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

Vector of calculated gains filled by the Solve method.

Definition at line 242 of file OverlapNormalization.h.

◆ 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 174 of file OverlapNormalization.h.

Referenced by AddHold().

◆ m_offsetFunction

BasisFunction* Isis::OverlapNormalization::m_offsetFunction
private

The offset function to be solved.

Definition at line 258 of file OverlapNormalization.h.

◆ m_offsetLsq

LeastSquares* Isis::OverlapNormalization::m_offsetLsq
private

The least squares object that calculates offsets.

Definition at line 268 of file OverlapNormalization.h.

◆ m_offsets

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

Vector of calculated offsets filled by the Solve method.

Definition at line 247 of file OverlapNormalization.h.

◆ m_overlapList

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

Vector of valid overlaps collected.

Definition at line 214 of file OverlapNormalization.h.

◆ 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 237 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 231 of file OverlapNormalization.h.

◆ m_statsList

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

Vector of Statistics objects for each data set.

Definition at line 168 of file OverlapNormalization.h.

◆ m_weights

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

Vector of weights for every valid overlap.

Definition at line 225 of file OverlapNormalization.h.


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