Isis 3 Programmer Reference
Isis::Projection Class Referenceabstract

Base class for Map Projections. More...

#include <Projection.h>

Inheritance diagram for Isis::Projection:
Inheritance graph
Collaboration diagram for Isis::Projection:
Collaboration graph

Public Types

enum  ProjectionType { Triaxial, RingPlane }
 This enum defines the subclasses of Projection supported in Isis. More...
 

Public Member Functions

 Projection (Pvl &label)
 Constructs an empty Projection object. More...
 
virtual ~Projection ()
 Destroys the Projection object. More...
 
virtual bool operator== (const Projection &proj)
 This method determines whether two map projection objects are equal by comparing the resolution, and projection name. More...
 
bool operator!= (const Projection &proj)
 This method determines whether two map projection objects are not equal. More...
 
void setProjectionType (const ProjectionType ptype)
 Sets the projection subclass type. More...
 
ProjectionType projectionType () const
 Returns an enum value for the projection type. More...
 
bool IsSky () const
 Returns true if projection is sky and false if it is land. More...
 
virtual QString Name () const =0
 This method returns the name of the map projection. More...
 
virtual double LocalRadius () const =0
 
virtual QString Version () const =0
 This method returns the Version of the map projection. More...
 
virtual bool IsEquatorialCylindrical ()
 This method returns true if the projection is equatorial cylindrical. More...
 
virtual bool HasGroundRange () const
 This indicates if the longitude direction type is positive west (as opposed to postive east). More...
 
double Rotation () const
 Returns the value of the Rotation keyword from the mapping group. More...
 
void SetWorldMapper (WorldMapper *mapper)
 If desired the programmer can use this method to set a world mapper to be used in the SetWorld, WorldX, and WorldY methods. More...
 
virtual bool SetGround (const double lat, const double lon)=0
 
virtual bool SetCoordinate (const double x, const double y)=0
 
bool IsGood () const
 This indicates if the last invocation of SetGround, SetCoordinate, SetUniversalGround, or SetWorld was with successful or not. More...
 
double XCoord () const
 This returns the projection X provided SetGround, SetCoordinate, SetUniversalGround, or SetWorld returned with success. More...
 
double YCoord () const
 This returns the projection Y provided SetGround, SetCoordinate, SetUniversalGround, or SetWorld returned with success. More...
 
