lsst.geom  22.0.1-5-g096abc9+1d2032976f
Public Member Functions | Related Functions | List of all members
lsst::geom::SpherePoint Class Referencefinal

Point in an unspecified spherical coordinate system. More...

#include <SpherePoint.h>

Public Member Functions

 SpherePoint (Angle const &longitude, Angle const &latitude)
 Construct a SpherePoint from a longitude and latitude. More...
 
 SpherePoint (double longitude, double latitude, AngleUnit units)
 Construct a SpherePoint from double longitude and latitude. More...
 
 SpherePoint (sphgeom::Vector3d const &vector)
 Construct a SpherePoint from a vector representing a direction. More...
 
 SpherePoint (sphgeom::LonLat const &lonLat) noexcept
 Construct a SpherePoint from a sphgeom::LonLat. More...
 
 SpherePoint () noexcept
 Construct a SpherePoint with "nan" for longitude and latitude. More...
 
 SpherePoint (SpherePoint const &other) noexcept
 Create a copy of a SpherePoint. More...
 
 SpherePoint (SpherePoint &&other) noexcept
 Create a copy of a SpherePoint. More...
 
 ~SpherePoint () noexcept
 
SpherePointoperator= (SpherePoint const &other) noexcept
 Overwrite this object with the value of another SpherePoint. More...
 
SpherePointoperator= (SpherePoint &&other) noexcept
 Overwrite this object with the value of another SpherePoint. More...
 
 operator sphgeom::LonLat () const noexcept
 Make SpherePoint implicitly convertible to LonLat. More...
 
Angle getLongitude () const noexcept
 The longitude of this point. More...
 
Angle getRa () const noexcept
 Synonym for getLongitude. More...
 
Angle getLatitude () const noexcept
 The latitude of this point. More...
 
Angle getDec () const noexcept
 Synonym for getLatitude. More...
 
Point2D getPosition (AngleUnit unit) const noexcept
 Return longitude, latitude as a Point2D object. More...
 
sphgeom::UnitVector3d getVector () const noexcept
 A unit vector representation of this point. More...
 
Angle operator[] (size_t index) const
 Longitude and latitude by index. More...
 
bool atPole () const noexcept
 true if this point is either coordinate pole. More...
 
bool isFinite () const noexcept
 true if this point is a well-defined position. More...
 
bool operator== (SpherePoint const &other) const noexcept
 true if two points have the same longitude and latitude. More...
 
bool operator!= (SpherePoint const &other) const noexcept
 false if two points represent the same position. More...
 
std::size_t hash_value () const noexcept
 Return a hash of this object. More...
 
Angle bearingTo (SpherePoint const &other) const
 Orientation at this point of the great circle arc to another point. More...
 
Angle separation (SpherePoint const &other) const noexcept
 Angular distance between two points. More...
 
SpherePoint rotated (SpherePoint const &axis, Angle const &amount) const noexcept
 Return a point rotated from this one around an axis. More...
 
SpherePoint offset (Angle const &bearing, Angle const &amount) const
 Return a point offset from this one along a great circle. More...
 
std::pair< Angle, AnglegetTangentPlaneOffset (SpherePoint const &other) const
 Get the offset from a tangent plane centered at this point to another point. More...
 

Related Functions

(Note that these are not member functions.)

std::ostreamoperator<< (std::ostream &os, SpherePoint const &point)
 Print the value of a point to a stream. More...
 

Detailed Description

Point in an unspecified spherical coordinate system.

This class represents a point on a sphere in the mathematical rather than the astronomical sense. It does not refer to any astronomical reference frame, nor does it have any concept of (radial) distance.

Points can be represented either as spherical coordinates or as a unit vector. The adopted convention for converting between these two systems is that (0, 0) corresponds to <1, 0, 0>, that (π/2, 0) corresponds to <0, 1, 0>, and that (0, π/2) corresponds to <0, 0, 1>.

To keep usage simple, SpherePoint does not support modification of existing values; transformations of SpherePoints should be expressed as a new object. To support cases where a SpherePoint must be updated in-place, SpherePoint supports assignment to an existing object. One example is in containers of SpherePoints; no STL container has an atomic element-replacement method, so complicated constructions would need to be used if you couldn't overwrite an existing element.

