This class is used to find the overlaps between all the images in a list of serial numbers. More...

#include <ImageOverlapSet.h>

Inheritance diagram for Isis::ImageOverlapSet:

Collaboration diagram for Isis::ImageOverlapSet:

Public Member Functions
	ImageOverlapSet (bool continueOnError=false, bool useThread=true)
	Create FindImageOverlaps object. More...

virtual	~ImageOverlapSet ()
	Delete this object. More...

void	FindImageOverlaps (SerialNumberList &boundaries)
	Create polygons of overlap from the images specified in the serial number list. More...

void	FindImageOverlaps (std::vector< QString > sns, std::vector< geos::geom::MultiPolygon * > polygons)
	This is a strict pthread implementation of this class' multi-threading! More...

void	FindImageOverlaps (SerialNumberList &boundaries, QString outputFile)
	This method calculates image overlaps given a SerialNumberList and writes it to the filename specified by outputFile. More...

void	ReadImageOverlaps (const QString &filename)
	Create polygons of overlap from the file specified. More...

void	WriteImageOverlaps (const QString &filename)
	Write polygons of overlap to the file specified. More...

int	Size ()
	Returns the total number of latitude and longitude overlaps. More...

const ImageOverlap *	operator[] (int index)
	Returns the images which overlap at a given loverlap. More...

std::vector< ImageOverlap * >	operator[] (QString serialNumber)
	Return the overlaps that have a specific serial number. More...

const std::vector< PvlGroup > &	Errors ()
	Return the a list of errors encountered. More...

Protected Member Functions
void	FindAllOverlaps (SerialNumberList *snlist=NULL)
	Find the overlaps between all the existing ImageOverlap Objects. More...

void	AddSerialNumbers (ImageOverlap to, ImageOverlap from)
	Add the serial numbers from the second overlap to the first. More...

Protected Attributes
std::vector< PvlGroup >	p_errorLog
	This is a list of detailed* errors including all known information. More...

Private Member Functions
void	run ()
	Find overlaps is all the threaded calculate does. More...

void	DespikeLonLatOverlaps ()
	Despikes all of the overlaps in p_lonLatOverlaps. More...

ImageOverlap *	CreateNewOverlap (QString serialNumber, geos::geom::MultiPolygon *lonLatPolygon)
	Create an overlap item to hold the overlap poly and its SN. More...

bool	SetPolygon (geos::geom::Geometry poly, int position, ImageOverlap sncopy=NULL, bool insert=false)
	This method inserts or overwrites a polygon in the overlap list based on parameters. More...

void	HandleError (IException &e, SerialNumberList *snlist, QString msg="", int overlap1=-1, int overlap2=-1)
	If a problem occurred when searching for image overlaps, this method will handle it. More...

void	HandleError (geos::util::GEOSException exc, SerialNumberList snlist, QString msg="", int overlap1=-1, int overlap2=-1)
	If a problem occurred when searching for image overlaps, this method will handle it. More...

void	HandleError (SerialNumberList *snlist, QString msg, int overlap1=-1, int overlap2=-1)
	If a problem occurred when searching for image overlaps, this method will handle it. More...

Private Attributes
QList< ImageOverlap * >	p_lonLatOverlaps
	The list of lat/lon overlaps. More...

bool	p_continueAfterError
	If false iExceptions will be thrown from FindImageOverlaps(...) More...

bool	p_threadedCalculate
	True if we want to do calculations in a threaded way. More...

int	p_writtenSoFar
	The index of the last overlap that is done writing (number written-1) More...

int	p_calculatedSoFar
	The index of the last overlap that is done calculating (number calculated-1) More...

SerialNumberList *	p_snlist
	This is used for multi-threaded calls to FindAllOverlaps only; this class never gets ownership of this pointer. More...

QMutex	p_calculatePolygonMutex
	This mutex will be used to have blocking on the write method when multi-threading (instead of busy waiting), it is not intended to prevent calculations and writing from happening simultaneously. More...

QMutex	p_lonLatOverlapsMutex

Detailed Description

This class is used to find the overlaps between all the images in a list of serial numbers.

The overlaps are created in (Lon,Lat) coordinates of geos::geom::MultiPolygons. Each overlap has an associated list of serial numbers which are contained in that overlap.

Author: 2006-01-20 Stuart Sides

History:: 2008-06-18 Christopher Austin - Fixed documentation

History:: 2008-08-18 Steven Lambright - Updated to work with geos3.0.0 instead of geos2. Mostly namespace changes.

History:: 2008-11-24 Steven Lambright - Improved upon error reporting. Added the Errors() method.

