USGS Astrogeology Isis API

This class creates polygons defining an image boundary, reads the polygon from a cube blob, and writes a polygon to a cube blob. The GEOS (Geometry Engine Open Source) package is used to create and manipulate the polygons. See http://geos.refractions.net for information about this package.

Definition at line 149 of file ImagePolygon.h.


Public Member Functions
	ImagePolygon ()
	Constructs a Polygon object, setting the polygon name.
	~ImagePolygon ()
	Destroys the Polygon object.
void	Create (Cube &cube, int sampinc=1, int lineinc=1, int ss=1, int sl=1, int ns=0, int nl=0, int band=1)
	Create a Polygon from given cube.
void	Emission (double emission)
	Set the maximum emission angle ( light refleted to camera ).
void	Incidence (double incidence)
	Set the maximum incidence angle ( light contacting the planet ).
void	EllipsoidLimb (bool ellip)
	If a limb is detected, use un ellipsoid shape model if true.
void	SubpixelAccuracy (int div)
	The subpixel accuracy to use.
geos::geom::MultiPolygon *	Polys ()
	Return a geos Multipolygon.
void	Read (const std::string &file)
	This reads Pvl values from a specified file.
virtual void	Read (Isis::Pvl &pvl, std::fstream &is)
void	Write (const std::string &file)
	Write the blob data out to a file.
void	Write (Isis::Pvl &pvl, std::fstream &istm, const std::string &detachedFilename="")
	Write the blob data out to a Pvl object.
std::string	Type () const
std::string	Name () const
PvlObject &	Label ()
Protected Member Functions
void	ReadData (std::fstream &is)
	Reads Multipolygon from cube blob.
void	WriteInit ()
	Initializes for writing polygon to cube blob.
void	WriteData (std::fstream &os)
	Writes polygon to cube blob.
void	Find (Isis::Pvl &pvl)
virtual void	ReadInit ()
Protected Attributes
Isis::PvlObject	p_blobPvl
	Pvl Blob object.
std::string	p_blobName
	Name of the Blob object.
char *	p_buffer
	Buffer blob data is stored in.
BigInt	p_startByte
	Byte blob data starts at in buffer.
int	p_nbytes
	Size of blob data (in bytes).
std::string	p_type
	Type of data stored in the buffer.
std::string	p_detached
	Used for reading detached blobs.
std::string	p_labelFile
	The file containing the labels.
Private Member Functions
bool	SetImage (const double sample, const double line)
	Sets the sample/line values of the cube to get lat/lon values.
geos::geom::Coordinate	FindFirstPoint ()
	Finds the first point that projects in an image.
void	WalkPoly ()
	Walks the image finding its lon lat polygon and stores it to p_pts.
geos::geom::Coordinate	FindNextPoint (geos::geom::Coordinate *currentPoint, geos::geom::Coordinate lastPoint, int recursionDepth=0)
	Finds the next point on the image using a left hand rule walking algorithm.
double	DistanceSquared (const geos::geom::Coordinate p1, const geos::geom::Coordinate p2)
	Calculates the distance squared between two coordinates.
void	MoveBackInsideImage (double &sample, double &line, double sinc, double linc)
	This method ensures sample/line after sinc/linc have been applied is inside the image.
bool	InsideImage (double sample, double line)
	This returns true if sample/line are inside the cube.
void	Fix360Poly ()
	If the cube crosses the 0/360 boundary and does not include a pole, the polygon is separated into multiple polygons, usually one on each side of the boundary.
void	FixPolePoly (std::vector< geos::geom::Coordinate > *crossingPoints)
	If the cube crosses the 0/360 boundary and contains a pole, Some points are added to allow the polygon to unwrap properly.
bool	IsLimb ()
	Returns True when the input image is a limb image.
geos::geom::Coordinate	FindBestPoint (geos::geom::Coordinate *currentPoint, geos::geom::Coordinate newPoint, geos::geom::Coordinate lastPoint)
	While walking the image in sample/line space, this function finds the best valid point between the first valid point found and the last point which failed its validity test using a linear search.
