Skip to content

inertialsim.geodesy

Geodetic coordinates, gravity models, and earth rotation models.

The geodesy module provides:

  • classes to manipulate geodetic coordinates and poses (validate, store, transform, etc.)
  • models to calculate gravity at any point in the vicinity of Earth
  • models to calculate Earth's rotation rate
  • datums to define coordinate systems

Input conventions

All inputs are expected to be in SI units. Angles are expected to be in radians.

See the input conventions of the geometry module also.

Open-source packages

This module is tested for consistency against the following open source packages: 1. GeographicLib: https://geographiclib.sourceforge.io/

Modules:

Name Description
datums

Geodetic datums.

Classes:

Name Description
Coordinates

3-dimensional coordinates with respect to Earth.
CoordinateSystem

Supported coordinate systems.
ConstantEarthRate

Constant Earth rate model.
EllipsoidalEarthRate

Rotation rate model of Earth.
ZeroEarthRate

Zero Earth rate model.
ConstantGravity

Constant gravity model.
EllipsoidalGravity

Ellipsoidal gravity model.
Gravity

Abstract base class for gravity models.
ConstantMagneticField

Constant Magnetic field model.
WorldMagneticModel

Magnetic field model of Earth.
GlobalPose

Pose and velocity with respect to Earth.

Attributes:

Name Type Description
EarthRate
MagneticField

EarthRate module-attribute 

EarthRate = EarthModel

MagneticField module-attribute 

MagneticField = EarthModel

Coordinates 

Coordinates(
    coordinates: Vector,
    coordinate_system: CoordinateSystem,
    geodetic_datum: GeodeticDatum | None = None,
    topocentric_datum: TopocentricDatum | None = None,
)

3-dimensional coordinates with respect to Earth.

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.

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 info boxes in class and method documentation.

Coordinate system definition

Varying definitions exist for the terms coordinate system, reference frame, and related terms. Consistent with inertial navigation practice, here a coordinate system is defined as an axis system (an orthogonal Cartesian basis) and an origin point relative to Earth.

Methods:

Name Description
from_geodetic

Construct an instance from an array of geodetic coordinates.
from_ecef

Construct an instance from an array of ECEF coordinates.
from_topocentric

Construct an instance from an array of topocentric coordinates.
from_spherical

Construct an instance from an array of spherical coordinates.
from_ellipsoidal_harmonic

Construct an instance from ellipsoidal harmonic coordinates.
from_local

Construct an instance from an array of local Cartesian coordinates.
from_inertial

Construct an instance from an array of inertial coordinates.
as_geodetic

Return an array of geodetic coordinates.
as_ecef

Return an array of ECEF coordinates.
as_topocentric

Return an array of topocentric coordinates.
as_spherical

Return an array of geocentric spherical coordinates.
as_ellipsoidal_harmonic

Return an array of ellipsoidal harmonic coordinates.
rigid_transform

Return the rigid transform between two coordinate systems.
interpolate

Interpolate coordinates at the input times.
time_derivative

Return a numerical derivative with respect to time.

Attributes:

Name Type Description
coordinate_system CoordinateSystem

The coordinate system of the stored coordinates.
num_coordinates int

The number of coordinates stored in the instance.
num_elements int

The number of coordinates stored in the instance.
coordinates NDArray

Array of raw coordinates.
time NDArray | None

Array of times corresponding to each coordinate.
geodetic_datum GeodeticDatum | None

The geodetic datum associated with the stored coordinates.
topocentric_datum TopocentricDatum | None

The topocentric datum associated with the stored coordinates.

coordinate_system property 

coordinate_system: CoordinateSystem

The coordinate system of the stored coordinates.

num_coordinates property 

num_coordinates: int

The number of coordinates stored in the instance.

num_elements property 

num_elements: int

The number of coordinates stored in the instance.

coordinates property 

coordinates: NDArray

Array of raw coordinates.

time property 

time: NDArray | None

Array of times corresponding to each coordinate.

geodetic_datum property 

geodetic_datum: GeodeticDatum | None

The geodetic datum associated with the stored coordinates.

Returns None if there is no geodetic datum specified.

topocentric_datum property 

topocentric_datum: TopocentricDatum | None

The topocentric datum associated with the stored coordinates.

Returns None if there is no topocentric datum specified.

from_geodetic classmethod 

from_geodetic(
    lla: ArrayLike,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
) -> Self

Construct an instance from an array of geodetic coordinates.

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 <= latitude <= pi/2
-pi < longitude <= pi or 0 <= longitude < 2*pi
To standardize, the longitude will be adjusted such that: 
-pi < longitude <= pi
Altitude is measured relative to the ellipsoid. Positive altitude is above the ellipsoid, negative altitude is below the ellipsoid.

Parameters:

Name Type Description Default
lla ArrayLike

Array of geodetic coordinates (latitude, longitude, altitude).

 required
datum GeodeticDatum

A datum describing Earth's shape and gravity field.

 WGS84
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

from_ecef classmethod 

from_ecef(
    xyz: ArrayLike,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
) -> Self

Construct an instance from an array of ECEF coordinates.

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:

Name Type Description Default
xyz ArrayLike

ECEF coordinates or array of ECEF coordinates.

 required
datum GeodeticDatum

A datum describing Earth's shape and gravity field.

 WGS84
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

from_topocentric classmethod 

from_topocentric(
    xyz: ArrayLike,
    topocentric_datum: TopocentricDatum,
    time: ArrayLike | None = None,
) -> Self

