Isis 3.0 Object Programmers' Reference

Home

---

Isis::Stretch Class Reference
[Utility]

#include <Stretch.h>

Collaboration diagram for Isis::Stretch:

[legend]List of all members.

---

Detailed Description

Pixel value mapper.

This class is used to stretch or remap pixel values. For example, it can be used to apply contrast stretches, color code stretches, or remap from a double range to 8-bit (0 to 255). The methodology used is straightforward. The program must set up a list of stretch pairs, input-to-output mappings, using the AddPair method. For example, (0,0) and (1,255) are two pairs which would cause an input of 0 to be mapped to 0, 0.5 would be mapped to 127.5 and 1 would be mapped to 255. More than two pairs can be used which generates piece-wise linear mappings. Special pixels are mapped to themselves unless overridden with methods such as SetNull. Input values outside the minimum and maximum input pair values are mapped to LRS and HRS respectively.

If you would like to see Stretch being used in implementation, see stretch.cpp

Author:

2002-05-15 Jeff Anderson

For internal use only.

History:

2002-09-17 Jeff Anderson - Added Parse method

History:

2003-05-16 Stuart Sides - Modified schema from astrogeology... isis.astrogeology...

History:

2005-02-16 Elizabeth Ribelin - Modified file to support Doxygen documentation

History:

2005-03-11 Elizabeth Ribelin - Modified unitTest to test all methods in the class

History:

2006-05-25 Jacob Danton - Fixed typo in documentation

History:

2007-03-02 Elizabeth Miller - Added Load and Save methods

History:

2008-11-12 Steven Lambright - Changed search algorithm into a binary search replacing a linear search.

History:

2009-04-30 Eric Hyer - One line setters now implemented in header file instead of cpp

• Modified parse method
  • added abstraction by letting NextPair handle low level details
• created second Parse method for handling pairs where the input side is a perentage
• created private NextPair method
• Fixed Input and Output getters to check both sides of boundry condition for valid data

History:

2009-07-16 Eric Hyer - Fixed bug introduced in AddPair by my last commit

• Renamed variable pair to avoid potential conflict with std::pair

Definition at line 77 of file Stretch.h.

Public Member Functions
	Stretch ()
	Constructs a Stretch object with default mapping of special pixel values to themselves.
	~Stretch ()
	Destroys the Stretch object.
void	AddPair (const double input, const double output)
	Adds a stretch pair to the list of pairs.
void	SetNull (const double value)
	Sets the mapping for NULL pixels.
void	SetLis (const double value)
	Sets the mapping for LIS pixels.
void	SetLrs (const double value)
	Sets the mapping for LRS pixels.
void	SetHis (const double value)
	Sets the mapping for HIS pixels.
void	SetHrs (const double value)
	Sets the mapping for HRS pixels.
void	SetMinimum (const double value)
void	SetMaximum (const double value)
void	Load (Pvl &pvl, std::string &grpName)
	Loads the stretch pairs from the pvl file into the Stretch object.
void	Save (Pvl &pvl, std::string &grpName)
void	Load (std::string &file, std::string &grpName)
	Loads the stretch pairs from the pvl file into the Stretch object.
void	Save (std::string &file, std::string &grpName)
	Saves the stretch pairs in the Stretch object into the given pvl file.
double	Map (const double value) const
	Maps an input value to an output value based on the stretch pairs and/or special pixel mappings.
void	Parse (const std::string &pairs)
	Parses a string of the form "i1:o1 i2:o2...iN:oN" where each i:o represents an input:output pair.
void	Parse (const std::string &pairs, const Isis::Histogram *hist)
	Parses a string of the form "i1:o1 i2:o2...iN:oN" where each i:o represents an input:output pair where the input is a percentage.
std::string	Text () const
	Converts stretch pair to a string.
int	Pairs () const
	Returns the number of stretch pairs.
double	Input (const int index) const
	Returns the value of the input side of the stretch pair at the specified index.
double	Output (const int index) const
	Returns the value of the output side of the stretch pair at the specified index.