History:: 2008-11-25 Steven Koechle - Moved Despike Methods from ImageOverlapSet to PolygonTools.

History:: 2008-12-10 Steven Koechle - Moved MakeMultiPolygon Method from ImageOverlapSet to PolygonTools.

History:: 2008-12-05 Steven Lambright - Checking footprints for validity now, fixed an issue with the intersection operator where an invalid but repairable polygon is produced, and fixed a memory leak.

History:: 2008-12-15 Steven Koechle - Fixed to read new footprint blob naming scheme.

History:: 2009-01-06 Steven Koechle - Removed backwards compatibility for old footprint blob name. Added a throw if footprints are invalid in an image.

History:: 2009-01-07 Steven Lambright & Christopher Austin - Fixed handling of Despike(...) throwing errors on empty polygons.

History:: 2009-01-13 Steven Lambright - Deletes both overlaps if an intersection fails for an unknown reason.

History:: 2009-01-28 Steven Lambright - Fixed memory leaks.

History:: 2009-03-12 Christopher Austin - Added the MULTIPOLYGON to HandleError() as the Keyword "Polygon".

History:: 2009-06-01 Christopher Austin - Changed the basic algorithm to improve results.

History:: 2009-06-01 Steven Lambright - Multi-threaded this object. Split code into smaller methods, now new elements are inserted next instead of appended to the end of the overlap list, and added more error-recovery solutions.

History:: 2010-09-27 Christopher Austin - Added an error when no new overlaps are calculated. (i.e. All overlaps contain only a single Serial Number).

History:: 2011-03-29 Steven Lambright - Added some safety around p_lonLatOverlaps to (hopefully) get rid of a race condition.

History:: 2016-08-26 Kelvin Rodriguez - Added tryLock() just before unlocking mutex in FindAllOverlaps() to avoid undefined behavior. This was done to prevent compile errors on MAC OS 10.11.

History:: 2016-09-14 Marjorie Hahn - Modified FindAllOverlaps()'s check to ensure that at least one overlap has been calculated by adding in the "foundOverlap" boolean. References #2199.

History:: 2016-09-28 Jeannie Backer - Replaced deprecated IStrings with QStrings. Added mutex unlock() calls immediately before exception calls to prevent warning message by latest Qt library 5.7.

History:: 2016-12-09 Marjorie Hahn - Added mutex tryLock() calls before unlocking to prevent undefined behavior caused by unlocking an unlocked mutex.

History:: 2017-05-23 Ian Humphrey - Added a tryLock() to FindAllOverlaps to prevent a segfault from occuring on OSX with certain data. Fixes #4810.

Definition at line 86 of file ImageOverlapSet.h.

Constructor & Destructor Documentation

◆ ImageOverlapSet()

Isis::ImageOverlapSet::ImageOverlapSet	(	bool	continueOnError = `false`,
		bool	useThread = `true`
	)

Create FindImageOverlaps object.

Create an empty FindImageOverlaps object.

Parameters

continueOnError Whether or not this class throws exceptions in addition to logging errors.

See also: automaticRegistration.doc

Definition at line 42 of file ImageOverlapSet.cpp.

◆ ~ImageOverlapSet()

Isis::ImageOverlapSet::~ImageOverlapSet ( )

virtual

Delete this object.

Delete the FindImageOverlaps object. The stored ImageOverlaps will be deleted as well.

Definition at line 58 of file ImageOverlapSet.cpp.

Member Function Documentation

◆ AddSerialNumbers()

void Isis::ImageOverlapSet::AddSerialNumbers	(	ImageOverlap *	to,
		ImageOverlap *	from
	)

protected

Add the serial numbers from the second overlap to the first.

Note: Need to check for existence of a SN before adding it

Parameters

to	The object to receive the new serial numbers
from	The object to copy the serial numbers from

Definition at line 823 of file ImageOverlapSet.cpp.

References Isis::ImageOverlap::Add().

◆ CreateNewOverlap()

ImageOverlap * Isis::ImageOverlapSet::CreateNewOverlap	(	QString	serialNumber,
		geos::geom::MultiPolygon *	latLonPolygon
	)

private

Create an overlap item to hold the overlap poly and its SN.

Parameters

serialNumber	The serial number
latLonPolygon	The object to copy the serial numbers from

Definition at line 838 of file ImageOverlapSet.cpp.

◆ DespikeLonLatOverlaps()

void Isis::ImageOverlapSet::DespikeLonLatOverlaps ( )

private

Despikes all of the overlaps in p_lonLatOverlaps.

Currently (2009-03-19), this fixes spiked multipolygons generated by footprintinit, prior to calculating overlaps.