Construct an instance from an array of topocentric 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:

Name Type Description Default
xyz ArrayLike

Topocentric coordinates or an array of topocentric coordinates.

 required
topocentric_datum TopocentricDatum

A datum describing the geodetic origin and axis order of the topocentric coordinates.

 required
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

from_spherical classmethod 

from_spherical(
    rpl: ArrayLike,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
) -> Self

Construct an instance from an array of spherical coordinates.

Order and direction conventions

InertialSim uses the radius, polar angle, and longitude angle convention (reflected in the "rpl" input variable 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 from_geodetic. 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.

Angle range conventions

To be valid, the spherical coordinates must meet the following requirements: 

0 <= range
0 <= polar_angle <= pi
-pi < longitude <= pi or 0 <= longitude < 2*pi
To standardize, the longitude will be adjusted such that: 
-pi < longitude <= pi

Parameters:

Name Type Description Default
rpl ArrayLike

Geocentric spherical coordinates (radius, polar angle, longitude) or array of spherical coordinates.

 required
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None
datum GeodeticDatum

A datum describing Earth's shape and gravity field.

 WGS84

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

from_ellipsoidal_harmonic classmethod 

from_ellipsoidal_harmonic(
    upl: ArrayLike,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
) -> Self

Construct an 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" input variable 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 from_geodetic. 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 <= semi-minor axis
0 <= polar_angle <= pi
-pi < longitude <= pi or 0 <= longitude < 2*pi
To standardize, the longitude will be adjusted such that: 
-pi < longitude <= pi

Parameters:

Name Type Description Default
upl ArrayLike

Ellipsoidal harmonic coordinates (semi-minor axis, polar angle, longitude) or array of ellipsoidal harmonic coordinates.

 required
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None
datum GeodeticDatum

A datum describing Earth's shape and gravity field.

 WGS84

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

from_local classmethod 

from_local(
    *, position: ArrayLike, time: ArrayLike | None = None
) -> Self

from_local(
    *,
    position: ArrayLike,
    frame_origin: ArrayLike,
    frame_rotation: Rotation,
    local_datum: LocalDatum,
    time: ArrayLike | None = None,
) -> Self

from_local(
    *,
    position: ArrayLike,
    frame_origin: ArrayLike | None = None,
    frame_rotation: Rotation | None = None,
    local_datum: LocalDatum | None = None,
    time: ArrayLike | None = None,
) -> Self

Construct an instance from an array of local Cartesian coordinates.

If position and time are the only inputs, the local coordinates are specified independent of Earth.

If frame_origin, frame_rotation, and local_datum are provided, the local coordinates are converted to topocentric coordinates.

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:

Name Type Description Default
position ArrayLike

Local cartesian coordinates or an array of coordinates.

 required
frame_origin ArrayLike | None

Origin of the local frame in geodetic coordinates (latitude, longitude, altitude). See from_geodetic for geodetic coordinate conventions.

 None
frame_rotation Rotation | None

Rotation that rotates topocentric axes (NED or ENU) into the local axes (FRD or FLU respectively).

 None
local_datum LocalDatum | None

A datum describing the local coordinates axis order.

 None
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

from_inertial classmethod 

from_inertial(
    xyz: ArrayLike, time: ArrayLike | None = None
) -> Self

Construct an instance from an array of inertial coordinates.

Inertial coordinates must be specified with respect to a non-accelerating, non-rotating reference frame.

Parameters:

Name Type Description Default
xyz ArrayLike

Inertial cartesian coordinates or an array of coordinates.

 required
time ArrayLike | None

Array of unique, strictly increasing times corresponding to each coordinate input.

 None

Returns:

Name Type Description
coordinates Self

A Coordinates instance.

as_geodetic 

as_geodetic() -> NDArray

Return an array of geodetic coordinates.

See additional documentation regarding geodetic coordinate conventions at: from_geodetic.

Returns:

Name Type Description
lla NDArray

Array of geodetic coordinates (latitude, longitude, altitude).

as_ecef 

as_ecef() -> NDArray

Return an array of ECEF coordinates.

See additional documentation regarding ECEF coordinate conventions at: from_ecef.

Returns:

Name Type Description
xyz NDArray

Array of ECEF coordinates.

as_topocentric 

as_topocentric(
    datum: TopocentricDatum | None = None,
) -> NDArray

Return an array of topocentric coordinates.

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 a ValueError will be raised.

See additional documentation regarding topocentric coordinate conventions at: from_topocentric.

Returns:

Name Type Description
ned NDArray

Array of topocentric coordinates.
topocentric_datum NDArray

A datum describing the geodetic origin and axis order of the topocentric coordinates.

as_spherical 

as_spherical() -> NDArray

Return an array of geocentric spherical coordinates.

See additional documentation regarding spherical coordinate conventions at: from_spherical.

Returns:

Name Type Description
rpl NDArray

Array of geocentric spherical coordinates (radius, polar angle, longitude).

as_ellipsoidal_harmonic 

as_ellipsoidal_harmonic() -> NDArray

Return an array of ellipsoidal harmonic coordinates.

See additional documentation regarding ellipsoidal harmonic coordinate conventions at: from_ellipsoidal_harmonic.

Returns:

Name Type Description
upl NDArray

Array of ellipsoidal harmonic coordinates (semi-minor axis, polar angle, longitude).

rigid_transform 

rigid_transform(
    from_coordinates: CoordinateSystem,
    to_coordinates: CoordinateSystem,
    from_topocentric_datum: TopocentricDatum | None = None,
    to_topocentric_datum: TopocentricDatum | None = None,
) -> RigidTransform

Return the rigid transform between two coordinate systems.

The rotation component of the rigid transform will be the rotation between the basis vectors of each coordinate system. For curvilinear coordinates (geodetic, spherical, ellipsoidal harmonic), these will be the local basis vectors. The translation component of the rigid transform will be the vector difference between the origin of each coordinate system.

For converting positions (points), prefer to use the from and to methods directly. This function is helpful in 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 a ValueError will be raised.

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 RigidTransform for more details.

Parameters:

Name Type Description Default
from_coordinates CoordinateSystem

The source coordinate system. One of: "geodetic", "ecef", "topocentric", "spherical", or "ellipsoidal_harmonic"

 required
to_coordinates CoordinateSystem

The destination coordinate system. One of: "geodetic", "ecef", "topocentric", "spherical", or "ellipsoidal_harmonic"

 required
from_topocentric_datum TopocentricDatum | None

The topocentric datum to apply if the from_coordinates input is "topocentric". If not specified the datum used to construct the instance will be used.

 None
to_topocentric_datum TopocentricDatum | None

The topocentric datum to apply if the to_coordinates input is "topocentric". If not specified the datum used to construct the instance will be used.

 None

Returns:

Name Type Description
transform RigidTransform

A RigidTransform instance.

interpolate 

interpolate(
    time: ArrayLike, method: Interpolator = LINEAR
) -> Self

Interpolate coordinates at the input times.

The time input can be any array of times or indices consistent with those used to construct the instance originally. Values outside of 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:

Name Type Description Default
time ArrayLike

Array of unique, strictly increasing times (or indices) corresponding to each desired output.

 required
method Interpolator

Interpolation method to use.

 LINEAR

Returns:

Name Type Description
coordinates Self

New instance constructed from the input times and interpolated elements.

time_derivative 

time_derivative(
    order: int = 1, accuracy: int = 4
) -> NDArray

Return a numerical derivative with respect to time.

The result is calculated with finite differences. The instance must have at least two elements and timestamps or a ValueError is raised. 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:

Name Type Description Default
order int

Order of the derivative to calculate.

 1
accuracy int

Desired accuracy of the finite difference approximation. Accuracy of order n, requires n+1 samples.

 4

Returns:

Name Type Description
derivative NDArray

Time derivative array.

CoordinateSystem

Bases: Flag

Supported coordinate systems.

Superset of coordinate systems supported by InertialSim. Individual modules and classes may only support a subset.

Attributes:

Name Type Description
GEODETIC
ECEF
TOPOCENTRIC
SPHERICAL
ELLIPSOIDAL_HARMONIC
LOCAL
INERTIAL
CARTESIAN
CURVILINEAR
GLOBAL

GEODETIC class-attribute instance-attribute 

GEODETIC = auto()

ECEF class-attribute instance-attribute 

ECEF = auto()

TOPOCENTRIC class-attribute instance-attribute 

TOPOCENTRIC = auto()

SPHERICAL class-attribute instance-attribute 

SPHERICAL = auto()

ELLIPSOIDAL_HARMONIC class-attribute instance-attribute 

ELLIPSOIDAL_HARMONIC = auto()

LOCAL class-attribute instance-attribute 

LOCAL = auto()

INERTIAL class-attribute instance-attribute 

INERTIAL = auto()

CARTESIAN class-attribute instance-attribute 

CARTESIAN = ECEF | TOPOCENTRIC | INERTIAL | LOCAL

CURVILINEAR class-attribute instance-attribute 

CURVILINEAR = GEODETIC | SPHERICAL | ELLIPSOIDAL_HARMONIC

GLOBAL class-attribute instance-attribute 

GLOBAL = (
    GEODETIC
    | ECEF
    | TOPOCENTRIC
    | SPHERICAL
    | ELLIPSOIDAL_HARMONIC
)

ConstantEarthRate 

ConstantEarthRate(earth_rate: ArrayLike | Vector)

Bases: EarthRate

Constant Earth rate model.

Models a constant Earth rate vector for all coordinates. This is appropriate for ECEF, topocentric, and local coordinate systems, where the basis is fixed and the earth rate vector remains constant.

Methods:

Name Description
magnitude

Return the magnitude of Earth rate at the given coordinates.
vector

Return the Earth rate vector at the given coordinates.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Return the magnitude of Earth rate at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant Earth rate magnitude is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
earth_rate NDArray

Array of Earth rate magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    _: CoordinateSystem | None = None,
) -> NDArray