void	ClearPairs ()
	Clears the stretch pairs.
void	CopyPairs (const Stretch &other)
	Copies the stretch pairs from another Stretch object, but maintains special pixel values.
Private Member Functions
std::pair< double, double >	NextPair (Isis::iString &pairs)
	Given a string containing stretch pairs for example "0:0 50:0 100:255 255:255" evaluate the first pair and return a pair of doubles where first is the first input and second is the first output.
Private Attributes
std::vector< double >	p_input
	Array for input side of stretch pairs.
std::vector< double >	p_output
	Array for output side of stretch pairs.
int	p_pairs
	Number of stretch pairs.
double	p_null
	Mapping of input NULL values go to this value (default NULL).
double	p_lis
	Mapping of input LIS values go to this value (default LIS).
double	p_lrs
	Mapping of input LRS values go to this value (default LRS).
double	p_his
	Mapping of input HIS values go to this value (default HIS).
double	p_hrs
	Mapping of input HRS values go to this value (default HRS).
double	p_minimum
	By default this value is set to p_lrs.
double	p_maximum
	By default this value is set to p_hrs.

---

Constructor & Destructor Documentation

Isis::Stretch::Stretch

(

)

Constructs a Stretch object with default mapping of special pixel values to themselves.

Definition at line 38 of file Stretch.cpp.

References Isis::HIGH_INSTR_SAT8, Isis::HIGH_REPR_SAT8, Isis::LOW_INSTR_SAT8, Isis::LOW_REPR_SAT8, Isis::NULL8, p_his, p_hrs, p_lis, p_lrs, p_maximum, p_minimum, p_null, and p_pairs.

Isis::Stretch::~Stretch

(

)

[inline]

Destroys the Stretch object.

Definition at line 102 of file Stretch.h.

---

Member Function Documentation

void Isis::Stretch::AddPair	(	const double	input,
		const double	output
	)

Adds a stretch pair to the list of pairs.

Note that all input pairs must be in ascending order.

Parameters:

	input	Input value to map
	output	Output value when the input is mapped

Exceptions:

Isis::iException::Programmer

- input pairs must be in ascending order

Definition at line 60 of file Stretch.cpp.

References _FILEINFO_, Isis::iException::Message(), p_input, p_output, and p_pairs.

Referenced by Qisis::ManualStretch::addPair(), Qisis::LinearStretch::calculateStretch(), Qisis::BinaryStretch::computeBinary(), Qisis::SawtoothStretch::computeSawtooths(), Qisis::ManualStretch::deletePair(), Isis::GaussianStretch::GaussianStretch(), Qisis::MosaicItem::getStretch(), Qisis::CubeViewport::initialStretch(), Qisis::LinearStretch::LinearStretch(), Load(), Parse(), Qisis::ScatterPlotData::ScatterPlotData(), Qisis::ManualStretch::setMinMax(), and Qisis::VisualDisplay::setPixelData().

void Isis::Stretch::ClearPairs

(

)

[inline]

Clears the stretch pairs.

Definition at line 173 of file Stretch.h.

References p_input, p_output, and p_pairs.

Referenced by Qisis::ManualStretch::addPair(), Qisis::LinearStretch::calculateStretch(), Qisis::BinaryStretch::computeBinary(), Qisis::SawtoothStretch::computeSawtooths(), Qisis::ManualStretch::deletePair(), Isis::GaussianStretch::GaussianStretch(), Qisis::CubeViewport::initialStretch(), Qisis::VisualDisplay::setPixelData(), Qisis::StretchTool::stretchBuffer(), and Qisis::StretchTool::stretchEntireCube().

void Isis::Stretch::CopyPairs

(

const Stretch &

other

)

Copies the stretch pairs from another Stretch object, but maintains special pixel values.

Parameters:

other

- The Stretch to copy pairs from

Definition at line 403 of file Stretch.cpp.

References p_input, p_output, and p_pairs.

Referenced by Qisis::CubeViewport::stretchGray().

