Class inertialsim::geodesy::Coordinates¶

ClassList > inertialsim > geodesy > Coordinates

3-dimensional coordinates with respect to Earth. More...

#include <coordinates.h>

Public Functions¶

Type	Name
Vector3D	AsEcef () const Return ECEF coordinates.
Array3D	AsEllipsoidalHarmonic () const Return ellipsoidal harmonic coordinates.
Array3D	AsGeodetic () const Return geodetic coordinates.
Array3D	AsSpherical () const Return spherical coordinates.
Vector3D	AsTopocentric (const std::optional< TopocentricDatum > & datum=std::nullopt) const Return topocentric coordinates.
Coordinates	Interpolate (const Timestamps & time, geometry::Interpolator method=geometry::Interpolator::LINEAR) const Interpolate coordinates at requested times.
geometry::RigidTransform	RigidTransform (CoordinateSystem from_coordinates, CoordinateSystem to_coordinates, const std::optional< TopocentricDatum > & from_topocentric_datum=std::nullopt, const std::optional< TopocentricDatum > & to_topocentric_datum=std::nullopt) const Return rigid transform between coordinate systems.
Coordinates	Slice (int start, int end) const Get a slice of coordinates.
Vector3D	TimeDerivative (int order=1, int accuracy=4) const Numerical time derivative in current coordinate system.
CoordinateSystem	coordinate_system () const The coordinate system of the stored coordinates.
const Array3D &	coordinates () const Array of raw coordinates.
std::optional< GeodeticDatum >	geodetic_datum () const The geodetic datum associated with the stored coordinates.
int	num_coordinates () const The number of coordinates stored in the instance.
Coordinates	operator[] (int index) const Get a single coordinate by index.
std::optional< Timestamps >	time () const Array of times corresponding to each coordinate.
std::optional< TopocentricDatum >	topocentric_datum () const The topocentric datum associated with the stored coordinates.

Public Static Functions¶

Type	Name
Coordinates	FromEcef (const Vector3D & xyz, const GeodeticDatum & datum=WGS84, const std::optional< Timestamps > & time=std::nullopt) Construct from ECEF coordinates.
Coordinates	FromEllipsoidalHarmonic (const Array3D & upl, const GeodeticDatum & datum=WGS84, const std::optional< Timestamps > & time=std::nullopt) Construct from ellipsoidal harmonic coordinates.
Coordinates	FromGeodetic (const Array3D & lla, const GeodeticDatum & datum=WGS84, const std::optional< Timestamps > & time=std::nullopt) Construct from geodetic coordinates.
Coordinates	FromInertial (const Vector3D & xyz, const std::optional< Timestamps > & time=std::nullopt) Construct from inertial coordinates.
Coordinates	FromLocal (const Vector3D & position, const std::optional< Timestamps > & time=std::nullopt) Construct from simple local coordinates.
Coordinates	FromLocal (const Vector3D & position, const Array3D & frame_origin, const geometry::Rotation & frame_rotation, const LocalDatum & local_datum, const std::optional< Timestamps > & time=std::nullopt) Construct from local coordinates with geodetic frame.
Coordinates	FromSpherical (const Array3D & rpl, const GeodeticDatum & datum=WGS84, const std::optional< Timestamps > & time=std::nullopt) Construct from spherical coordinates.
Coordinates	FromTopocentric (const Vector3D & ned, const TopocentricDatum & datum, const std::optional< Timestamps > & time=std::nullopt) Construct from topocentric coordinates.

Protected Functions¶

Type	Name
	Coordinates () = default Default constructor.
	Coordinates (const Array3D & coordinates, CoordinateSystem coordinate_system, const std::optional< GeodeticDatum > & geodetic_datum=std::nullopt, const std::optional< TopocentricDatum > & topocentric_datum=std::nullopt, const std::optional< Timestamps > & time=std::nullopt) Construct with raw data.

Detailed Description¶

Geodetic coordinates describe the location of points relative to the Earth. In contrast, see geometry::Vector for basic geometric coordinates.

