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.

	SpherePoint (double longitude, double latitude, AngleUnit units)
	Construct a SpherePoint from double longitude and latitude.

	SpherePoint (sphgeom::Vector3d const &vector)
	Construct a SpherePoint from a vector representing a direction.

	SpherePoint (sphgeom::LonLat const &lonLat) noexcept
	Construct a SpherePoint from a sphgeom::LonLat.

	SpherePoint () noexcept
	Construct a SpherePoint with "nan" for longitude and latitude.

	SpherePoint (SpherePoint const &other) noexcept
	Create a copy of a SpherePoint.

	SpherePoint (SpherePoint &&other) noexcept
	Create a copy of a SpherePoint.

	~SpherePoint () noexcept

SpherePoint &	operator= (SpherePoint const &other) noexcept
	Overwrite this object with the value of another SpherePoint.

SpherePoint &	operator= (SpherePoint &&other) noexcept
	Overwrite this object with the value of another SpherePoint.

	operator sphgeom::LonLat () const noexcept
	Make SpherePoint implicitly convertible to LonLat.

Angle	getLongitude () const noexcept
	The longitude of this point.

Angle	getRa () const noexcept
	Synonym for getLongitude.

Angle	getLatitude () const noexcept
	The latitude of this point.

Angle	getDec () const noexcept
	Synonym for getLatitude.

Point2D	getPosition (AngleUnit unit) const noexcept
	Return longitude, latitude as a Point2D object.

sphgeom::UnitVector3d	getVector () const noexcept
	A unit vector representation of this point.

Angle	operator[] (size_t index) const
	Longitude and latitude by index.

bool	atPole () const noexcept
	`true` if this point is either coordinate pole.

bool	isFinite () const noexcept
	`true` if this point is a well-defined position.

bool	operator== (SpherePoint const &other) const noexcept
	`true` if two points have the same longitude and latitude.

bool	operator!= (SpherePoint const &other) const noexcept
	`false` if two points represent the same position.

std::size_t	hash_value () const noexcept
	Return a hash of this object.

Angle	bearingTo (SpherePoint const &other) const
	Orientation at this point of the great circle arc to another point.

Angle	separation (SpherePoint const &other) const noexcept
	Angular distance between two points.

SpherePoint	rotated (SpherePoint const &axis, Angle const &amount) const noexcept
	Return a point rotated from this one around an axis.

SpherePoint	offset (Angle const &bearing, Angle const &amount) const
	Return a point offset from this one along a great circle.

std::pair< Angle, Angle >	getTangentPlaneOffset (SpherePoint const &other) const
	Get the offset from a tangent plane centered at this point to another point.

Related Symbols
(Note that these are not member symbols.)
std::ostream &	operator<< (std::ostream &os, SpherePoint const &point)
	Print the value of a point to a stream.

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

longitude	The longitude of the point. `+/-inf` is treated as `nan` (because longitude is wrapped to a standard range and infinity cannot be wrapped)
latitude	The latitude of the point. Must be in the interval [-π/2, π/2] radians.

Exceptions

pex::exceptions::InvalidParameterError Thrown 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

longitude	The longitude of the point. `+/-inf` is treated as `nan` (because longitude is wrapped to a standard range and infinity cannot be wrapped)
latitude	The latitude of the point. Must be in the interval [-π/2, π/2] radians.
units	The units of longitude and latitude

Exceptions

pex::exceptions::InvalidParameterError Thrown 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

vector A 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::InvalidParameterError Thrown 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

lonLat The 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

other The 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

other the 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] unit Units 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] other Coordinate 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

bearing	the direction in which to move this point, following the conventions described in bearingTo.
amount	the 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

other The 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

other the 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

index the 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::OutOfRangeError Thrown 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

axis	a point defining the north pole of the rotation axis.
amount	the 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

other the 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 Symbol Documentation

◆ operator<<()

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

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

os	the stream to which to print `point`
point	the point to print to the stream

Returns: a reference to os

Exceptions

pex::exceptions::std::ostream::failure Thrown 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:

include/lsst/geom/SpherePoint.h
src/SpherePoint.cc

Public Member Functions

Related Symbols

Detailed Description

Constructor & Destructor Documentation

◆ SpherePoint() [1/7]

◆ SpherePoint() [2/7]

◆ SpherePoint() [3/7]

◆ SpherePoint() [4/7]

◆ SpherePoint() [5/7]

◆ SpherePoint() [6/7]

◆ SpherePoint() [7/7]

◆ ~SpherePoint()

Member Function Documentation

◆ atPole()

◆ bearingTo()

◆ getDec()

◆ getLatitude()

◆ getLongitude()

◆ getPosition()

◆ getRa()

◆ getTangentPlaneOffset()

◆ getVector()

◆ hash_value()

◆ isFinite()

◆ offset()

◆ operator sphgeom::LonLat()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]()

◆ rotated()

◆ separation()

Friends And Related Symbol Documentation

◆ operator<<()