double Isis::Stretch::Input

(

const int

index

)

const

Returns the value of the input side of the stretch pair at the specified index.

If the index number is out of bounds, then the method returns -1

Parameters:

index

The index number to retrieve the input stretch pair value from

Returns:

double The input side of the stretch pair at the specified index

Definition at line 298 of file Stretch.cpp.

References p_input, and p_pairs.

Referenced by Qisis::ManualStretch::addPair(), Qisis::ManualStretch::deletePair(), and Save().

void Isis::Stretch::Load	(	std::string &	file,
		std::string &	grpName
	)

Loads the stretch pairs from the pvl file into the Stretch object.

The file should look similar to this:

 Group = Pairs
   Input = (0,100,255)
   Output = (255,100,0)
 EndGroup

Parameters:

	file	- The input file containing the stretch pairs
	grpName	- The group name to get the input and output keywords from

Definition at line 334 of file Stretch.cpp.

References Load(), and pvl().

void Isis::Stretch::Load	(	Isis::Pvl &	pvl,
		std::string &	grpName
	)

Loads the stretch pairs from the pvl file into the Stretch object.

The pvl should look similar to this:

 Group = Pairs
   Input = (0,100,255)
   Output = (255,100,0)
 EndGroup

Parameters:

	pvl	- The pvl containing the stretch pairs
	grpName	- The group name to get the input and output keywords from

Definition at line 353 of file Stretch.cpp.

References _FILEINFO_, AddPair(), Isis::PvlContainer::FindKeyword(), Isis::iException::Message(), pvl(), Isis::PvlKeyword::Size(), and Isis::PvlObject::Traverse.

Referenced by Load().

double Isis::Stretch::Map

(

const double

value

)

const

Maps an input value to an output value based on the stretch pairs and/or special pixel mappings.

Parameters:

value

Value to map

Returns:

double The mapped output value is returned by this method

Definition at line 81 of file Stretch.cpp.

References Isis::IsHisPixel(), Isis::IsHrsPixel(), Isis::IsLisPixel(), Isis::IsNullPixel(), Isis::IsValidPixel(), p_his, p_hrs, p_input, p_lis, p_lrs, p_maximum, p_minimum, p_null, p_output, and p_pairs.

Referenced by Qisis::MosaicItem::drawImage(), Isis::GaussianStretch::Map(), Qisis::ChipViewport::paintImage(), Qisis::VisualDisplay::paintPixmap(), Qisis::CubeViewport::paintPixmap(), Qisis::ScatterPlotData::ScatterPlotData(), and Qisis::ScatterPlotData::value().

std::pair< double, double > Isis::Stretch::NextPair

(

Isis::iString &

pairs

)

[private]

Given a string containing stretch pairs for example "0:0 50:0 100:255 255:255" evaluate the first pair and return a pair of doubles where first is the first input and second is the first output.

Parameters:

pairs

A string containing stretch pairs for example "0:0 50:0 100:255 255:255"

Exceptions:

Isis::iException::User

- invalid stretch pair

Returns:

std::pair of doubles where first is the first input and second is the first output

Definition at line 157 of file Stretch.cpp.

References _FILEINFO_, Isis::iException::Message(), Isis::iString::ToDouble(), Isis::iString::Token(), Isis::iString::Trim(), and Isis::iString::TrimHead().

Referenced by Parse().

double Isis::Stretch::Output

(

const int

index

)

const

Returns the value of the output side of the stretch pair at the specified index.

If the index number is out of bounds, then the method returns -1.

Parameters:

index

The index number to retieve the output stretch pair value from

Returns:

double The output side of the stretch pair at the specified index

Definition at line 313 of file Stretch.cpp.

References p_output, and p_pairs.

Referenced by Qisis::ManualStretch::addPair(), Qisis::ManualStretch::deletePair(), and Save().

int Isis::Stretch::Pairs

(

)

const [inline]

Returns the number of stretch pairs.

Definition at line 167 of file Stretch.h.

References p_pairs.