Use the From* methods to construct an instance. Do not initialize an instance directly using the protected constructor.

Coordinate conventions

There are a variety of coordinate conventions and they are a common source of errors. Because many of these conventions cannot be automatically validated, users must be aware of them and manage interfaces with other software accordingly. InertialSim conventions are documented in each method.

Coordinate system definition

Consistent with inertial navigation practice, a coordinate system is defined as an axis system (an orthogonal Cartesian basis) and an origin point relative to Earth.

See also: geometry::Vector for basic geometric coordinates

See also: GlobalPose for full pose (attitude + position + velocity)

Public Functions Documentation¶

function AsEcef¶

Return ECEF coordinates.

Vector3D inertialsim::geodesy::Coordinates::AsEcef () const

Converts the stored coordinates to ECEF (Earth-Centered, Earth-Fixed) format. See FromEcef() for additional documentation regarding ECEF coordinate conventions.

Returns:

ECEF coordinates (meters).

Exception:

std::invalid_argument if coordinates cannot be converted to ECEF.

function AsEllipsoidalHarmonic¶

Return ellipsoidal harmonic coordinates.

Array3D inertialsim::geodesy::Coordinates::AsEllipsoidalHarmonic () const

Converts the stored coordinates to ellipsoidal harmonic format. See FromEllipsoidalHarmonic() for additional documentation regarding ellipsoidal harmonic coordinate conventions.

Returns:

Ellipsoidal harmonic coordinates (semi-minor axis, polar angle, longitude). Semi-minor axis in meters, angles in radians.

Exception:

std::invalid_argument if geodetic datum is not set or coordinates cannot be converted.

function AsGeodetic¶

Return geodetic coordinates.

Array3D inertialsim::geodesy::Coordinates::AsGeodetic () const

Converts the stored coordinates to geodetic format (latitude, longitude, altitude). See FromGeodetic() for additional documentation regarding geodetic coordinate conventions.

Returns:

Geodetic coordinates (latitude, longitude, altitude). Latitude and longitude in radians, altitude in meters.

Exception:

std::invalid_argument if geodetic datum is not set or coordinates cannot be converted.

function AsSpherical¶

Return spherical coordinates.

Array3D inertialsim::geodesy::Coordinates::AsSpherical () const

Converts the stored coordinates to geocentric spherical format. See FromSpherical() for additional documentation regarding spherical coordinate conventions.

Returns:

Spherical coordinates (radius, polar angle, longitude). Radius in meters, angles in radians.

Exception:

std::invalid_argument if coordinates cannot be converted.

function AsTopocentric¶

Return topocentric coordinates.

Vector3D inertialsim::geodesy::Coordinates::AsTopocentric (
    const std::optional< TopocentricDatum > & datum=std::nullopt
) const

Converts the stored coordinates to topocentric format. If a topocentric datum is provided, it will be used. If no datum is provided and the coordinates were initialized with a topocentric datum, it will be used. Otherwise an exception is thrown.

See FromTopocentric() for additional documentation regarding topocentric coordinate conventions.

Parameters:

datum Optional topocentric datum. If not provided, uses the datum from construction.

Returns:

Topocentric coordinates (NED or ENU, meters).

Exception:

std::invalid_argument if topocentric datum is not available or coordinates cannot be converted.

function Interpolate¶

Interpolate coordinates at requested times.

Coordinates inertialsim::geodesy::Coordinates::Interpolate (
    const  Timestamps & time,
    geometry::Interpolator method=geometry::Interpolator::LINEAR
) const

Interpolates coordinates at the specified times. The time input can be any array of times or indices consistent with those used to construct the instance. Values outside the range of the original data will not be extrapolated but will return the end-points instead.

For curvilinear coordinate systems (geodetic, spherical, ellipsoidal harmonic), interpolation is performed in ECEF coordinates and converted back.

Example

