Gazebo Math

API Reference

9.0.0~pre1

Convert spherical coordinates for planetary surfaces. More...

#include <SphericalCoordinates.hh>

Public Types

enum  CoordinateType { SPHERICAL = 1 , ECEF = 2 , GLOBAL = 3 , LOCAL = 4 }
 Unique identifiers for coordinate types. More...
 
enum  SurfaceType { EARTH_WGS84 = 1 , MOON_SCS = 2 , CUSTOM_SURFACE = 10 }
 Unique identifiers for planetary surface models. More...
 

Public Member Functions

 SphericalCoordinates ()
 Constructor.
 
 SphericalCoordinates (const SurfaceType _type)
 Constructor with surface type input.
 
 SphericalCoordinates (const SurfaceType _type, const Angle &_latitude, const Angle &_longitude, const double _elevation, const Angle &_heading)
 Constructor with surface type, angle, and elevation inputs.
 
 SphericalCoordinates (const SurfaceType _type, const double _axisEquatorial, const double _axisPolar)
 Constructor with surface type input and properties input. To be used for CUSTOM_SURFACE.
 
double DistanceBetweenPoints (const Angle &_latA, const Angle &_lonA, const Angle &_latB, const Angle &_lonB)
 Get the distance between two points expressed in geographic latitude and longitude. It assumes that both points are at sea level. Example: _latA = 38.0016667 and _lonA = -123.0016667) represents the point with latitude 38d 0'6.00"N and longitude 123d 0'6.00"W.
 
double ElevationReference () const
 Get reference elevation in meters.
 
std::optional< math::CoordinateVector3GlobalFromLocalVelocity (const CoordinateVector3 &_xyz) const
 Convert a Cartesian velocity vector in the local frame to a global Cartesian frame with components East, North, Up. This is a wrapper around VelocityTransform(_xyz, LOCAL, GLOBAL)
 
Angle HeadingOffset () const
 Get heading offset for the reference frame, expressed as angle from East to x-axis, or equivalently from North to y-axis.
 
Angle LatitudeReference () const
 Get reference geodetic latitude.
 
std::optional< math::CoordinateVector3LocalFromGlobalVelocity (const CoordinateVector3 &_xyz) const
 Convert a Cartesian velocity vector with components East, North, Up to a local cartesian frame vector XYZ. This is a wrapper around VelocityTransform(_xyz, GLOBAL, LOCAL)
 
std::optional< math::CoordinateVector3LocalFromSphericalPosition (const CoordinateVector3 &_latLonEle) const
 Convert a geodetic position vector to Cartesian coordinates. This performs a PositionTransform from SPHERICAL to LOCAL.
 
Angle LongitudeReference () const
 Get reference longitude.
 
bool operator!= (const SphericalCoordinates &_sc) const
 Inequality.
 
bool operator== (const SphericalCoordinates &_sc) const
 Equality operator, result = this == _sc.
 
std::optional< CoordinateVector3PositionTransform (const CoordinateVector3 &_pos, const CoordinateType &_in, const CoordinateType &_out) const
 Convert between positions in SPHERICAL/ECEF/LOCAL/GLOBAL frame using the cached reference point.
 
void SetElevationReference (const double _elevation)
 Set reference elevation above sea level in meters.
 
void SetHeadingOffset (const Angle &_angle)
 Set heading angle offset for the frame.
 
void SetLatitudeReference (const Angle &_angle)
 Set reference geodetic latitude.
 
void SetLongitudeReference (const Angle &_angle)
 Set reference longitude.
 
void SetSurface (const SurfaceType &_type)
 Set SurfaceType for planetary surface model.
 
void SetSurface (const SurfaceType &_type, const double _axisEquatorial, const double _axisPolar)
 Set SurfaceType for planetary surface model with custom ellipsoid properties.
 
std::optional< math::CoordinateVector3SphericalFromLocalPosition (const CoordinateVector3 &_xyz) const
 Convert a Cartesian position vector to geodetic coordinates. This performs a PositionTransform from LOCAL to SPHERICAL.
 
SurfaceType Surface () const
 Get SurfaceType currently in use.
 
double SurfaceAxisEquatorial () const
 Get the major axis of the surface.
 
double SurfaceAxisPolar () const
 Get the minor axis of the surface.
 
double SurfaceFlattening () const
 Get the flattening of the surface.
 
double SurfaceRadius () const
 Get the radius of the surface.
 
void UpdateTransformationMatrix ()
 Update coordinate transformation matrix with reference location.
 
std::optional< CoordinateVector3VelocityTransform (const CoordinateVector3 &_vel, const CoordinateType &_in, const CoordinateType &_out) const
 Convert between velocity in ECEF/LOCAL/GLOBAL frame.
 

Static Public Member Functions

static SurfaceType Convert (const std::string &_str)
 Convert a string to a SurfaceType. Allowed values: ["EARTH_WGS84"].
 
static std::string Convert (SurfaceType _type)
 Convert a SurfaceType to a string.
 