Referenced by Qisis::ManualStretch::addPair(), Qisis::ManualStretch::deletePair(), Qisis::MosaicItem::getStretch(), Save(), Qisis::ManualStretch::setMinMax(), and Qisis::StretchTool::stretchGlobal().

void Isis::Stretch::Parse	(	const std::string &	pairs,
		const Isis::Histogram *	hist
	)

Parses a string of the form "i1:o1 i2:o2...iN:oN" where each i:o represents an input:output pair where the input is a percentage.

Using the Histogram an appropriate dn value will be calculated for each input percentage. Therefore, the user can enter a string in this form and this method will parse the string and load the stretch pairs into the object via AddPairs.

Parameters:

pairs

A string containing stretch pairs for example "0:0 50:0 100:255"

Exceptions:

Isis::iException::User

- invalid stretch pair

Definition at line 227 of file Stretch.cpp.

References _FILEINFO_, AddPair(), e, Isis::iException::Message(), NextPair(), p_input, p_output, p_pairs, Isis::Histogram::Percent(), and Isis::iString::TrimHead().

void Isis::Stretch::Parse

(

const std::string &

pairs

)

Parses a string of the form "i1:o1 i2:o2...iN:oN" where each i:o represents an input:output pair.

Therefore, the user can enter a string in this form and this method will parse the string and load the stretch pairs into the object via AddPairs.

Parameters:

pairs

A string containing stretch pairs for example "0:0 50:0 100:255 255:255"

Exceptions:

Isis::iException::User

- invalid stretch pair

Definition at line 191 of file Stretch.cpp.

References _FILEINFO_, AddPair(), e, Isis::iException::Message(), NextPair(), p_input, p_output, p_pairs, and Isis::iString::TrimHead().

Referenced by Qisis::CubeViewport::stretchGray(), and Qisis::CubeViewport::stretchRGB().

void Isis::Stretch::Save	(	std::string &	file,
		std::string &	grpName
	)

Saves the stretch pairs in the Stretch object into the given pvl file.

Parameters:

	file	- The file that the stretch pairs will be written to
	grpName	- The name of the group to create and put the stretch pairs into. The group will contain two keywords, Input, and Output.

Definition at line 378 of file Stretch.cpp.

References Save(), and Isis::Pvl::Write().

void Isis::Stretch::SetHis

(

const double

value

)

[inline]

Sets the mapping for HIS pixels.

If not called the HIS pixels will be mapped to HIS. Otherwise you can map HIS to any double value. For example, SetHis(255.0).

Parameters:

value

Value to map input HIS

Definition at line 140 of file Stretch.h.

References p_his.

Referenced by Qisis::CubeViewport::BandInfo::BandInfo(), Qisis::ChipViewport::BandInfo::BandInfo(), Qisis::MosaicItem::getStretch(), Qisis::QStretch::QStretch(), and Qisis::VisualDisplay::VisualDisplay().

void Isis::Stretch::SetHrs

(

const double

value

)

[inline]

Sets the mapping for HRS pixels.

If not called the HRS pixels will be mapped to HRS. Otherwise you can map HRS to any double value. For example, SetHrs(255.0).

Parameters:

value

Value to map input HRS

Definition at line 149 of file Stretch.h.

References p_hrs.

Referenced by Qisis::CubeViewport::BandInfo::BandInfo(), Qisis::ChipViewport::BandInfo::BandInfo(), Qisis::MosaicItem::getStretch(), Qisis::QStretch::QStretch(), and Qisis::VisualDisplay::VisualDisplay().

void Isis::Stretch::SetLis

(

const double

value

)

[inline]

Sets the mapping for LIS pixels.

If not called the LIS pixels will be mapped to LIS. Otherwise you can map LIS to any double value. For example, SetLis(0.0).

Parameters:

value

Value to map input LIS

Definition at line 122 of file Stretch.h.

References p_lis.