geos::geom::Coordinate	FixCornerSkip (geos::geom::Coordinate *currentPoint, geos::geom::Coordinate newPoint)
	Looks at the next possible point relative to the lasts and attempts to adjust the point outward to grab valid corner data.
void	FindSubpixel (std::vector< geos::geom::Coordinate > *points)
	Takes p_polygons in sample/line space and finds its subpixel accuracy.
Private Attributes
Cube *	p_cube
	The cube provided.
bool	p_isProjected
	True when the provided cube is projected.
Brick *	p_brick
	Used to check for valid DNs.
geos::geom::CoordinateSequence *	p_pts
	The sequence of coordinates that compose the boundry of the image.
geos::geom::MultiPolygon *	p_polygons
	The multipolygon of the image.
std::string	p_polyStr
	The string representation of the polygon.
UniversalGroundMap *	p_gMap
	The cube's ground map.
int	p_cubeStartSamp
	The the sample of the first valid point in the cube.
int	p_cubeStartLine
	The the line of the first valid point in the cube.
int	p_cubeSamps
	The number of samples in the cube.
int	p_cubeLines
	The number of lines in the cube.
int	p_sampinc
	The increment for walking along the polygon in the sample direction.
int	p_lineinc
	The increment for walking along the polygon in the line direcction.
double	p_emission
	The maximum emission angle to consider valid.
double	p_incidence
	The maximum incidence angle to consider valid.
bool	p_ellipsoid
	Uses an ellipsoid if a limb is detected.
int	p_subpixelAccuracy
	The subpixel accuracy to use.

Constructor & Destructor Documentation

Isis::ImagePolygon::ImagePolygon ( )

Constructs a Polygon object, setting the polygon name.

Definition at line 50 of file ImagePolygon.cpp.

References p_cubeStartLine, p_cubeStartSamp, p_ellipsoid, p_emission, p_incidence, p_polygons, and p_subpixelAccuracy.

Isis::ImagePolygon::~ImagePolygon ( )

Destroys the Polygon object.

Definition at line 62 of file ImagePolygon.cpp.

References p_polygons.

Member Function Documentation

void Isis::ImagePolygon::Create	(	Cube &	cube,
		int	sampinc = `1`,
		int	lineinc = `1`,
		int	ss = `1`,
		int	sl = `1`,
		int	ns = `0`,
		int	nl = `0`,
		int	band = `1`
	)

Create a Polygon from given cube.

Parameters:

`[in]`	cube	(Cube &) Cube used to create polygon
`[in]`	sampinc	(Default=1) (in) Pixel increment to define the granularity of the resulting polygon in the sample direction
`[in]`	lineinc	(Default=1) (in) Pixel increment to define the granularity of the resulting polygon in the line direction
`[in]`	ss	(Default=1) (in) Starting sample number
`[in]`	sl	(Default=1) (in) Starting Line number
`[in]`	ns	(Default=0) (in) Number of samples used to create the polygon. Default of 0 will cause ns to be set to the number of samples in the cube.
`[in]`	nl	(Default=0) (in) Number of lines used to create the polygon. Default of 0 will cause nl to be set to the number of lines in the cube.
`[in]`	band	(Default=1) (in) Image band number

History:: 2008-04-28 Tracie Sucharski, When calculating p_pixInc, set to 1 if values calculated is 0.

History:: 2008-12-30 Tracie Sucharski - If ground map returns pole make sure it is actually on the image.

History:: 2009-05-28 Stuart Sides - Added the quality argument.

Definition at line 93 of file ImagePolygon.cpp.

References _FILEINFO_, Isis::Camera::BasicMapping(), cam, Isis::UniversalGroundMap::Camera(), Isis::Cube::Camera(), Isis::iException::Clear(), cube, e, Isis::Cube::Filename(), Fix360Poly(), Isis::Camera::HasProjection(), Isis::Sensor::IgnoreElevationModel(), IsLimb(), Isis::Cube::Lines(), Isis::iException::Message(), p_brick, p_cube, p_cubeLines, p_cubeSamps, p_cubeStartLine, p_cubeStartSamp, p_ellipsoid, p_gMap, p_isProjected, p_lineinc, p_pts, p_sampinc, Isis::Cube::PixelType(), proj, Isis::Cube::Projection(), Isis::Cube::Samples(), Isis::UniversalGroundMap::SetBand(), and WalkPoly().