Return the Earth rate vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant Earth rate vector is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
earth_rate NDArray

Array of Earth rate vectors.

EllipsoidalEarthRate

Bases: EarthRate

Rotation rate model of Earth.

Earth rotates at an approximately constant rate around the z-axis of an Earth-centered, Earth-fixed (ECEF) coordinate system. This rotation contributes to apparent forces (coriolis, centripetal, etc.) that must be compensated in inertial equations of motion.

The model is stateless and inherits parameters from the datum associated with the coordinate inputs.

The model supports both the magnitude and vector representations of the Earth rate based on input Coordinates.

Methods:

Name Description
magnitude

Return the magnitude of Earth rate at the given coordinates.
vector

Return the Earth rate vector at the given coordinates.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Return the magnitude of Earth rate at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be geodetic.

The magnitude may be a constant, which is returned for each coordinate input.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
earth_rate NDArray

Array of Earth rate magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    basis: CoordinateSystem | None = None,
) -> NDArray

Return the Earth rate vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be geodetic.

By default, the Earth rate vector components will be expressed in the basis of the input coordinates. For curvilinear systems (e.g. geodetic), the basis is the local basis at the given coordinates. If basis is supplied, it will be used instead.

See Coordinates for additional conventions and details.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required
basis CoordinateSystem | None

