Isis 3 Programmer Reference
Isis::ImageOverlapSet Class Reference

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:
Inheritance graph
Collaboration diagram for Isis::ImageOverlapSet:
Collaboration graph

Public Member Functions

 ImageOverlapSet (bool continueOnError=false, bool useThread=true)
 Create FindImageOverlaps object.
 
virtual ~ImageOverlapSet ()
 Delete this object.
 
void FindImageOverlaps (SerialNumberList &boundaries)
 Create polygons of overlap from the images specified in the serial number list.
 
void FindImageOverlaps (std::vector< QString > sns, std::vector< geos::geom::MultiPolygon * > polygons)
 This is a strict pthread implementation of this class' multi-threading!
 
void FindImageOverlaps (SerialNumberList &boundaries, QString outputFile)
 This method calculates image overlaps given a SerialNumberList and writes it to the filename specified by outputFile.
 
void ReadImageOverlaps (const QString &filename)
 Create polygons of overlap from the file specified.
 
void WriteImageOverlaps (const QString &filename)
 Write polygons of overlap to the file specified.
 
int Size ()
 Returns the total number of latitude and longitude overlaps.
 
const ImageOverlapoperator[] (int index)
 Returns the images which overlap at a given loverlap.
 
std::vector< ImageOverlap * > operator[] (QString serialNumber)
 Return the overlaps that have a specific serial number.
 
const std::vector< PvlGroup > & Errors ()
 Return the a list of errors encountered.
 

Protected Member Functions

void FindAllOverlaps (SerialNumberList *snlist=NULL)
 Find the overlaps between all the existing ImageOverlap Objects.
 
void AddSerialNumbers (ImageOverlap *to, ImageOverlap *from)
 Add the serial numbers from the second overlap to the first.
 

Protected Attributes

std::vector< PvlGroupp_errorLog
 This is a list of detailed* errors including all known information.
 

Private Member Functions

void run ()
 Find overlaps is all the threaded calculate does.
 
void DespikeLonLatOverlaps ()
 Despikes all of the overlaps in p_lonLatOverlaps.
 
ImageOverlapCreateNewOverlap (QString serialNumber, geos::geom::MultiPolygon *lonLatPolygon)
 Create an overlap item to hold the overlap poly and its SN.
 
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.
 
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.
 
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.
 
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.
 

Private Attributes

QList< ImageOverlap * > p_lonLatOverlaps
 The list of lat/lon overlaps.
 
bool p_continueAfterError
 If false iExceptions will be thrown from FindImageOverlaps(...)
 
bool p_threadedCalculate
 True if we want to do calculations in a threaded way.
 
int p_writtenSoFar
 The index of the last overlap that is done writing (number written-1)
 
int p_calculatedSoFar
 The index of the last overlap that is done calculating (number calculated-1)
 
SerialNumberListp_snlist
 This is used for multi-threaded calls to FindAllOverlaps only; this class never gets ownership of this pointer.
 
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.
 
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

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

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

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

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

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.

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

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

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

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

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

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

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

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.

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

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

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.

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.

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.

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

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
continueOnErrorWhether or not this class throws exceptions in addition to logging errors.
See also
automaticRegistration.doc

Definition at line 44 of file ImageOverlapSet.cpp.

References p_calculatedSoFar, p_continueAfterError, p_snlist, p_threadedCalculate, and p_writtenSoFar.

◆ ~ImageOverlapSet()

Isis::ImageOverlapSet::~ImageOverlapSet ( )
virtual

Delete this object.

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

Definition at line 60 of file ImageOverlapSet.cpp.

References p_lonLatOverlaps, and Size().

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
toThe object to receive the new serial numbers
fromThe object to copy the serial numbers from

Definition at line 825 of file ImageOverlapSet.cpp.

Referenced by FindAllOverlaps(), and SetPolygon().

◆ 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
serialNumberThe serial number
latLonPolygonThe object to copy the serial numbers from

Definition at line 840 of file ImageOverlapSet.cpp.

Referenced by FindImageOverlaps(), and FindImageOverlaps().

◆ 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 1093 of file ImageOverlapSet.cpp.

References Isis::PolygonTools::Despike(), p_lonLatOverlaps, and Size().

Referenced by FindImageOverlaps(), and FindImageOverlaps().

◆ 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
snlistThe serialnumber list relating to the overlaps described by the current known ImageOverlap objects or NULL

Definition at line 540 of file ImageOverlapSet.cpp.

References AddSerialNumbers(), Isis::PolygonTools::Despike(), Isis::PolygonTools::Difference(), HandleError(), Isis::PolygonTools::Intersect(), Isis::PolygonTools::MakeMultiPolygon(), p_calculatedSoFar, p_calculatePolygonMutex, p_lonLatOverlaps, p_threadedCalculate, SetPolygon(), and Isis::Progress::SetText().

Referenced by FindImageOverlaps(), FindImageOverlaps(), and 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
snsThe serial number list to use when finding overlaps

Definition at line 79 of file ImageOverlapSet.cpp.