double Isis::ImagePolygon::DistanceSquared	(	const geos::geom::Coordinate *	p1,
		const geos::geom::Coordinate *	p2
	)			`[private]`

Calculates the distance squared between two coordinates.

Parameters:

	p1	The first Coordinate for the calculation
	p2	The second Coordinate for the calculation

return The distance squared between the Coordinates

Definition at line 1115 of file ImagePolygon.cpp.

Referenced by FixPolePoly(), and WalkPoly().

void Isis::ImagePolygon::EllipsoidLimb ( bool ellip ) [inline]

If a limb is detected, use un ellipsoid shape model if true.

If false, use the default (spiceinit defined) shape model.

Parameters:

ellip

True to use ellipsoid on limb images

Definition at line 177 of file ImagePolygon.h.

References p_ellipsoid.

void Isis::ImagePolygon::Emission ( double emission ) [inline]

Set the maximum emission angle ( light refleted to camera ).

Parameters:

emission

The maximum valid emission angle

Definition at line 163 of file ImagePolygon.h.

References p_emission.

geos::geom::Coordinate Isis::ImagePolygon::FindBestPoint	(	geos::geom::Coordinate *	currentPoint,
		geos::geom::Coordinate	newPoint,
		geos::geom::Coordinate	lastPoint
	)			`[private]`

While walking the image in sample/line space, this function finds the best valid point between the first valid point found and the last point which failed its validity test using a linear search.

Parameters:

	currentPoint	The last point added to the polygon
	newPoint	The first valid point found for the next step.
	lastPoint	The last point that was found to be invalid which checking for the next step.

Returns:: geos::geom::Coordinate The valid point found via searching between the provided points.

Definition at line 1149 of file ImagePolygon.cpp.

References FixCornerSkip(), p_cubeLines, p_cubeSamps, p_cubeStartLine, p_cubeStartSamp, p_lineinc, p_sampinc, SetImage(), x, and y.

Referenced by FindNextPoint().

geos::geom::Coordinate Isis::ImagePolygon::FindFirstPoint ( ) [private]

Finds the first point that projects in an image.

Returns:: geos::geom::Coordinate A starting point that is on the edge of the polygon.

Definition at line 407 of file ImagePolygon.cpp.

References _FILEINFO_, line, Isis::iException::Message(), p_cubeLines, p_cubeSamps, p_cubeStartLine, p_cubeStartSamp, sample, and SetImage().

Referenced by WalkPoly().

geos::geom::Coordinate Isis::ImagePolygon::FindNextPoint	(	geos::geom::Coordinate *	currentPoint,
		geos::geom::Coordinate	lastPoint,
		int	recursionDepth = `0`
	)			`[private]`

Finds the next point on the image using a left hand rule walking algorithm.

To initiate the walk pass it the same point for both currentPoint and lastPoint.

Parameters:

`[in]`	currentPoint	(geos::geom::Coordinate *currentPoint) This is the currentPoint in the path. You are looking for its successor.
`[in]`	lastPoint	(geos::geom::Coordinate lastPoint) This is the lastPoint in the path, it allows the algorithm to calculate direction.
`[in]`	recursionDepth	(int) This optional parameter keeps track of how far it has walked around a point. By default it is zero.

throws Isis::iException::Programmer - Error walking the file

Definition at line 196 of file ImagePolygon.cpp.

References _FILEINFO_, FindBestPoint(), InsideImage(), line, Isis::iException::Message(), MoveBackInsideImage(), p_lineinc, p_sampinc, SetImage(), x, and y.

Referenced by WalkPoly().

void Isis::ImagePolygon::FindSubpixel ( std::vector< geos::geom::Coordinate > * points ) [private]

Takes p_polygons in sample/line space and finds its subpixel accuracy.

This algorithm depends on a left-hand-turn algorithm and assumes that the vector of Coordinates provided is not empty.