Basis in which to return the Earth rate vector.

 None

Returns:

Name Type Description
earth_rate NDArray

Array of Earth rate vectors.

ZeroEarthRate 

ZeroEarthRate()

Bases: ConstantEarthRate

Zero Earth rate model.

Models a zero Earth rate vector for all coordinates. This is appropriate for inertial coordinates where Earth is irrelevant, or for local coordinates where Earth rate effects are neglected. Explicitly modeling zero Earth rate allows for optimization of some inertial navigation computations.

Methods:

Name Description
magnitude

Return the magnitude of Earth rate at the given coordinates.
vector

Return the Earth rate vector at the given coordinates.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Return the magnitude of Earth rate at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant Earth rate magnitude is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
earth_rate NDArray

Array of Earth rate magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    _: CoordinateSystem | None = None,
) -> NDArray

Return the Earth rate vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant Earth rate vector is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
earth_rate NDArray

Array of Earth rate vectors.

ConstantGravity 

ConstantGravity(gravity: ArrayLike | Vector | None = None)

Bases: Gravity

Constant gravity model.

Methods:

Name Description
standard_vector

Standard gravity in a topocentric frame.
magnitude

Return the magnitude of gravity at the given coordinates.
vector

Return the gravity vector at the given coordinates.

Attributes:

Name Type Description
standard_magnitude

Standard gravity magnitude.

standard_magnitude class-attribute instance-attribute 

standard_magnitude = _STANDARD_GRAVITY

Standard gravity magnitude.

The standard value of gravity is 9.80665 ms-2 (See Standard [01] and equivalent international standards). This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should be used to convert units of "g". It may be used in applications where a single global approximation is appropriate.

standard_vector classmethod 

standard_vector(
    axis_order: TopocentricAxisOrder = NED,
) -> NDArray

Standard gravity in a topocentric frame.

The standard value of gravity is 9.80665 ms-2 (See Standard [01] and equivalent international standards). This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should be used to convert units of "g". It may be used in applications where a single global approximation is appropriate.

Parameters:

Name Type Description Default
axis_order TopocentricAxisOrder

The axis ordering of the topocentric frame. Must be one of "NED" or "ENU".

 NED

Returns:

Name Type Description
gravity NDArray

Standard gravity in topocentric frame.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Return the magnitude of gravity at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant gravity magnitude is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
gravity NDArray

Array of gravity magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    _: CoordinateSystem | None = None,
) -> NDArray

Return the gravity vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant gravity vector is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
gravity NDArray

Array of gravity vectors.

EllipsoidalGravity

Bases: Gravity

Ellipsoidal gravity model.

Analytic model based on an equipotential ellipsoid of revolution, as in the WGS84 model of Earth.

Gravity is gravitational acceleration from the mass of ellipsoid plus the effect of centripetal acceleration from the rotation of the ellipsoid. An exact ellipsoidal model with approximate extensions for negative altitudes is used.

Methods:

Name Description
standard_vector

Standard gravity in a topocentric frame.
magnitude

Return the magnitude of gravity at the given coordinates.
vector

Return the gravity vector at the given coordinates.

Attributes:

Name Type Description
standard_magnitude

Standard gravity magnitude.

standard_magnitude class-attribute instance-attribute 

standard_magnitude = _STANDARD_GRAVITY

Standard gravity magnitude.

The standard value of gravity is 9.80665 ms-2 (See Standard [01] and equivalent international standards). This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should be used to convert units of "g". It may be used in applications where a single global approximation is appropriate.

standard_vector classmethod 

standard_vector(
    axis_order: TopocentricAxisOrder = NED,
) -> NDArray

Standard gravity in a topocentric frame.

The standard value of gravity is 9.80665 ms-2 (See Standard [01] and equivalent international standards). This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should be used to convert units of "g". It may be used in applications where a single global approximation is appropriate.

Parameters:

Name Type Description Default
axis_order TopocentricAxisOrder

The axis ordering of the topocentric frame. Must be one of "NED" or "ENU".

 NED

Returns:

Name Type Description
gravity NDArray

Standard gravity in topocentric frame.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Return the magnitude of gravity at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be geodetic.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
gravity NDArray

Array of gravity magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    basis: CoordinateSystem | None = None,
) -> NDArray

Return the gravity vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be geodetic.

By default, the gravity vector components will be expressed in the basis of the input coordinates. For curvilinear systems (e.g. geodetic), the basis is the local basis at the given coordinates. If basis is supplied, it will be used instead.

See Coordinates for additional conventions and details.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required
basis CoordinateSystem | None

Basis in which to return the gravity vector.

 None

Returns:

Name Type Description
gravity NDArray

Array of gravity vectors.

Gravity

Bases: EarthModel

Abstract base class for gravity models.

Methods:

Name Description
magnitude

Return a scalar parameter at the given coordinates.
vector