References Isis::Cube::close(), CreateNewOverlap(), Isis::PolygonTools::Despike(), DespikeLonLatOverlaps(), FindAllOverlaps(), HandleError(), Isis::PolygonTools::MakeMultiPolygon(), Isis::Cube::open(), p_lonLatOverlaps, p_threadedCalculate, Isis::IException::Programmer, and Isis::Cube::readFootprint().

Referenced by FindImageOverlaps().

◆ 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
boundariesThe files to find overlaps between
outputFileThe output ImageOverlapSet file

Definition at line 174 of file ImageOverlapSet.cpp.

References FindImageOverlaps(), p_calculatedSoFar, p_lonLatOverlaps, p_snlist, p_threadedCalculate, p_writtenSoFar, Isis::IException::Programmer, and WriteImageOverlaps().

◆ 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
dataAn 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
snsThe serial number list to use when finding overlaps
polygonsThe polygons which are to be used when finding overlaps
See also
automaticRegistration.doc

Definition at line 301 of file ImageOverlapSet.cpp.

References CreateNewOverlap(), DespikeLonLatOverlaps(), FindAllOverlaps(), p_lonLatOverlaps, and Isis::IException::Programmer.

◆ 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
excGEOS Exception representing the problem
snlistSerial number list to get file information from
msgError message
overlap1First problematic overlap
overlap2Second problematic overlap

Definition at line 962 of file ImageOverlapSet.cpp.

References p_continueAfterError, p_errorLog, p_lonLatOverlaps, Isis::IException::Programmer, Size(), 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
eIsis Exception representing the problem
snlistSerial number list to get file information from
msgError message
overlap1First problematic overlap
overlap2Second problematic overlap

Definition at line 886 of file ImageOverlapSet.cpp.

References p_continueAfterError, p_errorLog, p_lonLatOverlaps, Size(), and Isis::PvlKeyword::size().

Referenced by FindAllOverlaps(), and FindImageOverlaps().

◆ 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
snlistSerial number list to get file information from
msgError message
overlap1First problematic overlap
overlap2Second problematic overlap

Definition at line 1033 of file ImageOverlapSet.cpp.

References p_continueAfterError, p_errorLog, p_lonLatOverlaps, Isis::IException::Programmer, Size(), 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
indexThe 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
serialNumberThe serial number to be search for in all existing ImageOverlaps
Returns
List of related ImageOverlap objects, ownership is retained by ImageOverlapSet*

Definition at line 858 of file ImageOverlapSet.cpp.

References p_lonLatOverlaps.

◆ ReadImageOverlaps()

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

Create polygons of overlap from the file specified.

Parameters
filenameThe file to read the image overlaps from

Definition at line 329 of file ImageOverlapSet.cpp.

References Isis::FileName::expanded(), p_lonLatOverlaps, and Isis::IException::Unknown.

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
polyThe geos polygon to insert/set
positionThe position to insert/set
sncopySerial numbers to copy to the ImageOverlap
insertTrue if inserting new overlap
Returns
bool True if operation was valid

Definition at line 379 of file ImageOverlapSet.cpp.

References AddSerialNumbers(), Isis::PolygonTools::Despike(), Isis::PolygonTools::MakeMultiPolygon(), and p_lonLatOverlaps.

Referenced by FindAllOverlaps().

◆ 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 DespikeLonLatOverlaps(), Isis::InterestOperator::FindOverlap(), HandleError(), HandleError(), HandleError(), and ~ImageOverlapSet().

◆ WriteImageOverlaps()

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

Write polygons of overlap to the file specified.

Parameters
filenameThe file to write the image overlaps to

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

Definition at line 447 of file ImageOverlapSet.cpp.

References Isis::FileName::expanded(), Isis::IException::Io, p_calculatedSoFar, p_calculatePolygonMutex, p_lonLatOverlaps, p_threadedCalculate, p_writtenSoFar, and Isis::IException::User.

Referenced by FindImageOverlaps().

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.

Referenced by FindAllOverlaps(), FindImageOverlaps(), ImageOverlapSet(), and WriteImageOverlaps().

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

Referenced by FindAllOverlaps(), and WriteImageOverlaps().

◆ p_continueAfterError

bool Isis::ImageOverlapSet::p_continueAfterError
private

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

Definition at line 150 of file ImageOverlapSet.h.

Referenced by HandleError(), HandleError(), HandleError(), and ImageOverlapSet().

◆ 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(), HandleError(), HandleError(), and HandleError().

◆ p_lonLatOverlaps

◆ p_lonLatOverlapsMutex

QMutex Isis::ImageOverlapSet::p_lonLatOverlapsMutex
private

Definition at line 166 of file ImageOverlapSet.h.

◆ 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 FindImageOverlaps(), ImageOverlapSet(), and 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.

Referenced by FindAllOverlaps(), FindImageOverlaps(), FindImageOverlaps(), ImageOverlapSet(), and WriteImageOverlaps().

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

Referenced by FindImageOverlaps(), ImageOverlapSet(), and WriteImageOverlaps().


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