Definition at line 57 of file SpherePoint.h.

Constructor & Destructor Documentation

◆ SpherePoint() [1/7]

lsst::geom::SpherePoint::SpherePoint ( Angle const &  longitude,
Angle const &  latitude 
)

Construct a SpherePoint from a longitude and latitude.

Parameters
longitudeThe longitude of the point. +/-inf is treated as nan (because longitude is wrapped to a standard range and infinity cannot be wrapped)
latitudeThe latitude of the point. Must be in the interval [-π/2, π/2] radians.
Exceptions
pex::exceptions::InvalidParameterErrorThrown if latitude is out of range.
Exception Safety
Provides strong exception guarantee.

Definition at line 68 of file SpherePoint.cc.

◆ SpherePoint() [2/7]

lsst::geom::SpherePoint::SpherePoint ( double  longitude,
double  latitude,
AngleUnit  units 
)

Construct a SpherePoint from double longitude and latitude.

Parameters
longitudeThe longitude of the point. +/-inf is treated as nan (because longitude is wrapped to a standard range and infinity cannot be wrapped)
latitudeThe latitude of the point. Must be in the interval [-π/2, π/2] radians.
unitsThe units of longitude and latitude
Exceptions
pex::exceptions::InvalidParameterErrorThrown if latitude is out of range.
Exception Safety
Provides strong exception guarantee.

Definition at line 65 of file SpherePoint.cc.

◆ SpherePoint() [3/7]

lsst::geom::SpherePoint::SpherePoint ( sphgeom::Vector3d const &  vector)
explicit

Construct a SpherePoint from a vector representing a direction.

Parameters
vectorA position whose direction will be stored as a SpherePoint. Must not be the zero vector. Need not be normalized, and the norm will not affect the value of the point.
Exceptions
pex::exceptions::InvalidParameterErrorThrown if vector is the zero vector.
Exception Safety
Provides strong exception guarantee.
Note
If the SpherePoint is at a pole then longitude is set to 0. That provides predictable behavior for bearingTo and offset.

Definition at line 76 of file SpherePoint.cc.

◆ SpherePoint() [4/7]

lsst::geom::SpherePoint::SpherePoint ( sphgeom::LonLat const &  lonLat)
noexcept

Construct a SpherePoint from a sphgeom::LonLat.

Parameters
lonLatThe lonLat
Exception Safety
Shall not throw exceptions.

Definition at line 94 of file SpherePoint.cc.

◆ SpherePoint() [5/7]

lsst::geom::SpherePoint::SpherePoint ( )
noexcept

Construct a SpherePoint with "nan" for longitude and latitude.

Definition at line 108 of file SpherePoint.cc.

◆ SpherePoint() [6/7]

lsst::geom::SpherePoint::SpherePoint ( SpherePoint const &  other)
defaultnoexcept

Create a copy of a SpherePoint.

Parameters
otherThe point to copy.
Exception Safety
Shall not throw exceptions.

◆ SpherePoint() [7/7]

lsst::geom::SpherePoint::SpherePoint ( SpherePoint &&  other)
defaultnoexcept

Create a copy of a SpherePoint.

As SpherePoint(SpherePoint const&), except that other may be left in an unspecified but valid state.

◆ ~SpherePoint()

lsst::geom::SpherePoint::~SpherePoint ( )
defaultnoexcept

Member Function Documentation

◆ atPole()

bool lsst::geom::SpherePoint::atPole ( ) const
inlinenoexcept

true if this point is either coordinate pole.

Returns
true if this point is at the north or south pole, false otherwise
Exception Safety
Shall not throw exceptions.

Definition at line 237 of file SpherePoint.h.

◆ bearingTo()

Angle lsst::geom::SpherePoint::bearingTo ( SpherePoint const &  other) const

Orientation at this point of the great circle arc to another point.