Return a vector parameter at the given coordinates.
standard_vector

Standard gravity in a topocentric frame.

Attributes:

Name Type Description
standard_magnitude

Standard gravity magnitude.

standard_magnitude class-attribute instance-attribute 

standard_magnitude = _STANDARD_GRAVITY

Standard gravity magnitude.

The standard value of gravity is 9.80665 ms-2 (See Standard [01] and equivalent international standards). This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should be used to convert units of "g". It may be used in applications where a single global approximation is appropriate.

magnitude abstractmethod 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Return a scalar parameter at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are converted to Coordinates, perhaps with assumptions.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
magnitude NDArray

Array of magnitudes.

vector abstractmethod 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    basis: CoordinateSystem | None = None,
) -> NDArray

Return a vector parameter at the given coordinates.

The coordinates input can be a Coordinates instance, a Vector or an numpy array. If a Vector or array, the coordinates are converted to Coordinates, perhaps with assumptions.

By default, the vector components will be expressed in the basis associated with the coordinates. For curvilinear systems (e.g. geodetic), the basis is the local basis at the given coordinates. If basis is supplied, it will be used instead.

See Coordinates for additional conventions and details.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required
basis CoordinateSystem | None

Basis in which to return the vector.

 None

Returns:

Name Type Description
vector NDArray

Array of vectors.

standard_vector classmethod 

standard_vector(
    axis_order: TopocentricAxisOrder = NED,
) -> NDArray

Standard gravity in a topocentric frame.

The standard value of gravity is 9.80665 ms-2 (See Standard [01] and equivalent international standards). This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should be used to convert units of "g". It may be used in applications where a single global approximation is appropriate.

Parameters:

Name Type Description Default
axis_order TopocentricAxisOrder

The axis ordering of the topocentric frame. Must be one of "NED" or "ENU".

 NED

Returns:

Name Type Description
gravity NDArray

Standard gravity in topocentric frame.

ConstantMagneticField 

ConstantMagneticField(magnetic_field: ArrayLike | Vector)

Bases: MagneticField

Constant Magnetic field model.

Methods:

Name Description
magnitude

Magnitude of Earth's magnetic field at the given coordinates.
vector

Return the Earth's magnetic field vector at the given coordinates.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Magnitude of Earth's magnetic field at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

The copy of the constant magnetic field magnitude is returned for each coordinate input.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
magnetic_field NDArray

Array of magnetic field magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    _: CoordinateSystem | None = None,
) -> NDArray

Return the Earth's magnetic field vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be local.

A copy of the constant magnetic field vector is returned for each input coordinate.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
magnetic_field NDArray

Array of magnetic field vectors.

WorldMagneticModel 

WorldMagneticModel(
    date: float | date, datum: MagneticDatum = WMM2025
)

Bases: EarthModel

Magnetic field model of Earth.

Earth's magnetic field is modeled empirically by the World Magnetic Model standard (Standard [08]). This model includes so-called "internal" sources of magnetism (Earth's liquid-iron outer core, magnetic minerals in the crust, etc.) but does not include external "disturbance fields".

The model is initialized with a date, and a World Magnetic Model (WMM) datum. Methods return the value of Earth's magnetic field in the local basis of various frames at the input coordinates and date.

The World Magnetic Model (WMM) datum is published in 5 year cycles with a reference epoch at the start of the cycle.

Earth shape calculations will use the datum of the coordinates inputs.

Date precision

The precision of the underlying model is limited and requires only an approximate date. See Standard [08] for more details. The date can be specified as a decimal year (e.g. 2025.63) or as a datetime.date object (e.g. 2025-06-03). Datetime objects are converted internally to decimal years at the start of the specified day and using the number of days in the specified year (365 or 366).

Polar fields

At the poles, the direction of the field requires special definition. In geocentric spherical or geodetic coordinates, the field is returned in [x,y,z] components which are the limit of the local basis vectors as the pole is approached along the zero longitude meridian. See Standard [08] Section 1.4 for more details.

Parameters:

Name Type Description Default
date float | date

Date of simulation.

 required
datum MagneticDatum

World magnetic model datum.

 WMM2025

Methods:

Name Description
magnitude

Magnitude of Earth's magnetic field at the given coordinates.
vector

Return the Earth's magnetic field vector at the given coordinates.

magnitude 

magnitude(
    coordinates: Coordinates | Vector | ArrayLike,
) -> NDArray

Magnitude of Earth's magnetic field at the given coordinates.

The input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be geodetic.

The magnitude is returned for each coordinate input.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required

Returns:

Name Type Description
magnetic_field NDArray

Array of magnetic field magnitudes.

vector 

vector(
    coordinates: Coordinates | Vector | ArrayLike,
    basis: CoordinateSystem | None = None,
) -> NDArray

Return the Earth's magnetic field vector at the given coordinates.

The coordinates input can be a Coordinates instance (supporting all global coordinate systems), a Vector or an numpy array. If a Vector or array, the coordinates are assumed to be geodetic.

By default, the magnetic field vector components will be expressed in the basis of the input coordinates. For curvilinear systems (e.g. geodetic), the basis is the local basis at the given coordinates. If basis is supplied, it will be used instead.

See Coordinates for additional conventions and details.

Parameters:

Name Type Description Default
coordinates Coordinates | Vector | ArrayLike

Array of coordinates.

 required
basis CoordinateSystem | None

Basis in which to return the magnetic field vector.

 None

Returns:

Name Type Description
magnetic_field NDArray

Array of magnetic field vectors.

GlobalPose 

GlobalPose(
    *,
    navigation_frame: CoordinateSystem,
    attitude: Rotation,
    position: Coordinates,
    velocity: Vector | None,
    gravity_model: Gravity,
    earth_rate_model: EarthRate,
)

Pose and velocity with respect to Earth.

Attitude, position, and velocity represented in the standard form for inertial navigation. Attitude is also known as orientation.

Use the from methods to construct an instance. Do not initialize an instance directly.

Geodetic vs. geometric pose

This class is for managing poses with respect to Earth. See geometry.Pose for purely geometric pose. See also geodesy.Coordinates for position with respect to Earth and for more details about coordinate conventions.

Methods:

Name Description
from_ecef

Construct a pose from ECEF inputs.
from_geodetic

Construct a pose from geodetic inputs.
from_topocentric

Construct a pose from topocentric inputs.
from_inertial

Construct a pose from inertial frame inputs.
from_local

Construct a global pose from local pose inputs.
as_extended_pose

Return the pose as a geometric pose object.
earth_rate

Return Earth's rotation rate.
gravity

Return Earth's gravity.
angular_rate

Return a numerical estimate of angular velocity.
inertial_angular_rate

Return an estimate of angular velocity w.r.t. inertial space.
specific_force

Return a numerical estimate of specific force.
interpolate

Interpolate poses at the input times.

Attributes:

Name Type Description
num_poses int

The number of poses stored in the instance.
num_elements int

The number of poses stored in the instance.
time NDArray | None

Array of times corresponding to each pose.
attitude Rotation

The attitude component of the pose.
position Coordinates

The position component of the pose.
velocity Vector | None

The velocity component of the pose.
navigation_frame CoordinateSystem

The navigation frame.

num_poses property 

num_poses: int

The number of poses stored in the instance.

num_elements property 

num_elements: int

The number of poses stored in the instance.

time property 

time: NDArray | None

Array of times corresponding to each pose.

attitude property 

attitude: Rotation

The attitude component of the pose.

position property 

position: Coordinates

The position component of the pose.

velocity property 

velocity: Vector | None

The velocity component of the pose.

navigation_frame property 

navigation_frame: CoordinateSystem

The navigation frame.

from_ecef classmethod 