Definition at line 1091 of file ImageOverlapSet.cpp.

◆ Errors()

const std::vector<PvlGroup>& Isis::ImageOverlapSet::Errors ( )

inline

Return the a list of errors encountered.

Definition at line 122 of file ImageOverlapSet.h.

References p_errorLog.

◆ FindAllOverlaps()

void Isis::ImageOverlapSet::FindAllOverlaps ( SerialNumberList * snlist = NULL )

protected

Find the overlaps between all the existing ImageOverlap Objects.

Parameters

snlist The serialnumber list relating to the overlaps described by the current known ImageOverlap objects or NULL

Definition at line 538 of file ImageOverlapSet.cpp.

References Isis::Progress::AddSteps(), Isis::Progress::CheckStatus(), Isis::Progress::SetMaximumSteps(), Isis::Progress::SetText(), and Isis::SerialNumberList::size().

Referenced by run().

◆ FindImageOverlaps() [1/3]

void Isis::ImageOverlapSet::FindImageOverlaps ( SerialNumberList & sns )

Create polygons of overlap from the images specified in the serial number list.

All polygons created by this class will be deleted when it is destroyed, so callers should not delete the polygons returned by various members.

Parameters

sns	The serial number list to use when finding overlaps

Definition at line 77 of file ImageOverlapSet.cpp.

References Isis::Cube::close(), Isis::SerialNumberList::fileName(), Isis::Cube::open(), Isis::ImagePolygon::Polys(), Isis::Cube::readFootprint(), Isis::SerialNumberList::serialNumber(), and Isis::SerialNumberList::size().

◆ FindImageOverlaps() [2/3]

void Isis::ImageOverlapSet::FindImageOverlaps	(	SerialNumberList &	boundaries,
		QString	outputFile
	)

This method calculates image overlaps given a SerialNumberList and writes it to the filename specified by outputFile.

This method is internally optimized and multi-threaded: the overlaps will NOT persist in memory after this method is called. This object will be reset to its initial state when this is called, and it is invalid to call this method if you have called other methods first.

This method is internally multi-threaded and more efficient than the others for calculating overlaps.

Parameters

boundaries	The files to find overlaps between
outputFile	The output ImageOverlapSet file

Definition at line 172 of file ImageOverlapSet.cpp.

◆ FindImageOverlaps() [3/3]

void Isis::ImageOverlapSet::FindImageOverlaps	(	std::vector< QString >	sns,
		std::vector< geos::geom::MultiPolygon * >	polygons
	)

This is a strict pthread implementation of this class' multi-threading!

void ImageOverlapSet::FindImageOverlaps(SerialNumberList &boundaries, QString outputFile) {

Do a common sense programmer check, this should be empty before we start if (!p_lonLatOverlaps.empty()) { string msg = "FindImageOverlaps(SerialNumberList&,QString) may not be called on an ImageOverlapSet " \ "which already contains overlaps."; throw iException::Message(iException::Programmer, msg, FILEINFO); }

p_writtenSoFar = 0; p_calculatedSoFar = -1;

This will enable using mutexes in the method calls where necessary. p_threadedCalculate = true;

We need to pass a this pointer to the thread AND the serial number list in order to have it calculate properly. Build the void* to pass in. void *data[] = {this, &boundaries};

This is the thread that will be calculating the overlaps. Our current thread will be the one writing to the output file so synchronization at exit is not an issue. pthread_t calculateThread;

Enter the initialization phase: don't try to write until the other thread says initialization is done by unlocking this mutex. pthread_mutex_lock(&initDataMutex);

Create the other thread - it will initialize variables (the ImageOverlap list), unlock the initDataMutex, and proceed to calculate. After each polygon is calculated the calculating mutex will also be unlocked in order to allow I/O if possible. When done calculatedSoFar == p_lonLatOverlaps.size() and the calculating mutex is unlocked. pthread_create(&calculateThread, NULL, FindImageOverlapsThreadStart, &data);

this will let us pass when initialization is done pthread_mutex_lock(&initDataMutex);

Final unlock of the initialization mutex - we locked it to get into this code pthread_mutex_unlock(&initDataMutex);

While our exit condition is not true, call WriteImageOverlaps with the filename. The WriteImageOverlaps call will block if it is waiting on calculations. while(p_calculatedSoFar != (int)p_lonLatOverlaps.size()) { WriteImageOverlaps(outputFile); }

Wait for the calculation thread to actually exit, this has more than likely already occurred. void *result; pthread_join(calculateThread, &result);

re-initialize object to original state p_lonLatOverlaps.clear(); p_writtenSoFar = 0; p_calculatedSoFar = -1; p_threadedCalculate = false; } This is the method that is called when a thread is spawned by FindImageOverlaps(...). It simply calls FindImageOverlaps with a SerialNumberList and exits.