Referenced by Qisis::CubeViewport::BandInfo::BandInfo(), Qisis::ChipViewport::BandInfo::BandInfo(), Qisis::MosaicItem::getStretch(), Qisis::QStretch::QStretch(), and Qisis::VisualDisplay::VisualDisplay().

void Isis::Stretch::SetLrs

(

const double

value

)

[inline]

Sets the mapping for LRS pixels.

If not called the LRS pixels will be mapped to LRS. Otherwise you can map LRS to any double value. For example, SetLrs(0.0).

Parameters:

value

Value to map input LRS

Definition at line 131 of file Stretch.h.

References p_lrs.

Referenced by Qisis::CubeViewport::BandInfo::BandInfo(), Qisis::ChipViewport::BandInfo::BandInfo(), Qisis::MosaicItem::getStretch(), Qisis::QStretch::QStretch(), and Qisis::VisualDisplay::VisualDisplay().

void Isis::Stretch::SetNull

(

const double

value

)

[inline]

Sets the mapping for NULL pixels.

If not called the NULL pixels will be mapped to NULL. Otherwise you can map NULLs to any double value. For example, SetNull(0.0).

Parameters:

value

Value to map input NULLs

Definition at line 113 of file Stretch.h.

References p_null.

Referenced by Qisis::CubeViewport::BandInfo::BandInfo(), Qisis::ChipViewport::BandInfo::BandInfo(), Qisis::MosaicItem::getStretch(), Qisis::QStretch::QStretch(), and Qisis::VisualDisplay::VisualDisplay().

string Isis::Stretch::Text

(

)

const

Converts stretch pair to a string.

Returns:

string The stretch pair as a string

Definition at line 279 of file Stretch.cpp.

References p_input, p_output, p_pairs, and Isis::iString::TrimTail().

---

Member Data Documentation

double Isis::Stretch::p_his [private]

Mapping of input HIS values go to this value (default HIS).

Definition at line 89 of file Stretch.h.

Referenced by Map(), SetHis(), and Stretch().

double Isis::Stretch::p_hrs [private]

Mapping of input HRS values go to this value (default HRS).

Definition at line 91 of file Stretch.h.

Referenced by Map(), SetHrs(), and Stretch().

std::vector<double> Isis::Stretch::p_input [private]

Array for input side of stretch pairs.

Definition at line 79 of file Stretch.h.

Referenced by AddPair(), ClearPairs(), CopyPairs(), Input(), Map(), Parse(), and Text().

double Isis::Stretch::p_lis [private]

Mapping of input LIS values go to this value (default LIS).

Definition at line 85 of file Stretch.h.

Referenced by Map(), SetLis(), and Stretch().

double Isis::Stretch::p_lrs [private]

Mapping of input LRS values go to this value (default LRS).

Definition at line 87 of file Stretch.h.

Referenced by Map(), SetLrs(), and Stretch().

double Isis::Stretch::p_maximum [private]

By default this value is set to p_hrs.

Definition at line 94 of file Stretch.h.

Referenced by Map(), SetMaximum(), and Stretch().

double Isis::Stretch::p_minimum [private]

By default this value is set to p_lrs.

Definition at line 93 of file Stretch.h.

Referenced by Map(), SetMinimum(), and Stretch().

double Isis::Stretch::p_null [private]

Mapping of input NULL values go to this value (default NULL).

Definition at line 83 of file Stretch.h.

Referenced by Map(), SetNull(), and Stretch().

std::vector<double> Isis::Stretch::p_output [private]

Array for output side of stretch pairs.

Definition at line 80 of file Stretch.h.

Referenced by AddPair(), ClearPairs(), CopyPairs(), Map(), Output(), Parse(), and Text().

int Isis::Stretch::p_pairs [private]

Number of stretch pairs.

Definition at line 81 of file Stretch.h.

Referenced by AddPair(), ClearPairs(), CopyPairs(), Input(), Map(), Output(), Pairs(), Parse(), Stretch(), and Text().

---

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

• src/base/objs/Stretch/Stretch.h
• src/base/objs/Stretch/Stretch.cpp