A Coordinates instance constructed with 2 coordinates at time indices [0, 1] can be interpolated for any set of values in [0, 1], e.g., [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Cubic Spline Continuity

The CUBIC method uses a Hermite spline technique. The resulting interpolant will pass through each of the original data points with C1 continuity.

Parameters:

time Array of unique, strictly increasing times (or indices) corresponding to each desired output.
method Interpolation method to use (LINEAR or CUBIC).

Returns:

New Coordinates instance with interpolated values.

Exception:

std::invalid_argument if time is not set or method is invalid.

function RigidTransform¶

Return rigid transform between coordinate systems.

geometry::RigidTransform inertialsim::geodesy::Coordinates::RigidTransform (
    CoordinateSystem from_coordinates,
    CoordinateSystem to_coordinates,
    const std::optional< TopocentricDatum > & from_topocentric_datum=std::nullopt,
    const std::optional< TopocentricDatum > & to_topocentric_datum=std::nullopt
) const

Returns the rigid transform between two coordinate systems. The rotation component represents the rotation between the basis vectors of each coordinate system. For curvilinear coordinates (geodetic, spherical, ellipsoidal harmonic), these are the local basis vectors. The translation component is the vector difference between the origin of each coordinate system.

For converting positions (points), prefer to use the From* and As* methods directly. This function is helpful for converting other vectors of interest between coordinate systems (gravity, velocity, etc.).

For transforms involving topocentric coordinate systems, if a topocentric datum is passed in, it will be used. If no datum is passed in and the coordinates were initialized with a topocentric datum, it will be used. Otherwise an exception will be thrown.

Geodetic local basis

By convention, geodetic coordinates are specified with a latitude, longitude, altitude tuple. The local basis of these coordinates is a left-handed north-east-up frame (latitude is positive northward, longitude is positive eastward, altitude is positive up). The transform returned by this function must be right-handed, so if geodetic coordinates are requested in either input, a north-east-down local basis will be used. If necessary, users should manually invert the sign of the z-axis component after applying the transform.

Passive transform convention

The transform returned by this function uses the passive convention, which is typical for coordinate transform operations. See geometry::RigidTransform for more details.

Parameters:

from_coordinates The source coordinate system (one of: GEODETIC, ECEF, TOPOCENTRIC, SPHERICAL, or ELLIPSOIDAL_HARMONIC).
to_coordinates The destination coordinate system (one of: GEODETIC, ECEF, TOPOCENTRIC, SPHERICAL, or ELLIPSOIDAL_HARMONIC).
from_topocentric_datum The topocentric datum to apply if from_coordinates is TOPOCENTRIC. If not specified, the datum used to construct the instance will be used.
to_topocentric_datum The topocentric datum to apply if to_coordinates is TOPOCENTRIC. If not specified, the datum used to construct the instance will be used.

Returns:

RigidTransform instance representing the coordinate transformation.

Exception:

std::invalid_argument if coordinate system is not global or topocentric datum is missing when required.

function Slice¶

Get a slice of coordinates.

Coordinates inertialsim::geodesy::Coordinates::Slice (
    int start,
    int end
) const

Returns a new Coordinates instance containing coordinates from start (inclusive) to end (exclusive). If the instance has time values, the corresponding times are also included.

Parameters:

start Start index (inclusive, 0-based).
end End index (exclusive, 0-based).

Returns:

New Coordinates instance with sliced elements.

Exception:

std::out_of_range if slice bounds are invalid.

function TimeDerivative¶

Numerical time derivative in current coordinate system.

Vector3D inertialsim::geodesy::Coordinates::TimeDerivative (
    int order=1,
    int accuracy=4
) const

Calculates numerical derivatives with respect to time using finite differences. The instance must have at least two elements with timestamps. First order derivatives estimate velocity, second order derivatives estimate acceleration, etc.

Derivatives are returned in the same coordinate system as the instance. If the coordinate system is curvilinear (geodetic, spherical, ellipsoidal harmonic), the derivatives are returned in the local basis of the coordinate system.

Parameters:

order Order of the derivative to calculate (default: 1).
accuracy Desired accuracy of the finite difference approximation (default: 4). Accuracy of order n requires n+1 samples.

Returns:

Time derivative array (3xN matrix).

Exception:

std::invalid_argument if timestamps are not set or fewer than 2 elements exist.

function coordinate_system¶

The coordinate system of the stored coordinates.

inline CoordinateSystem inertialsim::geodesy::Coordinates::coordinate_system () const

Returns the coordinate system type (GEODETIC, ECEF, TOPOCENTRIC, SPHERICAL, ELLIPSOIDAL_HARMONIC, LOCAL, or INERTIAL) of the stored coordinate data.

Returns:

Coordinate system type.

function coordinates¶

Array of raw coordinates.

inline const  Array3D & inertialsim::geodesy::Coordinates::coordinates () const

Returns the raw coordinate data as stored internally. The format depends on the coordinate system.

Returns:

Raw coordinate data matrix.

function geodetic_datum¶

The geodetic datum associated with the stored coordinates.

inline std::optional< GeodeticDatum > inertialsim::geodesy::Coordinates::geodetic_datum () const

Returns the geodetic datum (e.g., WGS84) used for coordinate conversions. Only set for coordinate systems that require a geodetic datum.

Returns:

Optional geodetic datum.

function num_coordinates¶

The number of coordinates stored in the instance.

inline int inertialsim::geodesy::Coordinates::num_coordinates () const

Returns the total number of coordinate sets stored. For instances with timestamps, this equals the number of time points.

Returns:

Number of coordinate sets.

function operator[]¶

Get a single coordinate by index.

inline Coordinates inertialsim::geodesy::Coordinates::operator[] (
    int index
) const

Returns a new Coordinates instance containing only the coordinate at the specified index. If the instance has time values, the corresponding time is also included.

Parameters:

index Index of the coordinate to retrieve (0-based).

Returns:

New Coordinates instance with a single coordinate.

Exception:

std::out_of_range if index is out of bounds.

function time¶

Array of times corresponding to each coordinate.

inline std::optional< Timestamps > inertialsim::geodesy::Coordinates::time () const

Returns the array of timestamps if set during construction, otherwise returns nullopt. When present, times are unique and strictly increasing.

Returns:

Optional time array.

function topocentric_datum¶

The topocentric datum associated with the stored coordinates.

inline std::optional< TopocentricDatum > inertialsim::geodesy::Coordinates::topocentric_datum () const

Returns the topocentric datum describing the origin and axis ordering (NED or ENU) for topocentric coordinate systems.

Returns:

Optional topocentric datum.

Public Static Functions Documentation¶

function FromEcef¶

Construct from ECEF coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromEcef (
    const  Vector3D & xyz,
    const  GeodeticDatum & datum=WGS84,
    const std::optional< Timestamps > & time=std::nullopt
)

The z-axis points along Earth's rotation axis (through the IERS Reference Pole), the x-axis is the line between the equatorial plane and the zero-meridian plane (IERS Reference Meridian) and the y-axis forms a right-hand orthonormal basis.

Axis direction conventions

Virtually all references use the convention described above, but a notable exception is Reference [01] which places the y-axis along Earth's rotation axis.

Parameters:

xyz ECEF coordinates (meters).
datum A datum describing Earth's shape and gravity field.
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromEllipsoidalHarmonic¶

Construct from ellipsoidal harmonic coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromEllipsoidalHarmonic (
    const  Array3D & upl,
    const  GeodeticDatum & datum=WGS84,
    const std::optional< Timestamps > & time=std::nullopt
)

Creates a Coordinates instance from ellipsoidal harmonic coordinates. Ellipsoidal harmonic coordinates are defined in Reference [23] and Standard [07] (where they are referred to simply as ellipsoidal coordinates). They are used primarily for gravity calculations.

Order and direction conventions

InertialSim uses the semi-minor axis, polar angle, and longitude angle convention (reflected in the "upl" parameter name). The semi-minor axis is the axis of an ellipsoid confocal to the Earth through the point of interest. The polar angle is measured from the polar axis to the line of reduced latitude. It is the complement of the reduced latitude. The ellipsoidal harmonic longitude is equivalent to the geodetic longitude defined in FromGeodetic(). Reference [23] uses the reduced latitude rather than polar angle but a semi-major axis, reduced latitude, longitude triple has a left-handed local Cartesian basis.

Angle range conventions

To be valid, the ellipsoidal harmonic coordinates must meet the following requirements:

\[ 0 \leq \text{semi-minor axis} \\ 0 \leq \text{polar\_angle} \leq \pi \\ -\pi < \text{longitude} \leq \pi \text{ or } 0 \leq \text{longitude}

< 2\pi \]

To standardize, the longitude will be adjusted such that:
\\( -\\pi &lt; \\text{longitude} \\leq \\pi \\)

Parameters:

upl Ellipsoidal harmonic coordinates (semi-minor axis, polar angle, longitude). Semi-minor axis in meters, angles in radians.
datum A datum describing Earth's shape and gravity field.
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromGeodetic¶

Construct from geodetic coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromGeodetic (
    const  Array3D & lla,
    const  GeodeticDatum & datum=WGS84,
    const std::optional< Timestamps > & time=std::nullopt
)

Left-handed basis

Geodetic coordinates are traditionally ordered latitude, longitude, altitude. This is the convention that InertialSim adopts. Users should note that the local Cartesian basis of these coordinates is a left-handed system.

Range and sign conventions

Latitudes north of the equator are positive, latitudes south of the equator are negative. Longitude is measured relative to the zero-meridian (the IERS Reference Meridian, also known as the Greenwich meridian). Longitudes east of the zero-meridian are positive, longitudes west of the zero-meridian are negative. To be valid, the latitude and longitude coordinates must meet the following requirements:

\[ -\pi/2 \leq \text{latitude} \leq \pi/2 \\ -\pi < \text{longitude} \leq \pi \text{ or } 0 \leq \text{longitude}

< 2\pi \]

To standardize, the longitude will be adjusted such that:
\\( -\\pi &lt; \\text{longitude} \\leq \\pi \\)

Altitude is measured relative to the ellipsoid. Positive altitude is
above the ellipsoid, negative altitude is below the ellipsoid.

Parameters:

lla Geodetic coordinates (latitude, longitude, altitude). Latitude and longitude in radians, altitude in meters.
datum A datum describing Earth's shape and gravity field.
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromInertial¶

Construct from inertial coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromInertial (
    const  Vector3D & xyz,
    const std::optional< Timestamps > & time=std::nullopt
)

Creates a Coordinates instance from inertial (non-rotating) coordinates. Inertial coordinates must be specified with respect to a non-accelerating, non-rotating reference frame.

Parameters:

xyz Inertial coordinates (meters).
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromLocal [1/2]¶

Construct from simple local coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromLocal (
    const  Vector3D & position,
    const std::optional< Timestamps > & time=std::nullopt
)

Creates a Coordinates instance from local coordinates without a geodetic datum or transformation. This is useful for purely local coordinate systems that don't need to be related to Earth's surface.

Parameters:

position Local coordinates (meters).
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromLocal [2/2]¶

Construct from local coordinates with geodetic frame.

static Coordinates inertialsim::geodesy::Coordinates::FromLocal (
    const  Vector3D & position,
    const  Array3D & frame_origin,
    const  geometry::Rotation & frame_rotation,
    const  LocalDatum & local_datum,
    const std::optional< Timestamps > & time=std::nullopt
)

Creates a Coordinates instance from local coordinates that are defined relative to a geodetic origin point with a specified rotation. This allows local coordinates to be georeferenced and converted to global coordinate systems.

Axis ordering conventions

The local datum input must specify one of: Forward, Right, Down (FRD) axis ordering or Forward, Left, Up (FLU) axis ordering. The resulting topocentric coordinates will have NED ordering for FRD inputs and ENU ordering for FLU inputs.

Frame origin and rotation

The frame origin and rotation define the relationship between the local coordinates and topocentric coordinates. The origin is specified in geodetic coordinates (latitude, longitude, altitude). The frame rotation rotates from a local level topocentric frame at the origin into alignment with the local frame. This is equivalent to a coordinate rotation that transforms the position coordinates from local to topocentric. If the local frame is also level with respect to gravity, the rotation is just a yaw relative to North (NED) or East (ENU).

Parameters:

position Local coordinates (meters).
frame_origin Geodetic coordinates (latitude, longitude, altitude) specifying the origin of the local frame. See FromGeodetic() for geodetic coordinate conventions.
frame_rotation Rotation that rotates topocentric axes (NED or ENU) into the local axes (FRD or FLU respectively).
local_datum Axis ordering for the local frame (e.g., FRD or FLU).
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromSpherical¶

Construct from spherical coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromSpherical (
    const  Array3D & rpl,
    const  GeodeticDatum & datum=WGS84,
    const std::optional< Timestamps > & time=std::nullopt
)

Creates a Coordinates instance from geocentric spherical coordinates.

!!! info "Order and direction conventions" InertialSim uses the radius, polar angle, and longitude angle convention (reflected in the "rpl" parameter name). The radius is the distance from the origin of the coordinate system (Earth's center) to the point of interest (in meters). The polar angle is the angle between the z-axis and the radial line (in radians). The polar angle is also known as the inclination and is the complement of geocentric latitude (not equivalent to the geodetic latitude). The spherical longitude is equivalent to the geodetic longitude defined in FromGeodetic(). It is common to use geocentric latitude rather than polar angle but a radius, geocentric latitude, longitude triple has a left-handed local Cartesian basis.

!!! info "Angle range conventions" To be valid, the spherical coordinates must meet the following requirements:

\\[
0 \\leq \\text{radius} \\\\
0 \\leq \\text{polar\\\_angle} \\leq \\pi \\\\
-\\pi &lt; \\text{longitude} \\leq \\pi \\text{ or } 0 \\leq \\text{longitude}

< 2\pi \]

To standardize, the longitude will be adjusted such that:
\\( -\\pi &lt; \\text{longitude} \\leq \\pi \\)

Parameters:

rpl Spherical coordinates (radius, polar angle, longitude). Radius in meters, angles in radians.
datum A datum describing Earth's shape and gravity field.
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

function FromTopocentric¶

Construct from topocentric coordinates.

static Coordinates inertialsim::geodesy::Coordinates::FromTopocentric (
    const  Vector3D & ned,
    const  TopocentricDatum & datum,
    const std::optional< Timestamps > & time=std::nullopt
)

Creates a Coordinates instance from topocentric (local tangent plane) coordinates. Topocentric coordinates are also known as local-level coordinates. They are typically used to specify locations relative to a local landmark such as a point-of-origin, runway threshold, target, etc.

Axis direction conventions

InertialSim supports North, East, Down (NED) axis ordering by default. East, North, Up (ENU) is supported via the datum input.

Parameters:

ned Topocentric coordinates (NED or ENU, meters).
datum A datum describing the geodetic origin and axis order.
time Optional time array of unique, strictly increasing times.

Returns:

Coordinates instance.

Protected Functions Documentation¶

function Coordinates [1/2]¶

Default constructor.

inertialsim::geodesy::Coordinates::Coordinates () = default

function Coordinates [2/2]¶

Construct with raw data.

inline inertialsim::geodesy::Coordinates::Coordinates (
    const  Array3D & coordinates,
    CoordinateSystem coordinate_system,
    const std::optional< GeodeticDatum > & geodetic_datum=std::nullopt,
    const std::optional< TopocentricDatum > & topocentric_datum=std::nullopt,
    const std::optional< Timestamps > & time=std::nullopt
)

Use the factory methods (FromGeodetic, FromEcef, etc.) instead of calling this constructor directly.

Parameters:

coordinates Raw coordinate data.
coordinate_system The coordinate system of the data.
geodetic_datum Optional geodetic datum.
topocentric_datum Optional topocentric datum.
time Optional time array.

The documentation for this class was generated from the following file cpp/include/inertialsim/geodesy/coordinates.h