lsst::geom::SpherePoint Class Reference

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
SpherePoint &	operator= (SpherePoint const &other) noexcept
	Overwrite this object with the value of another SpherePoint. More...
SpherePoint &	operator= (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, Angle >	getTangentPlaneOffset (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::ostream &	operator<< (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

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.

        : _longitude(longitude.wrap().asRadians()), _latitude(latitude.asRadians()) {
    if (fabs(_latitude) > HALFPI) {
        throw pexExcept::InvalidParameterError("Angle " + to_string(latitude.asDegrees()) +
                                               " is not a valid latitude.");
    }
}

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(longitude * units, latitude * units) {}

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.

                                                      {
    // sphgeom Vector3d has its own normalization,
    // but its behavior is not documented for non-finite values
    double norm = vector.getNorm();
    if (norm <= 0.0) {
        stringstream buffer;
        buffer << "Vector " << vector << " has zero norm and cannot be normalized.";
        throw pexExcept::InvalidParameterError(buffer.str());
    }
    // To avoid unexpected behavior from mixing finite elements and infinite norm
    if (!isfinite(norm)) {
        norm = NAN;
    }
    auto unitVector =
            sphgeom::UnitVector3d::fromNormalized(vector.x() / norm, vector.y() / norm, vector.z() / norm);
    _set(unitVector);
}

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(lonLat.getLon().asRadians(), lonLat.getLat().asRadians(), radians) {}

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.

: _longitude(nan("")), _latitude(nan("")) {}

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.

                                 {
        // Unit tests indicate we don't need to worry about epsilon-errors, in that
        // Objects constructed from lat=90*degrees, <0,0,1>, etc. all have atPole() = true.
        return fabs(_latitude) >= HALFPI;
    }

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.

                                                           {
    Angle const deltaLon = other.getLongitude() - this->getLongitude();
 
    double const sinDelta1 = sin(getLatitude().asRadians());
    double const sinDelta2 = sin(other.getLatitude().asRadians());
    double const cosDelta1 = cos(getLatitude().asRadians());
    double const cosDelta2 = cos(other.getLatitude().asRadians());
 
    // Adapted from http://www.movable-type.co.uk/scripts/latlong.html
    double const y = sin(deltaLon) * cosDelta2;
    double const x = cosDelta1 * sinDelta2 - sinDelta1 * cosDelta2 * cos(deltaLon);
    return (90.0 * degrees - atan2(y, x) * radians).wrap();
}

getDec()

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

inlinenoexcept

Synonym for getLatitude.

Definition at line 193 of file SpherePoint.h.

{ return _latitude * radians; };

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.

{ return _latitude * radians; };

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.

{ return _longitude * radians; };

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.

                                                              {
    return Point2D(getLongitude().asAngularUnits(unit), getLatitude().asAngularUnits(unit));
}

getRa()

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

inlinenoexcept

Synonym for getLongitude.

Definition at line 181 of file SpherePoint.h.

{ return _longitude * radians; };

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.

                                                                                               {
    geom::Angle const alpha1 = this->getLongitude();
    geom::Angle const delta1 = this->getLatitude();
    geom::Angle const alpha2 = other.getLongitude();
    geom::Angle const delta2 = other.getLatitude();
 
    // Compute the projection of "other" on a tangent plane centered at this point
    double const sinDelta1 = std::sin(delta1);
    double const cosDelta1 = std::cos(delta1);
    double const sinDelta2 = std::sin(delta2);
    double const cosDelta2 = std::cos(delta2);
    double const cosAlphaDiff = std::cos(alpha2 - alpha1);
    double const sinAlphaDiff = std::sin(alpha2 - alpha1);
 
    double const div = cosDelta1 * cosAlphaDiff * cosDelta2 + sinDelta1 * sinDelta2;
    double const xi = cosDelta1 * sinAlphaDiff / div;
    double const eta = (cosDelta1 * cosAlphaDiff * sinDelta2 - sinDelta1 * cosDelta2) / div;
 
    return std::make_pair(xi * geom::radians, eta * geom::radians);
}

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.

                                                          {
    return sphgeom::UnitVector3d::fromNormalized(cos(_longitude) * cos(_latitude),
                                                 sin(_longitude) * cos(_latitude), sin(_latitude));
}

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.

                                                 {
    // Completely arbitrary seed
    return utils::hashCombine(17, _longitude, _latitude);
}

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.

{ return isfinite(_longitude) && isfinite(_latitude); }

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.

                                                                               {
    double const phi = bearing.asRadians();
 
    // let v = vector in the direction bearing points (tangent to surface of sphere)
    // To do the rotation, use rotated() method.
    // - must provide an axis of rotation: take the cross product r x v to get that axis (pole)
 
    auto r = getVector();
 
    // Get the vector v:
    //  let u = unit vector lying on a parallel of declination
    //  let w = unit vector along line of longitude = r x u
    // the vector v must satisfy the following:
    //  r . v = 0
    //  u . v = cos(phi)
    //  w . v = sin(phi)
 
    // v is a linear combination of u and w
    // v = cos(phi)*u + sin(phi)*w
    sphgeom::Vector3d const u(-sin(_longitude), cos(_longitude), 0.0);
    auto w = r.cross(u);
    auto v = cos(phi) * u + sin(phi) * w;
 
    // take r x v to get the axis
    SpherePoint axis = SpherePoint(r.cross(v));
 
    return rotated(axis, amount);
}

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.

                                                   {
    return sphgeom::LonLat::fromRadians(getLongitude().asRadians(), getLatitude().asRadians());
}

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.

{ return !(*this == other); }

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.

                                                                    {
    // Deliberate override of Style Guide 5-12
    // Approximate FP comparison would make object equality intransitive
    return _longitude == other._longitude && _latitude == other._latitude;
}

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.

                                                {
    switch (index) {
        case 0:
            return getLongitude();
        case 1:
            return getLatitude();
        default:
            throw pexExcept::OutOfRangeError("Index " + to_string(index) + " must be 0 or 1.");
    }
}

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.

                                                                                            {
    auto const rotation = Eigen::AngleAxisd(amount.asRadians(), asEigen(axis.getVector())).matrix();
    auto const x = asEigen(getVector());
    auto const xprime = rotation * x;
    return SpherePoint(sphgeom::Vector3d(xprime[0], xprime[1], xprime[2]));
}

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.

                                                                     {
    return haversine(getLongitude() - other.getLongitude(), getLatitude() - other.getLatitude(),
                     cos(getLatitude().asRadians()), cos(other.getLatitude().asRadians()));
}

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

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.

                                                           {
    // Can't provide atomic guarantee anyway for I/O, so ok to set ostream states here.
    auto oldFlags = os.setf(ostream::fixed);
    // 10 digits of precision for a value in degrees is about 1 milliarcsecond
    auto oldPrecision = os.precision(10);
 
    os << "(" << point.getLongitude().asDegrees() << ", ";
    os.setf(ostream::showpos);
    os << point.getLatitude().asDegrees() << ")";
 
    os.flags(oldFlags);
    os.precision(oldPrecision);
    return os;
}

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/geom/22.0.1-6-g8d3140d+720564cf76/include/lsst/geom/SpherePoint.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/geom/22.0.1-6-g8d3140d+720564cf76/src/SpherePoint.cc