static double DistanceWGS84 (const Angle &_latA, const Angle &_lonA, const Angle &_latB, const Angle &_lonB)
 Get the distance between two points expressed in geographic latitude and longitude. It assumes that both points are at sea level. Example: _latA = 38.0016667 and _lonA = -123.0016667) represents the point with latitude 38d 0'6.00"N and longitude 123d 0'6.00"W. This method assumes that the surface model is EARTH_WGS84.
 

Detailed Description

Convert spherical coordinates for planetary surfaces.

Member Enumeration Documentation

◆ CoordinateType

Unique identifiers for coordinate types.

Enumerator
SPHERICAL 

Latitude, Longitude and Altitude by SurfaceType.

ECEF 

Earth centered, earth fixed Cartesian.

GLOBAL 

Local tangent plane (East, North, Up)

LOCAL 

Heading-adjusted tangent plane (X, Y, Z)

◆ SurfaceType

Unique identifiers for planetary surface models.

Enumerator
EARTH_WGS84 

Model of reference ellipsoid for earth, based on WGS 84 standard. see wikipedia: World_Geodetic_System.

MOON_SCS 

Model of the moon, based on the Selenographic coordinate system, see wikipedia: Selenographic Coordinate System.

CUSTOM_SURFACE 

Custom surface type.

Constructor & Destructor Documentation

◆ SphericalCoordinates() [1/4]

Constructor.

◆ SphericalCoordinates() [2/4]

SphericalCoordinates ( const SurfaceType  _type)
explicit

Constructor with surface type input.

Parameters
[in]_typeSurfaceType specification.

◆ SphericalCoordinates() [3/4]

SphericalCoordinates ( const SurfaceType  _type,
const double  _axisEquatorial,
const double  _axisPolar 
)

Constructor with surface type input and properties input. To be used for CUSTOM_SURFACE.

Parameters
[in]_typeSurfaceType specification.
[in]_axisEquatorialSemi major axis of the surface.
[in]_axisPolarSemi minor axis of the surface.

◆ SphericalCoordinates() [4/4]

SphericalCoordinates ( const SurfaceType  _type,
const Angle _latitude,
const Angle _longitude,
const double  _elevation,
const Angle _heading 
)

Constructor with surface type, angle, and elevation inputs.

Parameters
[in]_typeSurfaceType specification.
[in]_latitudeReference latitude.
[in]_longitudeReference longitude.
[in]_elevationReference elevation.
[in]_headingHeading offset.

Member Function Documentation

◆ Convert() [1/2]

static SurfaceType Convert ( const std::string _str)
static

Convert a string to a SurfaceType. Allowed values: ["EARTH_WGS84"].

Parameters
[in]_strString to convert.
Returns
Conversion to SurfaceType.

◆ Convert() [2/2]

static std::string Convert ( SurfaceType  _type)
static

Convert a SurfaceType to a string.

Parameters
[in]_typeSurface type
Returns
Type as string

◆ DistanceBetweenPoints()

double DistanceBetweenPoints ( const Angle _latA,
const Angle _lonA,
const Angle _latB,
const Angle _lonB 
)

Get the distance between two points expressed in geographic latitude and longitude. It assumes that both points are at sea level. Example: _latA = 38.0016667 and _lonA = -123.0016667) represents the point with latitude 38d 0'6.00"N and longitude 123d 0'6.00"W.

Parameters
[in]_latALatitude of point A.
[in]_lonALongitude of point A.
[in]_latBLatitude of point B.
[in]_lonBLongitude of point B.
Returns
Distance in meters.

◆ DistanceWGS84()

static double DistanceWGS84 ( const Angle _latA,
const Angle _lonA,
const Angle _latB,
const Angle _lonB 
)
static

Get the distance between two points expressed in geographic latitude and longitude. It assumes that both points are at sea level. Example: _latA = 38.0016667 and _lonA = -123.0016667) represents the point with latitude 38d 0'6.00"N and longitude 123d 0'6.00"W. This method assumes that the surface model is EARTH_WGS84.

Parameters
[in]_latALatitude of point A.
[in]_lonALongitude of point A.
[in]_latBLatitude of point B.
[in]_lonBLongitude of point B.
Returns
Distance in meters.

◆ ElevationReference()

double ElevationReference ( ) const

Get reference elevation in meters.

Returns
Reference elevation.

◆ GlobalFromLocalVelocity()

std::optional< math::CoordinateVector3 > GlobalFromLocalVelocity ( const CoordinateVector3 _xyz) const

Convert a Cartesian velocity vector in the local frame to a global Cartesian frame with components East, North, Up. This is a wrapper around VelocityTransform(_xyz, LOCAL, GLOBAL)

Parameters
[in]_xyzCartesian velocity vector in the heading-adjusted world frame.
Returns
Rotated vector with components (x,y,z): (East, North, Up).

◆ HeadingOffset()

Angle HeadingOffset ( ) const

Get heading offset for the reference frame, expressed as angle from East to x-axis, or equivalently from North to y-axis.

Returns
Heading offset of reference frame.

◆ LatitudeReference()

Angle LatitudeReference ( ) const