Parameters

data	An array of the form {ImageOverlapSet* instance, SerialNumberList *snlist)

Returns: void* Returns null

void *ImageOverlapSet::FindImageOverlapsThreadStart(void *data) { ImageOverlapSet *instance = (ImageOverlapSet *) ((void**)data)[0]; SerialNumberList *snlist = (SerialNumberList *)((void**)data)[1]; instance->FindImageOverlaps( *snlist ); pthread_exit(NULL); } Create polygons of overlap from the polygons specified. The serial numbers and the polygons are assumed to be parallel arrays. The original polygons passed as arguments are copied, so the ownership of the originals remains with the caller.

Parameters

sns	The serial number list to use when finding overlaps
polygons	The polygons which are to be used when finding overlaps

See also: automaticRegistration.doc

Definition at line 299 of file ImageOverlapSet.cpp.

◆ HandleError() [1/3]

void Isis::ImageOverlapSet::HandleError	(	geos::util::GEOSException *	exc,
		SerialNumberList *	snlist,
		QString	msg = `""`,
		int	overlap1 = `-1`,
		int	overlap2 = `-1`
	)

private

If a problem occurred when searching for image overlaps, this method will handle it.

Parameters

exc	GEOS Exception representing the problem
snlist	Serial number list to get file information from
msg	Error message
overlap1	First problematic overlap
overlap2	Second problematic overlap

Definition at line 960 of file ImageOverlapSet.cpp.

References Isis::SerialNumberList::fileName(), and Isis::PvlKeyword::size().

◆ HandleError() [2/3]

void Isis::ImageOverlapSet::HandleError	(	IException &	e,
		SerialNumberList *	snlist,
		QString	msg = `""`,
		int	overlap1 = `-1`,
		int	overlap2 = `-1`
	)

private

If a problem occurred when searching for image overlaps, this method will handle it.

Parameters

e	Isis Exception representing the problem
snlist	Serial number list to get file information from
msg	Error message
overlap1	First problematic overlap
overlap2	Second problematic overlap

Definition at line 884 of file ImageOverlapSet.cpp.

References Isis::SerialNumberList::fileName(), Isis::PvlKeyword::size(), and Isis::IException::what().

◆ HandleError() [3/3]

void Isis::ImageOverlapSet::HandleError	(	SerialNumberList *	snlist,
		QString	msg,
		int	overlap1 = `-1`,
		int	overlap2 = `-1`
	)

private

If a problem occurred when searching for image overlaps, this method will handle it.

Parameters

snlist	Serial number list to get file information from
msg	Error message
overlap1	First problematic overlap
overlap2	Second problematic overlap

Definition at line 1031 of file ImageOverlapSet.cpp.

References Isis::SerialNumberList::fileName(), and Isis::PvlKeyword::size().

◆ operator[]() [1/2]

const ImageOverlap* Isis::ImageOverlapSet::operator[] ( int index )

inline

Returns the images which overlap at a given loverlap.

Parameters

index The index of the overlap

Returns: const ImageOverlap* The polygon and serial numbers which define the indexed overlap.

Definition at line 115 of file ImageOverlapSet.h.

References p_lonLatOverlaps.

◆ operator[]() [2/2]

std::vector< ImageOverlap * > Isis::ImageOverlapSet::operator[] ( QString serialNumber )

Return the overlaps that have a specific serial number.

Search the existing ImageOverlap objects for all that have the serial numbers associated with them. Note: This could be costly when many overlaps exist.

Parameters

serialNumber The serial number to be search for in all existing ImageOverlaps

Returns: List of related ImageOverlap objects, ownership is retained by ImageOverlapSet*

Definition at line 856 of file ImageOverlapSet.cpp.

◆ ReadImageOverlaps()

void Isis::ImageOverlapSet::ReadImageOverlaps ( const QString & filename )

Create polygons of overlap from the file specified.

Parameters

filename The file to read the image overlaps from

Definition at line 327 of file ImageOverlapSet.cpp.

References Isis::FileName::expanded().

Referenced by Isis::InterestOperator::Operate().

◆ run()

void Isis::ImageOverlapSet::run ( )

inlineprivate

Find overlaps is all the threaded calculate does.

Definition at line 134 of file ImageOverlapSet.h.

References FindAllOverlaps(), and p_snlist.

◆ SetPolygon()

bool Isis::ImageOverlapSet::SetPolygon	(	geos::geom::Geometry *	poly,
		int	position,
		ImageOverlap *	sncopy = `NULL`,
		bool	insert = `false`
	)