from_ecef(
    *,
    attitude: Rotation,
    position: Coordinates,
    velocity: Vector | None,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_ecef(
    *,
    attitude: ArrayLike,
    position: ArrayLike,
    velocity: ArrayLike | None,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike,
    orthonormalize: bool = False,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_ecef(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

Construct a pose from ECEF inputs.

Construct a Pose from Earth-centered, Earth-fixed (ECEF) attitude, position, velocity and supporting inputs. See Coordinates.from_ecef for more details on ECEF frame conventions.

Velocity inputs are optional. If velocity = None it is calculated with accurate finite differences of the position. Inputs can be specified as inertialsim geometry objects or numpy arrays which are converted internally to the relevant object.

Parameters:

Name Type Description Default
attitude Rotation | ArrayLike

The attitude (orientation) that describes the sensor (body) frame relative to the ECEF frame. If specified as an array, it must be in rotation matrix form.

 required
position Coordinates | ArrayLike

The position of the sensor (body) frame in ECEF coordinates.

 required
velocity Vector | ArrayLike | None

The velocity of the sensor (body) frame in ECEF coordinates.

 required
datum GeodeticDatum

The geodetic datum associated with the ECEF coordinates.

 WGS84
time ArrayLike | None

If any of the attitude, position, or velocity inputs are arrays, an array of unique, strictly increasing times corresponding to each sample. Ignored otherwise.

 None
orthonormalize bool

If the attitude input is an array, enforce orthonormality of the matrix input. Ignored otherwise.

 False
gravity_model Gravity | None

The gravity model to use to compute gravity vectors. If None, an EllipsoidalGravity model is used.

 None
earth_rate_model EarthRate | None

The Earth rate model to use to compute Earth rate vectors. If None, an EllipsoidalEarthRate model is used.

 None

Returns:

Name Type Description
pose Self

A GlobalPose instance.

from_geodetic classmethod 

from_geodetic(
    *,
    attitude: Rotation,
    position: Coordinates,
    velocity: Vector | None,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_geodetic(
    *,
    attitude: ArrayLike,
    position: ArrayLike,
    velocity: ArrayLike | None,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike,
    orthonormalize: bool = False,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_geodetic(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

Construct a pose from geodetic inputs.

Construct a Pose from geodetic attitude, position, velocity and supporting inputs. See Coordinates.from_geodetic for more details on geodetic frame conventions.

Velocity inputs are optional. If velocity = None it is calculated with accurate finite differences of the position. Inputs can be specified as inertialsim geometry objects or numpy arrays which are converted internally to the relevant object.

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). Valid geometric transforms must be right-handed, so a north-east-down (NED) local basis is used instead. This affects the definition of attitude, velocity, the output of gravity, and other similar functions.

Parameters:

Name Type Description Default
attitude Rotation | ArrayLike

The attitude (orientation) that describes the sensor (body) frame relative to a local level north, east, down (NED) frame. Local means a a frame whose origin is at the instantaneous position of the sensor frame origin. If specified as an array, it must be in rotation matrix form.

 required
position Coordinates | ArrayLike

The position of the sensor (body) frame in geodetic coordinates (latitude, longitude, ellipsoidal altitude).

 required
velocity Vector | ArrayLike | None

The velocity of the sensor (body) frame in local level north, east, down (NED) coordinates.

 required
datum GeodeticDatum

The geodetic datum associated with the geodetic coordinates.

 WGS84
time ArrayLike | None

If any of the attitude, position, or velocity inputs are arrays, an array of unique, strictly increasing times corresponding to each sample. Ignored otherwise.

 None
orthonormalize bool

If the attitude input is an array, enforce orthonormality of the matrix input. Ignored otherwise.

 False
gravity_model Gravity | None

The gravity model to use to compute gravity vectors. If None, an EllipsoidalGravity model is used.

 None
earth_rate_model EarthRate | None

The Earth rate model to use to compute Earth rate vectors. If None, an EllipsoidalEarthRate model is used.

 None

Returns:

Name Type Description
pose Self

A GlobalPose instance.

from_topocentric classmethod 

from_topocentric(
    *,
    attitude: Rotation,
    position: Coordinates,
    velocity: Vector | None,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_topocentric(
    *,
    attitude: ArrayLike,
    position: ArrayLike,
    velocity: ArrayLike | None,
    datum: TopocentricDatum,
    time: ArrayLike,
    orthonormalize: bool = False,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_topocentric(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    datum: TopocentricDatum | None = None,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
    gravity_model: Gravity | None = None,
    earth_rate_model: EarthRate | None = None,
) -> Self

Construct a pose from topocentric inputs.

Construct a Pose from topocentric attitude, position, velocity and supporting inputs. See Coordinates.from_topocentric for more details on topocentric frame conventions.

Velocity inputs are optional. If velocity = None it is calculated with accurate finite differences of the position. Inputs can be specified as inertialsim geometry objects or numpy arrays which are converted internally to the relevant object.

Parameters:

Name Type Description Default
attitude Rotation | ArrayLike

The attitude (orientation) that describes the sensor (body) frame relative to the topocentric frame. If specified as an array, it must be in rotation matrix form.

 required
position Coordinates | ArrayLike

The position of the sensor (body) frame in topocentric coordinates.

 required
velocity Vector | ArrayLike | None

The velocity of the sensor (body) frame in topocentric coordinates.

 required
datum TopocentricDatum | None

The topocentric datum associated with the coordinates.

 None
time ArrayLike | None

If any of the attitude, position, or velocity inputs are arrays, an array of unique, strictly increasing times corresponding to each sample. Ignored otherwise.

 None
orthonormalize bool

If the attitude input is an array, enforce orthonormality of the matrix input. Ignored otherwise.

 False
gravity_model Gravity | None

The gravity model to use to compute gravity vectors. If None, an EllipsoidalGravity model is used.

 None
earth_rate_model EarthRate | None

The Earth rate model to use to compute Earth rate vectors. If None, an EllipsoidalEarthRate model is used.

 None

Returns:

Name Type Description
pose Self

A GlobalPose instance.

from_inertial classmethod 

from_inertial(
    *,
    attitude: Rotation,
    position: Coordinates,
    velocity: Vector | None,
    gravity_model: Gravity,
) -> Self

from_inertial(
    *,
    attitude: ArrayLike,
    position: ArrayLike,
    velocity: ArrayLike | None,
    time: ArrayLike,
    orthonormalize: bool = False,
    gravity_model: Gravity,
) -> Self

from_inertial(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
    gravity_model: Gravity,
) -> Self

Construct a pose from inertial frame inputs.

Construct a Pose from attitude, position, velocity relative to an inertial frame.

Velocity inputs are optional. If velocity = None it is calculated with accurate finite differences of the position. Inputs can be specified as inertialsim geometry objects or numpy arrays which are converted internally to the relevant object.

Because inertial frames do not rotate, there is no Earth rate model input.

Parameters:

Name Type Description Default
attitude Rotation | ArrayLike

The attitude (orientation) that describes the sensor (body) frame relative to the inertial frame. If specified as an array, it must be in rotation matrix form.

 required
position Coordinates | ArrayLike

The position of the sensor (body) frame in inertial coordinates.

 required
velocity Vector | ArrayLike | None

The velocity of the sensor (body) frame in inertial coordinates.

 required
time ArrayLike | None

If any of the attitude, position, or velocity inputs are arrays, an array of unique, strictly increasing times corresponding to each sample. Ignored otherwise.

 None
orthonormalize bool

If the attitude input is an array, whether to enforce orthonormality. Ignored otherwise.

 False
gravity_model Gravity

The gravity model to use to compute gravity vectors.

 required

Returns:

Name Type Description
pose Self

A GlobalPose instance.

from_local classmethod 

from_local(
    *,
    pose: Pose | ExtendedPose,
    gravity_model: Gravity,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_local(
    *,
    attitude: Rotation,
    position: Vector,
    velocity: Vector | None,
    gravity_model: Gravity,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_local(
    *,
    attitude: ArrayLike,
    position: ArrayLike,
    velocity: ArrayLike | None,
    time: ArrayLike,
    orthonormalize: bool = False,
    gravity_model: Gravity,
    earth_rate_model: EarthRate | None = None,
) -> Self

from_local(
    *,
    pose: Pose | ExtendedPose | None = None,
    attitude: Rotation | ArrayLike | None = None,
    position: Vector | ArrayLike | None = None,
    velocity: Vector | ArrayLike | None = None,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
    gravity_model: Gravity,
    earth_rate_model: EarthRate | None = None,
) -> Self

Construct a global pose from local pose inputs.

Construct a Pose from local attitude, position, velocity (optional) and supporting inputs.

If the pose input is supplied the attitude, position, and velocity inputs are ignored. Otherwise the attitude and position inputs must be supplied.

Inputs can be in an arbitrary local level frame.

Velocity inputs are optional. If velocity = None it is calculated with accurate finite differences of the position. Inputs can be specified as inertialsim geometry objects or numpy arrays which are converted internally to the relevant object.

The gravity_model is required and must return gravity vectors in the local frame. The earth_rate_model is optional and if not supplied a zero Earth rate model is used.

Parameters:

Name Type Description Default
pose Pose | ExtendedPose | None

A geometry Pose or ExtendedPose instance containing attitude (orientation) that describes the sensor (body) frame relative to the local frame; position of the sensor (body) frame in local coordinates; and velocity of the sensor (body) frame in local coordinates (ExtendedPose type only).

 None
attitude Rotation | ArrayLike | None

The attitude (orientation) that describes the sensor (body) frame relative to the local frame. If specified as an array, it must be in rotation matrix form.

 None
position Vector | ArrayLike | None

The position of the sensor (body) frame in local coordinates.

 None
velocity Vector | ArrayLike | None

The velocity of the sensor (body) frame in local coordinates.

 None
time ArrayLike | None

If any of the attitude, position, or velocity inputs are arrays, an array of unique, strictly increasing times corresponding to each sample. Ignored otherwise.

 None
orthonormalize bool

If the attitude input is an array, whether to enforce orthonormality. Ignored otherwise.

 False
gravity_model Gravity

The gravity model to use to compute gravity vectors.

 required
earth_rate_model EarthRate | None

The Earth rate model to use to compute Earth rate vectors.

 None

Returns:

Name Type Description
pose Self

A GlobalPose instance.

as_extended_pose 

as_extended_pose() -> ExtendedPose

Return the pose as a geometric pose object.

Returns the pose as an ExtendedPose instance.

ExtendedPose represents attitude, position, and velocity as a Lie group. If the navigation frame is geodetic, it is converted to Cartesian ECEF coordinates.

Returns:

Name Type Description
extended_pose ExtendedPose

The pose as an ExtendedPose instance.

earth_rate 

earth_rate(*, sensor_frame: bool = False) -> NDArray

Return Earth's rotation rate.

The rotation rate will be an array of vectors, one for each position coordinate stored in the instance. By default, the rotation rate vectors will be in the navigation frame basis.

Parameters:

Name Type Description Default
sensor_frame bool

If True, return the Earth rate in the sensor (body) frame basis.

 False

Returns:

Name Type Description
earth_rate NDArray

Earth rate vectors at each position.

gravity 

gravity(*, sensor_frame: bool = False) -> NDArray

Return Earth's gravity.

Gravity will be an array of vectors, one for each position coordinate stored in the instance. By default, the gravity vectors will be in the navigation frame basis.

Parameters:

Name Type Description Default
sensor_frame bool

If True, return the gravity in the sensor (body) frame basis.

 False

Returns:

Name Type Description
gravity NDArray

Gravity vectors at each position.

angular_rate 

angular_rate(*, navigation_frame: bool = False) -> NDArray

Return a numerical estimate of angular velocity.

Estimates the angular velocity of the sensor (body) frame with respect to the navigation frame by numerical differences of the attitude. The angular velocity is returned in the sensor (body) frame basis.

Parameters:

Name Type Description Default
navigation_frame bool

If True, return the angular velocity vectors in the navigation frame basis.

 False

Returns:

Name Type Description
angular_velocity NDArray

Angular velocity vectors.

inertial_angular_rate 

inertial_angular_rate(
    *, navigation_frame: bool = False
) -> NDArray

Return an estimate of angular velocity w.r.t. inertial space.

Estimates the angular velocity of the sensor (body) frame with respect to inertial space by numerical differences of the attitude compensated for Earth's rotation. The angular velocity is returned in the sensor (body) frame basis.

Parameters:

Name Type Description Default
navigation_frame bool

If True, return the angular velocity vectors in the navigation frame basis.

 False

Returns:

Name Type Description
angular_velocity NDArray

Angular velocity vectors.

specific_force 

specific_force(
    *, navigation_frame: bool = False
) -> NDArray

Return a numerical estimate of specific force.

Estimates the specific force by numerical differences of the velocity, compensated for gravity and, if applicable, Earth's rotation. The specific force is returned in the sensor (body) frame basis.

Parameters:

Name Type Description Default
navigation_frame bool

If True, return the specific force vectors in the navigation frame basis.

 False

Returns:

Name Type Description
specific_force NDArray

Specific force vectors.

interpolate 

interpolate(
    time: ArrayLike, method: Interpolator = LINEAR
) -> Self

Interpolate poses at the input times.

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

Interpolation is performed using the underlying Lie manifold for the pose elements (attitude, position, and velocity). Gravity and earth rate are recalculated at the interpolated poses.

Example

A GlobalPose instance constructed with 2 poses 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:

Name Type Description Default
time ArrayLike

Array of unique, strictly increasing times (or indices) corresponding to each desired output.

 required
method Interpolator

Interpolation method to use.

 LINEAR

Returns:

Name Type Description
pose Self

New class instance constructed from the input times and interpolated elements.