The orientation is measured in a plane tangent to the sphere at this point, with 0 degrees along the direction of increasing longitude and 90 degrees along the direction of increasing latitude. Thus for any point except the pole, the arc is due east at 0 degrees and due north at 90 degrees. To understand the behavior at the poles it may help to imagine the point has been shifted slightly by decreasing the absolute value of its latitude.

If the points are on opposite sides of the sphere then the returned bearing may be any value.

Parameters
otherthe point to which to measure the bearing
Returns
the direction, as defined above, in the interval [0, 2π).
Exception Safety
Provides strong exception guarantee.
Note
For two points A and B, A.bearingTo(B) will in general not be 180 degrees away from B.bearingTo(A).

Definition at line 159 of file SpherePoint.cc.

◆ getDec()

Angle lsst::geom::SpherePoint::getDec ( ) const
inlinenoexcept

Synonym for getLatitude.

Definition at line 193 of file SpherePoint.h.

◆ getLatitude()

Angle lsst::geom::SpherePoint::getLatitude ( ) const
inlinenoexcept

The latitude of this point.

Returns
the latitude, in the interval [-π/2, π/2] radians.
Exception Safety
Shall not throw exceptions.

Definition at line 190 of file SpherePoint.h.

◆ getLongitude()

Angle lsst::geom::SpherePoint::getLongitude ( ) const
inlinenoexcept

The longitude of this point.

Returns
the longitude, in the interval [0, 2π) radians.
Exception Safety
Shall not throw exceptions.

Definition at line 178 of file SpherePoint.h.

◆ getPosition()

Point2D lsst::geom::SpherePoint::getPosition ( AngleUnit  unit) const
noexcept

Return longitude, latitude as a Point2D object.

Parameters
[in]unitUnits of returned data.
Exception Safety
Shall not throw exceptions.

Definition at line 129 of file SpherePoint.cc.

◆ getRa()

Angle lsst::geom::SpherePoint::getRa ( ) const
inlinenoexcept

Synonym for getLongitude.

Definition at line 181 of file SpherePoint.h.

◆ getTangentPlaneOffset()

std::pair< geom::Angle, geom::Angle > lsst::geom::SpherePoint::getTangentPlaneOffset ( SpherePoint const &  other) const

Get the offset from a tangent plane centered at this point to another point.

This is suitable only for small angles.

Parameters
[in]otherCoordinate to which to compute offset
Returns
pair of Angles: Longitude and Latitude offsets

Definition at line 214 of file SpherePoint.cc.

◆ getVector()

sphgeom::UnitVector3d lsst::geom::SpherePoint::getVector ( ) const
noexcept

A unit vector representation of this point.

Returns
a unit vector whose direction corresponds to this point
Exception Safety
Shall not throw exceptions.

Definition at line 124 of file SpherePoint.cc.

◆ hash_value()

std::size_t lsst::geom::SpherePoint::hash_value ( ) const
noexcept

Return a hash of this object.

Definition at line 154 of file SpherePoint.cc.

◆ isFinite()

bool lsst::geom::SpherePoint::isFinite ( ) const
noexcept

true if this point is a well-defined position.

Returns
true if getLongitude(), getLatitude(), and getVector() return finite floating-point values; false if any return NaN or infinity.
Exception Safety
Shall not throw exceptions.

Definition at line 144 of file SpherePoint.cc.

◆ offset()

SpherePoint lsst::geom::SpherePoint::offset ( Angle const &  bearing,
Angle const &  amount 
) const

Return a point offset from this one along a great circle.