private

This method inserts or overwrites a polygon in the overlap list based on parameters.

"poly" is inserted at or after position if insert == true. "poly" is set at position if insert == false. Serial numbers from sncopy will be added to the new/existing ImageOverlap. This method WILL DELETE poly.

This method will attempt to despike poly. This method will return true if the operation was valid - if inserting and the polygon ended up being empty, this will still return true.

Parameters

poly	The geos polygon to insert/set
position	The position to insert/set
sncopy	Serial numbers to copy to the ImageOverlap
insert	True if inserting new overlap

Returns: bool True if operation was valid

Definition at line 377 of file ImageOverlapSet.cpp.

References Isis::ImageOverlap::SetPolygon().

◆ Size()

int Isis::ImageOverlapSet::Size ( )

inline

Returns the total number of latitude and longitude overlaps.

Returns: int The number of lat/lon overlaps

Definition at line 103 of file ImageOverlapSet.h.

References p_lonLatOverlaps.

Referenced by Isis::InterestOperator::FindOverlap().

◆ WriteImageOverlaps()

void Isis::ImageOverlapSet::WriteImageOverlaps ( const QString & filename )

Write polygons of overlap to the file specified.

Parameters

filename The file to write the image overlaps to

Don't wait for an unlock from FindImageOverlaps(...) if we're done calculating.

Definition at line 445 of file ImageOverlapSet.cpp.

References Isis::FileName::expanded().

Member Data Documentation

◆ p_calculatedSoFar

int Isis::ImageOverlapSet::p_calculatedSoFar

private

The index of the last overlap that is done calculating (number calculated-1)

Definition at line 153 of file ImageOverlapSet.h.

◆ p_calculatePolygonMutex

QMutex Isis::ImageOverlapSet::p_calculatePolygonMutex

private

This mutex will be used to have blocking on the write method when multi-threading (instead of busy waiting), it is not intended to prevent calculations and writing from happening simultaneously.

Every time we have new polygons this is unlocked by FindImageOverlaps(...) and re-locked by WriteImageOverlaps(...).

Definition at line 165 of file ImageOverlapSet.h.

◆ p_continueAfterError

bool Isis::ImageOverlapSet::p_continueAfterError

private

If false iExceptions will be thrown from FindImageOverlaps(...)

Definition at line 150 of file ImageOverlapSet.h.

◆ p_errorLog

std::vector<PvlGroup> Isis::ImageOverlapSet::p_errorLog

protected

This is a list of detailed* errors including all known information.

Definition at line 130 of file ImageOverlapSet.h.

Referenced by Errors().

◆ p_lonLatOverlaps

QList<ImageOverlap *> Isis::ImageOverlapSet::p_lonLatOverlaps

private

The list of lat/lon overlaps.

Definition at line 140 of file ImageOverlapSet.h.

Referenced by operator[](), and Size().

◆ p_snlist

SerialNumberList* Isis::ImageOverlapSet::p_snlist

private

This is used for multi-threaded calls to FindAllOverlaps only; this class never gets ownership of this pointer.

Definition at line 156 of file ImageOverlapSet.h.

Referenced by run().

◆ p_threadedCalculate

bool Isis::ImageOverlapSet::p_threadedCalculate

private

True if we want to do calculations in a threaded way.

Definition at line 151 of file ImageOverlapSet.h.

◆ p_writtenSoFar

int Isis::ImageOverlapSet::p_writtenSoFar

private

The index of the last overlap that is done writing (number written-1)

Definition at line 152 of file ImageOverlapSet.h.

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

src/base/objs/ImageOverlapSet/ImageOverlapSet.h
src/base/objs/ImageOverlapSet/ImageOverlapSet.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ImageOverlapSet()

◆ ~ImageOverlapSet()

Member Function Documentation

◆ AddSerialNumbers()

◆ CreateNewOverlap()

◆ DespikeLonLatOverlaps()

◆ Errors()

◆ FindAllOverlaps()

◆ FindImageOverlaps() [1/3]

◆ FindImageOverlaps() [2/3]

◆ FindImageOverlaps() [3/3]

◆ HandleError() [1/3]

◆ HandleError() [2/3]

◆ HandleError() [3/3]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ ReadImageOverlaps()

◆ run()

◆ SetPolygon()

◆ Size()

◆ WriteImageOverlaps()

Member Data Documentation

◆ p_calculatedSoFar

◆ p_calculatePolygonMutex

◆ p_continueAfterError

◆ p_errorLog

◆ p_lonLatOverlaps

◆ p_snlist

◆ p_threadedCalculate

◆ p_writtenSoFar