virtual bool SetUniversalGround (const double coord1, const double coord2)
 This method is used to set the lat/lon or radius/azimuth (i.e. More...
 
virtual bool SetUnboundUniversalGround (const double coord1, const double coord2)
 This method is used to set the lat/lon or radius/azimuth (i.e. More...
 
virtual bool SetWorld (const double x, const double y)
 This method is used to set a world coordinate. More...
 
virtual double WorldX () const
 This returns the world X coordinate provided SetGround, SetCoordinate, SetUniversalGround, or SetWorld returned with success. More...
 
virtual double WorldY () const
 This returns the world Y coordinate provided SetGround, SetCoordinate, SetUniversalGround, or SetWorld returned with success. More...
 
double ToWorldX (const double projectionX) const
 This method converts a projection x value to a world x value. More...
 
double ToWorldY (const double projectionY) const
 This method converts a projection y value to a world y value. More...
 
double ToProjectionX (const double worldX) const
 This method converts a world x value to a projection x value. More...
 
double ToProjectionY (const double worldY) const
 This method converts a world y value to a projection y value. More...
 
double Resolution () const
 This method returns the resolution for mapping world coordinates into projection coordinates. More...
 
virtual double Scale () const =0
 
virtual bool XYRange (double &minX, double &maxX, double &minY, double &maxY)=0
 
void SetUpperLeftCorner (const Displacement &x, const Displacement &y)
 This method searches for extreme (min/max/discontinuity) coordinate values along the constBorder line between minBorder and maxBorder (that is, across latitudes/longitudes). More...
 
virtual PvlGroup Mapping ()=0
 

Static Public Member Functions

static double ToHours (double angle)
 Converts the given angle (in degrees) to hours by using the ratio 15 degrees per hour. More...
 
static QString ToDMS (double angle)
 Converts the given angle (in degrees) to degrees, minutes, seconds. More...
 
static QString ToHMS (double angle)
 Converts the given angle (in degrees) to hours, minutes, seconds. More...
 

Protected Member Functions

virtual void XYRangeCheck (const double latitude, const double longitude)=0
 
void SetXY (double x, double y)
 This protected method is a helper for derived classes. More...
 
void SetComputedXY (double x, double y)
 This protected method is a helper for derived classes. More...
 
double GetX () const
 Calculates the unrotated form of current x value. More...
 
double GetY () const
 Calculates the unrotated form of the current y value. More...
 
double PixelResolution () const
 Returns the pixel resolution value from the PVL mapping group in meters/pixel. More...
 

Protected Attributes

WorldMapperm_mapper
 This points to a mapper passed into the SetWorldMapper method. More...
 
bool m_good
 Indicates if the contents of m_x, m_y, m_latitude, and m_longitude are valid. More...
 
bool m_sky
 Indicates whether projection is sky or land. More...
 
bool m_groundRangeGood
 Indicates if the ground range (min/max lat/lons) were read from the labels. More...
 
double m_minimumX
 The data elements m_minimumX, m_minimumY, m_maximumX, and m_maximumY are convience data elements when you write the XYRange virtual function. More...
 
double m_maximumX
 See minimumX description. More...
 
double m_minimumY
 See minimumX description. More...
 
double m_maximumY
 See minimumX description. More...
 
PvlGroup m_mappingGrp
 Mapping group that created this projection. More...
 

Private Attributes

ProjectionType m_projectionType
 
double m_rotation
 Rotation of map (usually zero) More...
 
double m_x
 This contains the rotated X coordinate for a specific projection at theposition indicated by m_latitude/m_longitude. More...
 
double m_y
 This contains the rotated Y coordinate for a specific projection at the position indicated by m_latitude/m_longitude. More...
 
double m_pixelResolution
 Pixel resolution value from the PVL mapping group, in meters/pixel. More...
 

Detailed Description

Base class for Map Projections.

This is a virtual base class for map projections. It must be used to create specific map projection classes such as Sinusoidal, Mercator, etc. The foundation of this class is the ability to convert ground coordinates (latitude and longitude) into projection coordinates (x and y) and vice versa. Options exist to allow conversion to and from programmer specified world coordinates. The world coordinates can be cube pixels, paper units in millimeters, or any other unit the program may need. Generally, you should never directly instantiate this class.

Here is an example of how to use Projection

Pvl lab;
lab.Read("projection.map");

If you would like to see Projection being used in implementation, see mappos.cpp

Author
2003-01-29 Jeff Anderson
History:
2003-01-30 Jeff Anderson - Add the SetWorldMapper() method and removed setting the mapper from the constructor
History:
2003-05-16 Stuart Sides - Modified schema from astrogeology... isis.astrogeology...
History:
2003-05-30 Jeff Anderson - Updated unit test to fix error for optimization
History:
2003-08-25 Jeff Anderson - Added LatitudeTypeString(), LongitudeDirectionString(), and LongitudeDomainString() methods
History:
2003-09-26 Jeff Anderson - Added ToWorldX(), ToWorldY(), ToProjectionX(), ToProjectionY(), and Resolution() methods
History:
2003-09-26 Jeff Anderson - Added virtual Name, operator==, and operator!= methods
History:
2003-09-26 Jeff Anderson - Remove virtual from operator!=
History:
2003-10-14 Jeff Anderson - Added Scale() and TrueScaleLatitude() methods
History:
2003-11-04 Jeff Anderson - Replace the pure virtual methods for SetGround() and SetCoordinate() with virtual method which simply copy lat/lon to x/y and vice versa. This is essentially no projection.
History:
2003-11-04 Jeff Anderson - Added LocalRadius() methods
History:
2004-02-23 Jeff Anderson - Added Eccentricity(), tCompute(), mCompute(), e4Compute(), and phi2Compute() methods
History:
2004-02-24 Jeff Anderson - Fixed bug in eccentricity computation
History:
2005-02-11 Elizabeth Ribelin - Modified file to support Doxygen documentation
History:
2005-02-25 Elizabeth Ribelin - Added 3 static conversion methods: ToHours(), ToDMS(), and ToHMS()
History:
2005-03-08 Elizabeth Ribelin - Fixed unitTest
History:
2005-06-24 Jeff Anderson - Tweaked format for DMS and HMS methods
History:
2005-07-22 Jeff Anderson - Added static ToPlanetographic() method
History:
2006-04-20 Tracie Sucharski - Fixed bug looking at Target instead of TargetName for sky.
History:
2006-06-20 Stuart Sides - Added ability to lookup the radii if given a "TargetName" in the mapping group.
History:
2006-07-10 Elizabeth Miller - Fixed bugs in new static method
History:
2007-06-27 Steven Lambright - Added static ToPlanetocentric(), ToPositiveWest() and ToPositiveEast() methods. Changed To180Domain() and To360Domain() to be static instead of const. Added Mapping(), MappingLatitudes() and MappingLongitudes() methods for map2map.
History:
2007-08-14 Steven Lambright - Mapping() fixed: should not return cube specific parameters, because they did not go into making the projection.
History:
2008-05-09 Steven Lambright - Added Name(), Version(), IsEquatorialCylindrical() methods
History:
2008-06-12 Christopher Austin - Elaborated error messages.
History:
2008-06-19 Steven Lambright - Fixed memory leak
History:
2009-01-29 Stacy Alley - added a overloaded STATIC method for convenience. TargetRadii, which takes a Pvl, the cube label, and a PvlGroup, a mapping group.
History:
2011-02-10 Jai Rideout - added SetUpperLeftCorner() because ProjectionFactory needed a way to set UpperLeftCornerX and UpperLeftCornerY keywords after creating the projection. Mapping() now adds optional keywords UpperLeftCornerX, UpperLeftCornerY, PixelResolution, and Scale to original mapping group so that cam2map can properly display a clean mapping group.
History:
2011-07-05 Jeannie Backer - Added qCompute() method. Updated documentation.
History:
2011-08-11 Steven Lambright - phi2Compute was running out of iterations for vesta (an asteroid). Fixes #279
History:
2012-03-01 Jeff Anderson - Fixed bug in SetUpperLeftCorner by adding Pvl::Replace when updating the mapping labels
History:
2012-03-30 Steven Lambright and Stuart Sides - To360Domain() and To180Domain() are now constant time operations. Fixes #656.
History:
2012-06-15 Jeannie Backer - Added documentation. Added forward declarations to header file. Ordered includes in implementation file. Moved destructor and accessor methods to the implementation file. Moved the following methods from the ObliqueCylindrical class for generalized xyRangeOblique() method - doSearch(), findExtreme(), setSearchGround(). Changed member variable prefix to m_. Improved unitTest. Resolves #928.
History:
2012-07-25 Jeannie Backer - Modified the new methods related to xyRangeOblique() to verify the validity of the values when setSearchGround() is called. References #954.
History:
2012-08-01 Kimberly Oyama - Added a qFuzzyCompare() to ToPlanetographic() to account for rounding error at the latitude boundaries (-90 and 90 degrees). Updated the unit test to exercise this change. References #604.
History:
2012-08-09 Steven Lambright - Added NaifStatus calls to protect the TargetRadii() method from naif throwing an error/crashing with inputs that have non-target naif codes.
History:
2012-01-19 Debbie A. Cook - Moved nongeneral functionality into another virtual base class layer of TProjection and PlaneProjection. Added m_projectionType and ProjectionType enum and protected method PixelResolution().
History:
2013-03-06 Steven Lambright - Cleaned up and fixed an issue with the Mapping() method which sometimes erroneously threw an exception. Added caching to the TargetRadii(QString) method for performance reasons. Fixes #1534.
History:
2017-06-26 Jesse Mapel - Added a new method to set the universal ground point without adjusting for the longitude domain. Fixes #2185.
Todo:
Continue to modify Projection class to comply with coding standards. Some of these include, but may not be limited to remove "Get" from methods GetX and GetY, change methods to lower camel case, add methods for RelativeScaleFactorLatitude and RelativeScaleFactorLongitude (see LambertAzimuthalEqualArea.cpp).

Definition at line 155 of file Projection.h.

Member Enumeration Documentation

◆ ProjectionType

This enum defines the subclasses of Projection supported in Isis.

Enumerator
Triaxial 

These projections are used to map triaxial and irregular-shaped bodies.

RingPlane 

These projections are used to map ring planes.

Definition at line 166 of file Projection.h.

Constructor & Destructor Documentation

◆ Projection()

Isis::Projection::Projection ( Pvl label)

Constructs an empty Projection object.

Parameters
labelA PVL object containing map projection labels. These labels are fully described in the Isis Map Projection Users Guide. A brief example follows:
Group = Mapping
EquatorialRadius = 3396190.0
PolarRadius = 3376200.0
LongitudeDirection = PositiveEast
LongitudeDomain = 360
LatitudeType = Planetographic
MinimumLatitude = 10.8920539924144
MaximumLatitude = 34.7603960060206
MinimumLongitude = 219.72432466275
MaximumLongitude = 236.186050244411
PixelResolution = 1387.31209461362
ProjectionName = SimpleCylindrical
CenterLongitude = 220.0
EndGroup
End
Exceptions
IException::Unknown- "Projection failed. No target radii available through keywords [EquatorialRadius and PolarRadius] or [TargetName]." @throw IException::Unknown - "Projection failed. Invalid value for keyword [EquatorialRadius]. It must be greater than zero." @throw IException::Unknown - "Projection failed. Invalid value for keyword [PolarRadius]. It must be greater than zero." @throw IException::Unknown - "Projection failed. Invalid value for keyword [LatitudeType] must be [Planetographic or Planetocentric]" @throw IException::Unknown - "Projection failed. Invalid value for keyword [LongitudeDirection] must be [PositiveWest or PositiveEast]" @throw IException::Unknown - "Projection failed. Invalid value for keyword [LongitudeDomain] must be [180 or 360]" @throw IException::Unknown - "Projection failed. [MinimumLatitude] is outside the range of [-90:90]" @throw IException::Unknown - "Projection failed. [MaximumLatitude] is outside the range of [-90:90]" @throw IException::Unknown - "Projection failed. [MinimumLatitude,MaximumLatitude] are not properly ordered" @throw IException::Unknown - "Projection failed. [MinimumLongitude,MaximumLongitude] are not properly ordered" @throw IException::Unknown - "Projection failed. Invalid keyword value(s). [EquatorialRadius] must be greater than or equal to [PolarRadius]" @throw IException::Unknown - "Projection failed. Invalid label group [Mapping]"

Definition at line 91 of file Projection.cpp.

References Isis::PvlObject::findGroup(), Isis::PvlContainer::hasKeyword(), m_good, m_mapper, m_mappingGrp, m_maximumX, m_maximumY, m_minimumX, m_minimumY, m_pixelResolution, m_rotation, m_sky, m_x, m_y, Isis::Null, Isis::PvlObject::Traverse, and Isis::IException::Unknown.

◆ ~Projection()

Isis::Projection::~Projection ( )
virtual

Destroys the Projection object.

Definition at line 148 of file Projection.cpp.

References m_mapper.

Member Function Documentation

◆ GetX()

◆ GetY()

◆ HasGroundRange()

bool Isis::Projection::HasGroundRange ( ) const
virtual

This indicates if the longitude direction type is positive west (as opposed to postive east).

The longitude type was obtained from the label during object construction.

Returns
bool This indicates if the longitude direction type is positive east (as opposed to postive west). The longitude type was obtained from the label during object construction.
bool This method returns the longitude direction as a string. It will return either PositiveEast or PositiveWest.
string The longitude direction, "PositiveEast" or "PositiveWest". This indicates if the longitude domain is -180 to 180 (as opposed to 0 to 360). The longitude domain was obtained from the label during object construction.
bool This indicates if the longitude domain is 0 to 360 (as opposed to -180 to 180). The longitude domain was obtained from the label during object construction.
bool This method converts a longitude into the -180 to 180 domain. It will leave the longitude unchanged if it is already in the domain.
Parameters
lonLongitude to convert into the -180 to 180 domain.
Exceptions
IException::Unknown- "The given longitude is invalid."
Returns
double The longitude, converted to 180 domain. This method converts a longitude into the 0 to 360 domain. It will leave the longitude unchanged if it is already in the domain.
Parameters
lonLongitude to convert into the 0 to 360 domain.
Returns
double The longitude, converted to 360 domain. This method returns the longitude domain as a string. It will return either 180 or 360.
string The longitude domain, "180" or "360". This indicates that the labels contained minimum and maximum ground coordinatess (e.g., a ground range coverage). If the projection has ground range coverage then the MinimumLatitude, MaximumLatitude, MinimumLongitude, and MaximumLongitude methods or comparable methods for other projection types can be used. The ground range coverage essentially defines the area of user interest.
bool

Definition at line 349 of file Projection.cpp.

References m_groundRangeGood.

Referenced by Isis::ProjectionFactory::CreateForCube(), Isis::RingPlaneProjection::Mapping(), Isis::TProjection::MappingLatitudes(), Isis::TProjection::MappingLongitudes(), Isis::Planar::MappingRingLongitudes(), Isis::RingCylindrical::MappingRingLongitudes(), Isis::RingPlaneProjection::MappingRingLongitudes(), Isis::Planar::MappingRingRadii(), Isis::RingCylindrical::MappingRingRadii(), Isis::RingPlaneProjection::MappingRingRadii(), Isis::ProjectionFactory::RingsCreateForCube(), and Isis::TProjection::xyRangeOblique().

◆ IsEquatorialCylindrical()

bool Isis::Projection::IsEquatorialCylindrical ( )
virtual

This method returns true if the projection is equatorial cylindrical.

In other words, if the projection is cylindrical and an image projected at 0 is the same as an image projected at 360.

Returns
bool true if the projection is equatorial cylindrical

Reimplemented in Isis::TProjection, Isis::SimpleCylindrical, Isis::RingCylindrical, Isis::Mercator, and Isis::Equirectangular.

Definition at line 222 of file Projection.cpp.

Referenced by Isis::ShapeModelFactory::create(), and Isis::ProcessMapMosaic::StartProcess().

◆ IsGood()

bool Isis::Projection::IsGood ( ) const

This indicates if the last invocation of SetGround, SetCoordinate, SetUniversalGround, or SetWorld was with successful or not.

If there was success then the Latitude, Longitude, XCoord, YCoord, UniversalLatitude, UniversalLongitude, WorldX, and WorldY methods can be utilized.

Returns
bool True if the last call to SetGround, SetCoordinate, SetUniversalGround, or SetWorld was successful.

Definition at line 374 of file Projection.cpp.

References m_good.

Referenced by Isis::ProjectionFactory::CreateForCube(), Isis::Chip::Load(), Isis::ProjectionFactory::RingsCreateForCube(), Isis::SubArea::UpdateLabel(), Isis::TProjection::XYRangeCheck(), and Isis::RingPlaneProjection::XYRangeCheck().

◆ IsSky()

bool Isis::Projection::IsSky ( ) const

Returns true if projection is sky and false if it is land.

Returns
bool

Definition at line 208 of file Projection.cpp.

References m_sky.

Referenced by Isis::Camera::RawFocalPlanetoImage(), Isis::Camera::SetImage(), Isis::Camera::SetRightAscensionDeclination(), Isis::TrackTool::updateLabels(), and Isis::AdvancedTrackTool::updateRow().

◆ Name()

◆ operator!=()

bool Isis::Projection::operator!= ( const Projection proj)

This method determines whether two map projection objects are not equal.

True is returned if they have at least some differences in the radii, latitude type, longitude direction, resolution, or projection name.

Parameters
projA reference to a Projection object to which this Projection will be compared.
Returns
bool Indicates whether the Projection objects are not equivalent.

Definition at line 178 of file Projection.cpp.

◆ operator==()

bool Isis::Projection::operator== ( const Projection proj)
virtual

This method determines whether two map projection objects are equal by comparing the resolution, and projection name.

Parameters
projA reference to a Projection object to which this Projection will be compared.
Returns
bool Indicates whether the Projection objects are equivalent.

Reimplemented in Isis::UpturnedEllipsoidTransverseAzimuthal, Isis::TransverseMercator, Isis::TProjection, Isis::Sinusoidal, Isis::SimpleCylindrical, Isis::Robinson, Isis::RingPlaneProjection, Isis::RingCylindrical, Isis::PolarStereographic, Isis::PointPerspective, Isis::Planar, Isis::Orthographic, Isis::Mollweide, Isis::Mercator, Isis::LambertConformal, Isis::LambertAzimuthalEqualArea, Isis::Equirectangular, and Isis::ObliqueCylindrical.

Definition at line 162 of file Projection.cpp.

References Name(), and Resolution().

◆ PixelResolution()

double Isis::Projection::PixelResolution ( ) const
protected

Returns the pixel resolution value from the PVL mapping group in meters/pixel.

Returns
double pixel resolution in meters/pixel

Definition at line 840 of file Projection.cpp.

References m_pixelResolution.

Referenced by Isis::TProjection::doSearch(), Isis::Planar::XYRange(), and Isis::RingCylindrical::XYRange().

◆ projectionType()

◆ Resolution()

double Isis::Projection::Resolution ( ) const

This method returns the resolution for mapping world coordinates into projection coordinates.

For example, if the world coordinate system is an image then this routine returns the number of meters per pixel. Likewise, if the world coordinate system is a piece of paper, it might return the number of meters per inch of paper. If the SetWorldMapper method is not invoked then this method returns 1.0

Returns
double The resolution, in appropriate units.

Definition at line 675 of file Projection.cpp.

References m_mapper, and Isis::WorldMapper::Resolution().

Referenced by Isis::ProcessExport::CreateWorldFile(), operator==(), Isis::UniversalGroundMap::Resolution(), and Isis::MeasureTool::updateDist().

◆ Rotation()

double Isis::Projection::Rotation ( ) const

Returns the value of the Rotation keyword from the mapping group.

Returns
double The rotation of the map.

Definition at line 359 of file Projection.cpp.

References m_rotation.

◆ SetComputedXY()

void Isis::Projection::SetComputedXY ( double  x,
double  y 
)
protected

◆ setProjectionType()

void Isis::Projection::setProjectionType ( const ProjectionType  ptype)

Sets the projection subclass type.

Parameters
ptypeThe projection subclass type

Definition at line 188 of file Projection.cpp.

Referenced by Isis::RingPlaneProjection::RingPlaneProjection(), and Isis::TProjection::TProjection().

◆ SetUnboundUniversalGround()

bool Isis::Projection::SetUnboundUniversalGround ( const double  coord1,
const double  coord2 
)
virtual

This method is used to set the lat/lon or radius/azimuth (i.e.

ring longitude) coordinate, depending on the projection type. The Set forces an attempted calculation of the projection X/Y values. This may or may not be successful and a status is returned as such. This method will not adjust the longitude coordinate based on the longitude domain.

Parameters
coord1Latitude (planetocentric) or ring radius to project
coord2Longitude or ring longitude to project. The value passed in should be PositiveEast, Domain360.
Returns
bool Indicates whether the method was successful.

Reimplemented in Isis::TProjection.

Definition at line 446 of file Projection.cpp.

References m_good, Isis::Null, projectionType(), Isis::TProjection::SetUnboundUniversalGround(), Isis::RingPlaneProjection::SetUniversalGround(), and Triaxial.

Referenced by Isis::UniversalGroundMap::SetUnboundGround().

◆ SetUniversalGround()

bool Isis::Projection::SetUniversalGround ( const double  coord1,
const double  coord2 
)
virtual

This method is used to set the lat/lon or radius/azimuth (i.e.

ring longitude) coordinate, depending on the projection type. The Set forces an attempted calculation of the projection X/Y values. This may or may not be successful and a status is returned as such.

Parameters
coord1Latitude (planetocentric) or ring radius to project
coord2Longitude or ring longitude to project. The value passed in should be PositiveEast, Domain360.
Returns
bool Indicates whether the method was successful.

Reimplemented in Isis::RingPlaneProjection, and Isis::TProjection.

Definition at line 417 of file Projection.cpp.

References m_good, Isis::Null, projectionType(), Isis::TProjection::SetUniversalGround(), Isis::RingPlaneProjection::SetUniversalGround(), and Triaxial.

Referenced by Isis::Chip::Load(), Isis::DemShape::localRadius(), Isis::Camera::RawFocalPlanetoImage(), Isis::UniversalGroundMap::SetGround(), Isis::Camera::SetRightAscensionDeclination(), Isis::UniversalGroundMap::SetUniversalGround(), and Isis::ProcessMapMosaic::StartProcess().

◆ SetUpperLeftCorner()

void Isis::Projection::SetUpperLeftCorner ( const Displacement x,
const Displacement y 
)

This method searches for extreme (min/max/discontinuity) coordinate values along the constBorder line between minBorder and maxBorder (that is, across latitudes/longitudes).

This method locates the extrema by utilizing the findExtreme() method until the coordinate values converge. Then, extremeVal parameter is updated with this value before returning.

Discontinuities are stored in m_specialLatCases and m_specialLonCases so they may be checked again later, which creates significantly more accuracy in some cases.

Parameters
minBorderMinimum latitude or longitude to search between.
maxBorderMaximum latitude or longitude to search between.
extremeValThe resulting global coordinate value (min or max value for x or y, depending on findMin and searchX) on the constBorder.
constBorderThe latitude or longitude that remains constant. The method will step along this border.
searchXIndicates whether the method is searching for a min or max x-coordinate. If false the method searches for min or max y-coordinate.
searchLongitudeIndicates whether the method will search along a longitude. If true, constBorder is longitude and all other borders are latitudes. If false, the method searches a latitude (constBorder is a lat, other borders lons).
findMinIndicates whether the method is looking for a minimum coordinate value. If false, the method is looking for a maximum value.
Author
Steven Lambright
History:
2011-07-02 Jeannie Backer - Moved this code from ObliqueCylindrical class to its own method here. Added condition to do-while loop for more precision. Replaced hard-coded TOLERANCE with 1/2 pixel resolution. (Defaults to 0.5)

Searches for extreme (min/max/discontinuity) coordinate values across latitudes/longitudes.

This method looks for these extrema along the constBorder between minBorder and maxBorder by stepping along constBorder (10 times) from the minBorder and maxBorder. Then, the range of this extreme value is recorded in minBorder and maxBorder and the coordinate values corresponding to these new borders are stored in minBorderX, minBorderY, maxBorderX and maxBorderY.

This function should be used by calling it repeatedly until minBorderX and minBorderY do not equal maxBorderX and maxBorderY, respectively. Discontinuities will cause the minBorderX, minBorderY, maxBorderX and maxBorderY to never converge. If minBorderX never comes close to maxBorderX or minBorderY never comes close to maxBorderY, then between minBorder and maxBorder is the value of the most extreme value. In this case, either the smaller or larger of the x or y values found will be correct, depending on the values of findMin and searchX.

Parameters
minBorderMinimum latitude or longitude to search between. This value gets updated to a more precise range.
maxBorderMaximum latitude or longitude to search between. This value gets updated to a more precise range.
minBorderXThe x-value corresponding to the lower resultant minBorder and the constBorder, which is more accurate when nearly equal to maxBorderX.
minBorderYThe y-value corresponding to the lower resultant minBorder and the constBorder, which is more accurate when nearly equal to maxBorderY.
maxBorderXThe x-value corresponding to the higher resultant maxBorder and the constBorder, which is more accurate when nearly equal to minBorderX.
maxBorderYThe y-value corresponding to the higher resultant maxBorder and the constBorder, which is more accurate when nearly equal to minBorderY.
constBorderThe latitude or longitude that remains constant. The method will step along this border.
searchXIndicates whether the method is searching for a min or max x-coordinate. If false the method searches for min or max y-coordinate.
searchLongitudeIndicates whether the method will search along a longitude. If true, constBorder is longitude and all other borders are latitudes. If false, the method searches a latitude (constBorder is a lat, other borders lons).
findMinIndicates whether the method is looking for a minimum coordinate value. If false, the method is looking for a maximum value.
Author
Stephen Lambright
History:
2011-07-02 Jeannie Backer - Moved this code from ObliqueCylindrical class to its own method here. Replaced parameters minVal and maxVal with minBorderX, minBorderY, maxBorderX, and maxBorderY.

This function sets the ground for the given border values. It calls the SetGround(lat, lon) method with the appropriate lat/lon values, depending on whether variableIsLat is true.

This method is used by doSearch and findExtreme in order to set the ground correctly each time.

Parameters
variableBorderThe latitude or longitude that is variable in the search methods.
constBorderThe latitude or longitude that is constant in the search methods.
variableIsLatIndicates whether variableBorder is the latittude value and constBorder is the longitude value. If false, variableBorder is the longitude value and constBorder is the latitude value.
Author
Stephen Lambright
History:
2011-07-02 Jeannie Backer - Moved this code from ObliqueCylindrical class to its own method here. Added error.

This method sets the UpperLeftCornerX and UpperLeftCornerY keywords in the projection mapping group, in meters.

Parameters
xthe upper left corner x value
ythe upper left corner y value

Definition at line 1373 of file Projection.cpp.

References Isis::PvlContainer::addKeyword(), m_mappingGrp, Isis::Displacement::meters(), and Isis::toString().

Referenced by Isis::ProjectionFactory::CreateForCube(), Isis::ProjectionFactory::CreateFromCube(), Isis::ProjectionFactory::RingsCreateForCube(), and Isis::ProjectionFactory::RingsCreateFromCube().

◆ SetWorld()

bool Isis::Projection::SetWorld ( const double  worldX,
const double  worldY 
)
virtual

This method is used to set a world coordinate.

A world coordinate is a different coordinate type that has a one-to-one mapping to the projection coordinate system. For example, mapping pixel samples and lines to projection x's and y's. The Set forces an attempted calculation of the corresponding latitude/longitude position. This may or may not be successful and a status is returned as such. Note that is only applies if the Projection object was given an WorldMapper object during construction. If an WorldMapper was not supplied then SetWorld operates exactly the same as SetCoordinate (impling that world coordinate and projection coordinate are identical).

Parameters
worldXWorld X coordinate in units that are specified by the WorldMapper object (e.g., pixels, millimeters, etc)
worldYWorld Y coordinate in units that are specified by the WorldMapper object (e.g., pixels, millimeters, etc)
Returns
bool Indicates whether the method was successful.

Definition at line 497 of file Projection.cpp.

References m_mapper, Isis::WorldMapper::ProjectionX(), and Isis::WorldMapper::ProjectionY().

Referenced by Isis::ProcessExport::CreateWorldFile(), Isis::UniversalGroundMap::GroundRange(), Isis::Cube::latLonRange(), Isis::Chip::Load(), Isis::UniversalGroundMap::SetImage(), Isis::Camera::SetImageMapProjection(), Isis::Camera::SetImageSkyMapProjection(), Isis::MeasureTool::updateDist(), Isis::SubArea::UpdateLabel(), Isis::TrackTool::updateLabels(), Isis::AdvancedTrackTool::updateRow(), and Isis::PolygonTools::XYToLatLon().

◆ SetWorldMapper()

void Isis::Projection::SetWorldMapper ( WorldMapper mapper)

If desired the programmer can use this method to set a world mapper to be used in the SetWorld, WorldX, and WorldY methods.

Mappers typically transform a projection coordinate (x/y) into the desired working coordinate system, for example, cube pixels or inches on a piece of paper. They transform in both directions (world to projection and projection to world). This allows for conversions from line/sample to latitude/longitude and vice versa. This projection will take ownership of the WorldMapper pointer.

Parameters
mapperPointer to the mapper

Definition at line 474 of file Projection.cpp.

References m_mapper.

Referenced by Isis::ProjectionFactory::CreateForCube(), Isis::ProjectionFactory::CreateFromCube(), Isis::ProjectionFactory::RingsCreateForCube(), and Isis::ProjectionFactory::RingsCreateFromCube().

◆ SetXY()

◆ ToDMS()

QString Isis::Projection::ToDMS ( double  angle)
static

Converts the given angle (in degrees) to degrees, minutes, seconds.

Outputs in the form xxx yym zz.zzzs, for example, 206.291 degrees is 206 17m 27.6s

Parameters
angleAngle in degrees to be converted to degrees, minutes, seconds
Returns
string The angle in Degrees, minutes, seconds

Definition at line 706 of file Projection.cpp.

◆ ToHMS()

QString Isis::Projection::ToHMS ( double  angle)
static

Converts the given angle (in degrees) to hours, minutes, seconds.

Outputs in the form xxh yym zz.zzzs For example, 206.291 will be 13h 45m 09.84s

Parameters
angleAngle in degrees to be converted to hours, minutes, seconds
Returns
string The angle in Hours, minutes, seconds

Definition at line 741 of file Projection.cpp.

References ToHours().

◆ ToHours()

double Isis::Projection::ToHours ( double  angle)
static

Converts the given angle (in degrees) to hours by using the ratio 15 degrees per hour.

Parameters
angleAngle in degrees to be converted to hours
Returns
double The number of hours for the given angle.

Definition at line 693 of file Projection.cpp.

Referenced by ToHMS().

◆ ToProjectionX()

double Isis::Projection::ToProjectionX ( const double  worldX) const

This method converts a world x value to a projection x value.

For example, if the world coordinate system is an image then this method converts a sample position to a projection x value. Note that if SetWorldMapper is not used then this routine simply returns the value of the argument. That is, no mapping occurs.

Parameters
worldXWorld x coordinate
Exceptions
IException::Unknown- "The given x-value is invalid."
Returns
double The projection X coordinate value.

Definition at line 622 of file Projection.cpp.

References m_mapper, Isis::Null, Isis::WorldMapper::ProjectionX(), and Isis::IException::Unknown.

Referenced by Isis::OverlapStatistics::OverlapStatistics(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), and Isis::ProcessMapMosaic::StartProcess().

◆ ToProjectionY()

double Isis::Projection::ToProjectionY ( const double  worldY) const

This method converts a world y value to a projection y value.

For example, if the world coordinate system is an image then this method converts a line position to a projection y value. Note that if SetWorldMapper is not used then this routine simply returns the value of the argument. That is, no mapping occurs.

Parameters
worldYWorld y coordinate
Exceptions
IException::Unknown- "The given y-value is invalid."
Returns
double The projection Y coordinate value.

Definition at line 650 of file Projection.cpp.

References m_mapper, Isis::Null, Isis::WorldMapper::ProjectionY(), and Isis::IException::Unknown.

Referenced by Isis::OverlapStatistics::OverlapStatistics(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), and Isis::ProcessMapMosaic::StartProcess().

◆ ToWorldX()

double Isis::Projection::ToWorldX ( const double  projectionX) const

This method converts a projection x value to a world x value.

For example, if the world coordinate system is an image then this method converts a projection x to a sample position. Note that if SetWorldMapper is not used then this routine simply returns the value of the argument. That is, no mapping occurs.

Parameters
projectionXProjection x value in meters
Exceptions
IException::Unknown- "The given x-value is invalid."
Returns
double The world X coordinate value.

Definition at line 566 of file Projection.cpp.

References m_mapper, Isis::Null, Isis::IException::Unknown, and Isis::WorldMapper::WorldX().

Referenced by Isis::OverlapStatistics::OverlapStatistics(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), and Isis::ProcessMapMosaic::StartProcess().

◆ ToWorldY()

double Isis::Projection::ToWorldY ( const double  projectionY) const

This method converts a projection y value to a world y value.

For example, if the world coordinate system is an image then this method converts a projection y to a line position. Note that if SetWorldMapper is not used then this routine simply returns the value of the argument. That is, no mapping occurs.

Parameters
projectionYProjection y value in meters
Exceptions
IException::Unknown- "The given y-value is invalid."
Returns
double The world Y coordinate value.

Definition at line 594 of file Projection.cpp.

References m_mapper, Isis::Null, Isis::IException::Unknown, and Isis::WorldMapper::WorldY().

Referenced by Isis::OverlapStatistics::OverlapStatistics(), Isis::ProcessMapMosaic::RingsSetOutputCube(), Isis::ProcessMapMosaic::SetOutputCube(), and Isis::ProcessMapMosaic::StartProcess().

◆ Version()

virtual QString Isis::Projection::Version ( ) const
pure virtual

◆ WorldX()

double Isis::Projection::WorldX ( ) const
virtual

This returns the world X coordinate provided SetGround, SetCoordinate, SetUniversalGround, or SetWorld returned with success.

Success can also be checked using the IsGood method. The units of X will be in the units as specified by the WorldMapper object which was given to the SetWorldMapper method. If a mapper object was not given then world coordinates are the same as the projection coordinates (i.e., WorldX and XCoord will return the same value).

Returns
double The world X coordinate.

Definition at line 524 of file Projection.cpp.

References m_mapper, m_x, and Isis::WorldMapper::WorldX().

Referenced by Isis::MosaicSceneItem::drawImage(), Isis::ImagePolygon::FixPolePoly(), Isis::Chip::Load(), Isis::DemShape::localRadius(), Isis::Camera::RawFocalPlanetoImage(), Isis::UniversalGroundMap::Sample(), Isis::Camera::SetRightAscensionDeclination(), and Isis::ProcessMapMosaic::StartProcess().

◆ WorldY()

double Isis::Projection::WorldY ( ) const
virtual

This returns the world Y coordinate provided SetGround, SetCoordinate, SetUniversalGround, or SetWorld returned with success.

Success can also be checked using the IsGood method. The units of Y will be in the units as specified by the WorldMapper object which was given to the SetWorldMapper. If a mapper object was not given then world coordinates are the same as the projection coordinates (i.e., WorldY and YCoord will return the same value).

Returns
double The world Y coordinate.

Definition at line 544 of file Projection.cpp.

References m_mapper, m_y, and Isis::WorldMapper::WorldY().

Referenced by Isis::MosaicSceneItem::drawImage(), Isis::ImagePolygon::FixPolePoly(), Isis::UniversalGroundMap::Line(), Isis::Chip::Load(), Isis::DemShape::localRadius(), Isis::Camera::RawFocalPlanetoImage(), and Isis::Camera::SetRightAscensionDeclination().

◆ XCoord()

double Isis::Projection::XCoord ( ) const

◆ YCoord()

double Isis::Projection::YCoord ( ) const

Member Data Documentation

◆ m_good

bool Isis::Projection::m_good
protected

Indicates if the contents of m_x, m_y, m_latitude, and m_longitude are valid.

Definition at line 300 of file Projection.h.

Referenced by Isis::TProjection::findExtreme(), IsGood(), Projection(), SetComputedXY(), Isis::Equirectangular::SetCoordinate(), Isis::LambertConformal::SetCoordinate(), Isis::LunarAzimuthalEqualArea::SetCoordinate(), Isis::Mercator::SetCoordinate(), Isis::Mollweide::SetCoordinate(), Isis::ObliqueCylindrical::SetCoordinate(), Isis::Orthographic::SetCoordinate(), Isis::Planar::SetCoordinate(), Isis::PointPerspective::SetCoordinate(), Isis::PolarStereographic::SetCoordinate(), Isis::RingCylindrical::SetCoordinate(), Isis::RingPlaneProjection::SetCoordinate(), Isis::Robinson::SetCoordinate(), Isis::SimpleCylindrical::SetCoordinate(), Isis::Sinusoidal::SetCoordinate(), Isis::TProjection::SetCoordinate(), Isis::TransverseMercator::SetCoordinate(), Isis::Equirectangular::SetGround(), Isis::LambertConformal::SetGround(), Isis::LunarAzimuthalEqualArea::SetGround(), Isis::Mercator::SetGround(), Isis::Mollweide::SetGround(), Isis::ObliqueCylindrical::SetGround(), Isis::Orthographic::SetGround(), Isis::PointPerspective::SetGround(), Isis::PolarStereographic::SetGround(), Isis::Robinson::SetGround(), Isis::SimpleCylindrical::SetGround(), Isis::Sinusoidal::SetGround(), Isis::TProjection::SetGround(), Isis::TransverseMercator::SetGround(), Isis::Planar::SetGround(), Isis::RingCylindrical::SetGround(), Isis::RingPlaneProjection::SetGround(), SetUnboundUniversalGround(), Isis::TProjection::SetUnboundUniversalGround(), SetUniversalGround(), Isis::TProjection::SetUniversalGround(), Isis::RingPlaneProjection::SetUniversalGround(), SetXY(), Isis::LambertConformal::XYRange(), Isis::TProjection::XYRangeCheck(), and Isis::RingPlaneProjection::XYRangeCheck().

◆ m_groundRangeGood

bool Isis::Projection::m_groundRangeGood
protected

Indicates if the ground range (min/max lat/lons) were read from the labels.

Definition at line 313 of file Projection.h.

Referenced by HasGroundRange(), Isis::RingPlaneProjection::RingPlaneProjection(), Isis::TProjection::TProjection(), Isis::RingPlaneProjection::XYRange(), and Isis::TProjection::XYRange().

◆ m_mapper

WorldMapper* Isis::Projection::m_mapper
protected

This points to a mapper passed into the SetWorldMapper method.

This mapper allows the programmer to specify a different world coordinate system. Thus the programmer could pass in line/sample positions in order to obtain a latitude/longitude or set a lat/lon and get a line/sample.

Definition at line 292 of file Projection.h.

Referenced by Projection(), Resolution(), Isis::RingPlaneProjection::Scale(), Isis::TProjection::Scale(), SetWorld(), SetWorldMapper(), ToProjectionX(), ToProjectionY(), ToWorldX(), ToWorldY(), WorldX(), WorldY(), and ~Projection().

◆ m_mappingGrp

PvlGroup Isis::Projection::m_mappingGrp
protected

Mapping group that created this projection.

Definition at line 329 of file Projection.h.

Referenced by Isis::Equirectangular::Mapping(), Isis::LambertConformal::Mapping(), Isis::LunarAzimuthalEqualArea::Mapping(), Isis::Mercator::Mapping(), Isis::Mollweide::Mapping(), Isis::ObliqueCylindrical::Mapping(), Isis::Orthographic::Mapping(), Isis::PointPerspective::Mapping(), Isis::PolarStereographic::Mapping(), Isis::RingPlaneProjection::Mapping(), Isis::Robinson::Mapping(), Isis::SimpleCylindrical::Mapping(), Isis::Sinusoidal::Mapping(), Isis::TProjection::Mapping(), Isis::TransverseMercator::Mapping(), Isis::Equirectangular::MappingLatitudes(), Isis::LambertConformal::MappingLatitudes(), Isis::Mercator::MappingLatitudes(), Isis::Orthographic::MappingLatitudes(), Isis::PointPerspective::MappingLatitudes(), Isis::PolarStereographic::MappingLatitudes(), Isis::TProjection::MappingLatitudes(), Isis::TransverseMercator::MappingLatitudes(), Isis::Equirectangular::MappingLongitudes(), Isis::LambertConformal::MappingLongitudes(), Isis::Mercator::MappingLongitudes(), Isis::Mollweide::MappingLongitudes(), Isis::Orthographic::MappingLongitudes(), Isis::PointPerspective::MappingLongitudes(), Isis::PolarStereographic::MappingLongitudes(), Isis::Robinson::MappingLongitudes(), Isis::SimpleCylindrical::MappingLongitudes(), Isis::Sinusoidal::MappingLongitudes(), Isis::TProjection::MappingLongitudes(), Isis::TransverseMercator::MappingLongitudes(), Isis::Planar::MappingRingLongitudes(), Isis::RingCylindrical::MappingRingLongitudes(), Isis::RingPlaneProjection::MappingRingLongitudes(), Isis::Planar::MappingRingRadii(), Isis::RingCylindrical::MappingRingRadii(), Isis::RingPlaneProjection::MappingRingRadii(), Projection(), Isis::RingPlaneProjection::RingPlaneProjection(), SetUpperLeftCorner(), and Isis::TProjection::TProjection().

◆ m_maximumX

◆ m_maximumY

◆ m_minimumX

double Isis::Projection::m_minimumX
protected

The data elements m_minimumX, m_minimumY, m_maximumX, and m_maximumY are convience data elements when you write the XYRange virtual function.

They are used in conjuction with the XYRangeCheck convience method. After utilizing XYRangeCheck to test boundary conditions in the XYRange method these values will contain the projection x/y coverage for the ground range specified by min/max lat/lon.

Definition at line 317 of file Projection.h.

Referenced by Projection(), Isis::Equirectangular::XYRange(), Isis::LambertConformal::XYRange(), Isis::LunarAzimuthalEqualArea::XYRange(), Isis::Mercator::XYRange(), Isis::Mollweide::XYRange(), Isis::Orthographic::XYRange(), Isis::Planar::XYRange(), Isis::PolarStereographic::XYRange(), Isis::RingCylindrical::XYRange(), Isis::Robinson::XYRange(), Isis::SimpleCylindrical::XYRange(), Isis::Sinusoidal::XYRange(), Isis::TransverseMercator::XYRange(), Isis::TProjection::XYRangeCheck(), Isis::RingPlaneProjection::XYRangeCheck(), and Isis::TProjection::xyRangeOblique().

◆ m_minimumY

◆ m_pixelResolution

double Isis::Projection::m_pixelResolution
private

Pixel resolution value from the PVL mapping group, in meters/pixel.

Definition at line 344 of file Projection.h.

Referenced by PixelResolution(), and Projection().

◆ m_rotation

double Isis::Projection::m_rotation
private

Rotation of map (usually zero)

Definition at line 333 of file Projection.h.

Referenced by GetX(), GetY(), Projection(), Rotation(), and SetComputedXY().

◆ m_sky

bool Isis::Projection::m_sky
protected

Indicates whether projection is sky or land.

Definition at line 310 of file Projection.h.

Referenced by IsSky(), and Projection().

◆ m_x

double Isis::Projection::m_x
private

This contains the rotated X coordinate for a specific projection at theposition indicated by m_latitude/m_longitude.

The value is only usable if m_good is true.

Definition at line 335 of file Projection.h.

Referenced by GetX(), GetY(), Projection(), SetComputedXY(), SetXY(), WorldX(), and XCoord().

◆ m_y

double Isis::Projection::m_y
private

This contains the rotated Y coordinate for a specific projection at the position indicated by m_latitude/m_longitude.

The value is only usable if m_good is true.

Definition at line 339 of file Projection.h.

Referenced by GetX(), GetY(), Projection(), SetComputedXY(), SetXY(), WorldY(), and YCoord().


The documentation for this class was generated from the following files:
Isis::Projection::Projection
Projection(Pvl &label)
Constructs an empty Projection object.
Definition: Projection.cpp:91
Isis::Projection::PixelResolution
double PixelResolution() const
Returns the pixel resolution value from the PVL mapping group in meters/pixel.
Definition: Projection.cpp:840
Isis::ProjectionFactory::Create
static Isis::Projection * Create(Isis::Pvl &label, bool allowDefaults=false)
This method returns a pointer to a Projection object.
Definition: ProjectionFactory.cpp:51