For any point A, any angle bearing and any non-negative angle amount, if B = A.offset(bearing, amount)thenA.bearingTo(B) = amountandA.separationTo(B) = amount. Negative values ofamountare supported in the obvious manner: A.offset(bearing, delta) = A.offset(bearing + 180*degrees, -delta)`

Parameters
bearingthe direction in which to move this point, following the conventions described in bearingTo.
amountthe distance by which to move along the great circle defined by bearing
Returns
a new point created by rotating this point. If the new point is at the pole then its longitude will be 0.
Exception Safety
Provides strong exception guarantee.

Definition at line 185 of file SpherePoint.cc.

◆ operator sphgeom::LonLat()

lsst::geom::SpherePoint::operator sphgeom::LonLat ( ) const
noexcept

Make SpherePoint implicitly convertible to LonLat.

Exception Safety
Shall not throw exceptions.

Definition at line 118 of file SpherePoint.cc.

◆ operator!=()

bool lsst::geom::SpherePoint::operator!= ( SpherePoint const &  other) const
noexcept

false if two points represent the same position.

This operator shall always return the logical negation of operator==(); see its documentation for a detailed specification.

Definition at line 152 of file SpherePoint.cc.

◆ operator=() [1/2]

SpherePoint & lsst::geom::SpherePoint::operator= ( SpherePoint &&  other)
defaultnoexcept

Overwrite this object with the value of another SpherePoint.

As operator=(SpherePoint const&), except that other may be left in an unspecified but valid state.

◆ operator=() [2/2]

SpherePoint & lsst::geom::SpherePoint::operator= ( SpherePoint const &  other)
defaultnoexcept

Overwrite this object with the value of another SpherePoint.

This is the only method that can alter the state of a SpherePoint after its construction, and is provided to allow in-place replacement of SpherePoints where swapping is not possible.

Parameters
otherThe object with which to overwrite this one.
Returns
a reference to this object.
Exception Safety
Shall not throw exceptions.

◆ operator==()

bool lsst::geom::SpherePoint::operator== ( SpherePoint const &  other) const
noexcept

true if two points have the same longitude and latitude.

Parameters
otherthe point to test for equality
Returns
true if this point has exactly the same values of getLongitude() and getLatitude() as other, false otherwise
Exception Safety
Shall not throw exceptions.
Note
Two points at the same pole will compare unequal if they have different longitudes, despite representing the same point on the unit sphere. This is important because the behavior of offset and bearingTo depend on longitude, even at the pole.
Warning
Points whose getLongitude(), getLatitude(), or getVector() methods return NaN shall not compare equal to any point, including themselves. This may break algorithms that assume object equality is reflexive; use isFinite() to filter objects if necessary.

Definition at line 146 of file SpherePoint.cc.

◆ operator[]()

Angle lsst::geom::SpherePoint::operator[] ( size_t  index) const

Longitude and latitude by index.

Parameters
indexthe index of the spherical coordinate to return. Must be either 0 or 1.
Returns
getLongitude() if index = 0, or getLatitude() if index = 1
Exceptions
pex::exceptions::OutOfRangeErrorThrown if index is neither 0 nor 1.
Exception Safety
Provides strong exception guarantee.

Definition at line 133 of file SpherePoint.cc.

◆ rotated()

SpherePoint lsst::geom::SpherePoint::rotated ( SpherePoint const &  axis,
Angle const &  amount 
) const
noexcept

Return a point rotated from this one around an axis.

Parameters
axisa point defining the north pole of the rotation axis.
amountthe amount of rotation, where positive values represent right-handed rotations around axis.
Returns
a new point created by rotating this point. If the new point is at the pole then its longitude will be 0.
Exception Safety
Shall not throw exceptions.

Definition at line 178 of file SpherePoint.cc.

◆ separation()

Angle lsst::geom::SpherePoint::separation ( SpherePoint const &  other) const
noexcept

Angular distance between two points.

Parameters
otherthe point to which to measure the separation
Returns
the length of the shortest (great circle) arc between the two points. Shall not be negative.
Exception Safety
Shall not throw exceptions.

Definition at line 173 of file SpherePoint.cc.

Friends And Related Function Documentation

◆ operator<<()

std::ostream & operator<< ( std::ostream os,
SpherePoint const &  point 
)
related

Print the value of a point to a stream.

The exact details of the string representation are unspecified and subject to change, but the following may be regarded as typical: "(10.543250, +32.830583)".

Parameters
osthe stream to which to print point
pointthe point to print to the stream
Returns
a reference to os
Exceptions
pex::exceptions::std::ostream::failureThrown if an I/O state flag was set that was registered with os.exceptions(). See the documentation of std::ostream for more details.
Exception Safety
Provides basic exception guarantee.

Definition at line 253 of file SpherePoint.cc.


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