Parameters:

points

The vector of Coordinate to set to subpixel accuracy

Definition at line 1266 of file ImagePolygon.cpp.

References InsideImage(), p_lineinc, p_sampinc, p_subpixelAccuracy, SetImage(), x, and y.

Referenced by WalkPoly().

void Isis::ImagePolygon::Fix360Poly ( ) [private]

If the cube crosses the 0/360 boundary and does not include a pole, the polygon is separated into multiple polygons, usually one on each side of the boundary.

These polygons are put into a geos Multipolygon. If the cube does not cross the 0/360 boundary then the Multipolygon will be a single Polygon.

Definition at line 853 of file ImagePolygon.cpp.

References _FILEINFO_, dist, e, Isis::globalFactory, Isis::PolygonTools::Intersect(), latitude, longitude, Isis::PolygonTools::MakeMultiPolygon(), Isis::iException::Message(), p_polygons, and p_pts.

Referenced by Create().

geos::geom::Coordinate Isis::ImagePolygon::FixCornerSkip	(	geos::geom::Coordinate *	currentPoint,
		geos::geom::Coordinate	newPoint
	)			`[private]`

Looks at the next possible point relative to the lasts and attempts to adjust the point outward to grab valid corner data.

Parameters:

	currentPoint	The last valid point added to the polygon
	newPoint	The new point to be added to the polygon

Returns:: geos::geom::Coordinate The new point modified for a better result

Definition at line 1210 of file ImagePolygon.cpp.

References p_cubeLines, p_cubeSamps, p_lineinc, p_sampinc, and SetImage().

Referenced by FindBestPoint().

void Isis::ImagePolygon::FixPolePoly ( std::vector< geos::geom::Coordinate > * crossingPoints ) [private]

If the cube crosses the 0/360 boundary and contains a pole, Some points are added to allow the polygon to unwrap properly.

Throws an error if both poles are in the image. Returns if there is no pole in the image.

Parameters:

crossingPoints

The coordinate sequence that crosses the 0/360 boundry

Definition at line 607 of file ImagePolygon.cpp.

References _FILEINFO_, Isis::UniversalGroundMap::Camera(), dist, DistanceSquared(), Isis::Sensor::EmissionAngle(), Isis::Sensor::IncidenceAngle(), Isis::iException::Message(), p_emission, p_gMap, p_incidence, p_pts, and Isis::UniversalGroundMap::SetUniversalGround().

Referenced by WalkPoly().

void Isis::ImagePolygon::Incidence ( double incidence ) [inline]

Set the maximum incidence angle ( light contacting the planet ).

Parameters:

incidence

The maximum valid incidence angle

Definition at line 169 of file ImagePolygon.h.

References p_incidence.

bool Isis::ImagePolygon::InsideImage	(	double	sample,
		double	line
	)			`[private]`

This returns true if sample/line are inside the cube.

Parameters:

	sample
	line

Returns:: bool

Definition at line 393 of file ImagePolygon.cpp.

References p_cubeLines, p_cubeSamps, p_cubeStartLine, and p_cubeStartSamp.

Referenced by FindNextPoint(), and FindSubpixel().

bool Isis::ImagePolygon::IsLimb ( ) [private]

Returns True when the input image is a limb image.

Returns:: bool True if any of the 4 corners of the input image cannot be set

Definition at line 1125 of file ImagePolygon.cpp.

References p_cubeLines, p_cubeSamps, and SetImage().

Referenced by Create().

void Isis::ImagePolygon::MoveBackInsideImage	(	double &	sample,
		double &	line,
		double	sinc,
		double	linc
	)			`[private]`

This method ensures sample/line after sinc/linc have been applied is inside the image.

If not, it snaps to the edge of the image - given we didn't start at the edge.

Parameters:

	sample	Sample after sinc applied
	line	Line after linc applied
	sinc	Sample increment (we can back up at most this much)
	linc	Line increment (we can back up at most this much)

Definition at line 325 of file ImagePolygon.cpp.

References p_cubeLines, p_cubeSamps, p_cubeStartLine, and p_cubeStartSamp.

Referenced by FindNextPoint().