Get reference geodetic latitude.

Returns
Reference geodetic latitude.

◆ LocalFromGlobalVelocity()

std::optional< math::CoordinateVector3 > LocalFromGlobalVelocity ( const CoordinateVector3 _xyz) const

Convert a Cartesian velocity vector with components East, North, Up to a local cartesian frame vector XYZ. This is a wrapper around VelocityTransform(_xyz, GLOBAL, LOCAL)

Parameters
[in]_xyzVector with components (x,y,z): (East, North, Up).
Returns
Cartesian vector in the world frame.

◆ LocalFromSphericalPosition()

std::optional< math::CoordinateVector3 > LocalFromSphericalPosition ( const CoordinateVector3 _latLonEle) const

Convert a geodetic position vector to Cartesian coordinates. This performs a PositionTransform from SPHERICAL to LOCAL.

Parameters
[in]_latLonEleGeodetic position in the planetary frame of reference. X: latitude, Y: longitude, Z: altitude.
Returns
Cartesian position vector in the heading-adjusted world frame.

◆ LongitudeReference()

Angle LongitudeReference ( ) const

Get reference longitude.

Returns
Reference longitude.

◆ operator!=()

bool operator!= ( const SphericalCoordinates _sc) const

Inequality.

Parameters
[in]_scSpherical coordinates to check for inequality
Returns
true if this != _sc

◆ operator==()

Equality operator, result = this == _sc.

Parameters
[in]_scSpherical coordinates to check for equality
Returns
true if this == _sc

◆ PositionTransform()

std::optional< CoordinateVector3 > PositionTransform ( const CoordinateVector3 _pos,
const CoordinateType _in,
const CoordinateType _out 
) const

Convert between positions in SPHERICAL/ECEF/LOCAL/GLOBAL frame using the cached reference point.

Parameters
[in]_posPosition vector in frame defined by parameter _in
[in]_inCoordinateType for input
[in]_outCoordinateType for output
Returns
Transformed coordinates (if the transformation succeeded).

◆ SetElevationReference()

void SetElevationReference ( const double  _elevation)

Set reference elevation above sea level in meters.

Parameters
[in]_elevationReference elevation.

◆ SetHeadingOffset()

void SetHeadingOffset ( const Angle _angle)

Set heading angle offset for the frame.

Parameters
[in]_angleHeading offset for the frame.

◆ SetLatitudeReference()

void SetLatitudeReference ( const Angle _angle)

Set reference geodetic latitude.

Parameters
[in]_angleReference geodetic latitude.

◆ SetLongitudeReference()

void SetLongitudeReference ( const Angle _angle)

Set reference longitude.

Parameters
[in]_angleReference longitude.

◆ SetSurface() [1/2]

void SetSurface ( const SurfaceType _type)

Set SurfaceType for planetary surface model.

Parameters
[in]_typeSurfaceType value.

◆ SetSurface() [2/2]

void SetSurface ( const SurfaceType _type,
const double  _axisEquatorial,
const double  _axisPolar 
)

Set SurfaceType for planetary surface model with custom ellipsoid properties.

Parameters
[in]_typeSurfaceType value.
[in]_axisEquatorialEquatorial axis of the surface.
[in]_axisPolarPolar axis of the surface.

◆ SphericalFromLocalPosition()

std::optional< math::CoordinateVector3 > SphericalFromLocalPosition ( const CoordinateVector3 _xyz) const

Convert a Cartesian position vector to geodetic coordinates. This performs a PositionTransform from LOCAL to SPHERICAL.

Parameters
[in]_xyzCartesian position vector in the heading-adjusted world frame.
Returns
Coordinates: geodetic latitude, longitude, altitude above sea level.

◆ Surface()

SurfaceType Surface ( ) const

Get SurfaceType currently in use.

Returns
Current SurfaceType value.

◆ SurfaceAxisEquatorial()

double SurfaceAxisEquatorial ( ) const

Get the major axis of the surface.

Returns
Equatorial axis of the surface in use.

◆ SurfaceAxisPolar()

double SurfaceAxisPolar ( ) const

Get the minor axis of the surface.

Returns
Polar axis of the surface in use.

◆ SurfaceFlattening()

double SurfaceFlattening ( ) const

Get the flattening of the surface.

Returns
Flattening parameter of the surface in use.

◆ SurfaceRadius()

double SurfaceRadius ( ) const

Get the radius of the surface.

Returns
radius of the surface in use.

◆ UpdateTransformationMatrix()

void UpdateTransformationMatrix ( )

Update coordinate transformation matrix with reference location.

◆ VelocityTransform()

std::optional< CoordinateVector3 > VelocityTransform ( const CoordinateVector3 _vel,
const CoordinateType _in,
const CoordinateType _out 
) const

Convert between velocity in ECEF/LOCAL/GLOBAL frame.

Note
Spherical coordinates are not supported.
Parameters
[in]_velVelocity vector in frame defined by parameter _in
[in]_inCoordinateType for input
[in]_outCoordinateType for output
Returns
Transformed velocity vector (if the transformation succeeded).

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