geos::geom::MultiPolygon* Isis::ImagePolygon::Polys ( ) [inline]

Return a geos Multipolygon.

Definition at line 191 of file ImagePolygon.h.

References p_polygons.

void Isis::Blob::Read ( const std::string & file ) [inherited]

This reads Pvl values from a specified file.

Parameters:

file

The filename to read from.

Exceptions:

	Isis::iException::Io	- Unable to open file
	Isis::iException::Pvl	- Invalid label format

Definition at line 141 of file Blob.cpp.

References _FILEINFO_, e, Isis::Message::FileOpen(), in, Isis::iException::Message(), Isis::Blob::p_blobName, Isis::Blob::p_type, and pvl().

Referenced by Isis::Blob::Blob(), Isis::History::History(), Isis::OriginalLabel::OriginalLabel(), Isis::OriginalLabel::Read(), Isis::History::Read(), Isis::Cube::Read(), and Isis::Table::Table().

void Isis::ImagePolygon::ReadData ( std::fstream & is ) [protected, virtual]

Reads Multipolygon from cube blob.

Parameters:

[in] is (std::fstream) Input stream to read from

throws Isis::iException::Io - Error reading data from stream

Reimplemented from Isis::Blob.

Definition at line 1052 of file ImagePolygon.cpp.

References _FILEINFO_, Isis::globalFactory, Isis::iException::Message(), Isis::Blob::p_blobName, Isis::Blob::p_nbytes, p_polygons, p_polyStr, Isis::Blob::p_startByte, and Isis::Blob::p_type.

bool Isis::ImagePolygon::SetImage	(	const double	sample,
		const double	line
	)			`[private]`

Sets the sample/line values of the cube to get lat/lon values.

This method checks whether the image pixel is Null for level 2 images and if so, it is considered an invalid pixel.

Parameters:

`[in]`	sample	(const double) Sample coordinate of the cube
`[in]`	line	(const double) Line coordinate of the cube

Returns:: bool Returns true if the image was set successfully and false if it was not or if pixel of level 2 images is NULL.

This check has been removed because it causes push frame cameras to fail inbetween the framelets, resulting in only the first framlet to be walked, leaving out the rest of the image.

This can cause autoseed/jigsaw issues, since they require conversion from lat/lon to samp/line

Definition at line 780 of file ImagePolygon.cpp.

References Isis::UniversalGroundMap::Camera(), Isis::Sensor::EmissionAngle(), Isis::Sensor::IncidenceAngle(), Isis::IsNullPixel(), p_brick, p_cube, p_emission, p_gMap, p_incidence, p_isProjected, Isis::Cube::Read(), Isis::Brick::SetBasePosition(), and Isis::UniversalGroundMap::SetImage().

Referenced by FindBestPoint(), FindFirstPoint(), FindNextPoint(), FindSubpixel(), FixCornerSkip(), IsLimb(), and WalkPoly().

void Isis::ImagePolygon::SubpixelAccuracy ( int div ) [inline]

The subpixel accuracy to use.

This accuracy is the number of binary steps to take to find the subpixel accuracy. A higher number provided gives more accurate results at the cost of runtime.

ImagePolygon's constructor sets a default value of 50

Parameters:

div

The subpixel accuracy to use

Definition at line 188 of file ImagePolygon.h.

References p_subpixelAccuracy.

void Isis::ImagePolygon::WalkPoly ( ) [private]

Walks the image finding its lon lat polygon and stores it to p_pts.

WARNING: Very large pixel increments for cubes that have cameras/projections with no data at any of the 4 corners can still fail in this algorithm.

Definition at line 430 of file ImagePolygon.cpp.

References _FILEINFO_, DistanceSquared(), FindFirstPoint(), FindNextPoint(), FindSubpixel(), FixPolePoly(), Isis::globalFactory, Isis::iException::Message(), p_cubeLines, p_cubeSamps, p_gMap, p_lineinc, p_pts, p_sampinc, SetImage(), Isis::UniversalGroundMap::UniversalLatitude(), Isis::UniversalGroundMap::UniversalLongitude(), x, and y.