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.
`EarthRate`	Rotation rate model of Earth.
`Gravity`	Gravity model of Earth.
`GlobalPose`	Pose (and velocity) with respect to Earth.

Coordinates ¶

Coordinates(
    xyz: ArrayLike | Translation,
    geodetic_datum: GeodeticDatum,
    topocentric_datum: TopocentricDatum | None = None,
    time: ArrayLike | 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.

Internally, coordinates are stored in Earth-centered, Earth-fixed (ECEF, also known as geocentric Cartesian) format.

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_local`	Construct an instance from an array of local Cartesian coordinates.
`from_spherical`	Construct an instance from an array of spherical coordinates.
`from_ellipsoidal_harmonic`	Construct an instance from ellipsoidal harmonic 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.

Attributes:

Name	Type	Description
`num_coordinates`	`int`	The number of coordinates stored in the instance.
`num_elements`	`int`	The number of coordinates stored in the instance.
`time`	`NDArray \| None`	Array of times corresponding to each coordinate.
`geodetic_datum`	`GeodeticDatum`	The geodetic datum associated with the stored coordinates.
`topocentric_datum`	`TopocentricDatum \| None`	The topocentric datum associated with 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.

time `property` ¶

time: NDArray | None

Array of times corresponding to each coordinate.

geodetic_datum `property` ¶

geodetic_datum: GeodeticDatum

The geodetic datum associated with the stored coordinates.

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_local `classmethod` ¶

from_local(
    *,
    position: ArrayLike,
    origin: ArrayLike,
    initial_yaw: float,
    local_datum: LocalDatum,
    time: ArrayLike | None = None,
) -> Self

Construct an instance from an array of local Cartesian coordinates.

Local coordinates can be converted to topocentric coordinates with the addition of initial yaw (or heading) angle; initial latitude and longitude; and initial altitude (optional). The local Cartesian coordinates are assumed level (relative to local gravity).

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.

Initial yaw angle

The initial yaw angle rotates around the z-axis of the topocentric coordinates to align the x-y axes of both systems. For topocentric NED and local FRD axis-ordering, it is equivalent to the heading angle relative to North.

Parameters:

Name	Type	Description	Default
`position`	`ArrayLike`	Local cartesian coordinates or an array of coordinates.	required
`origin`	`ArrayLike`	Origin of the local frame in geodetic coordinates (latitude, longitude, altitude). See from_geodetic for geodetic coordinate conventions.	required
`initial_yaw`	`float`	Yaw (or heading) angle (in radians) that rotates the topocentric coordinates (NED or ENU) into the local coordinates (FRD or FLU respectively).	required
`local_datum`	`LocalDatum`	A datum describing the local coordinates axis order.	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.

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: str,
    to_coordinates: str,
    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`	`str`	The source coordinate system. One of: "geodetic", "ecef", "topocentric", "spherical", or "ellipsoidal_harmonic"	required
`to_coordinates`	`str`	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.

EarthRate ¶

EarthRate(coordinates: Coordinates)

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 initialized with a Coordinates instance and methods return the value of Earth's rotation rate in the local basis of various frames at those coordinates. Calculations will use the datum of the Coordinates instance.

Returning the fixed magnitude of Earth's rotation rate is also supported.

Methods:

Name	Description
`from_coordinates`	Construct an instance from a set of coordinates.
`magnitude`	Return the magnitude of Earth's rotation rate.
`as_geodetic`	Return the earth rate vector in geodetic coordinates.
`as_ecef`	Return the earth rate vector in ECEF coordinates.
`as_topocentric`	Return the earth rate vector in topocentric coordinates.
`as_spherical`	Return the earth rate vector in geocentric spherical coordinates.
`as_ellipsoidal_harmonic`	Return the earth rate vector in ellipsoidal harmonic coordinates.

from_coordinates `classmethod` ¶

from_coordinates(coordinates: Coordinates) -> Self

Construct an instance from a set of coordinates.

Parameters:

Name	Type	Description	Default
`coordinates`	`Coordinates`	A Coordinates instance.	required

Returns:

Name	Type	Description
`earth_rate`	`Self`	An EarthRate instance.

magnitude ¶

magnitude() -> float

Return the magnitude of Earth's rotation rate.

The standard value of Earth's rotation rate depends on the geodetic datum in use. This function returns the value specified in the datum of the coordinates that initialize the instance. This defaults to the WGS84 value of 7.292115e-5 rad/s.

Returns:

Name	Type	Description
`earth_rate`	`float`	Earth rate magnitude.

as_geodetic ¶

as_geodetic() -> NDArray

Return the earth rate vector in geodetic coordinates.

See additional documentation regarding geodetic coordinate conventions at: Coordinates.from_geodetic.

Returns:

Name	Type	Description
`earth_rate`	`NDArray`	Array of Earth rate vectors.

as_ecef ¶

as_ecef() -> NDArray

Return the earth rate vector in ECEF coordinates.

See additional documentation regarding ECEF coordinate conventions at: Coordinates.from_ecef.

Returns:

Name	Type	Description
`earth_rate`	`NDArray`	Array of Earth rate vectors.

as_topocentric ¶

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

Return the earth rate vector in topocentric coordinates.

See additional documentation regarding topocentric coordinate conventions at: Coordinates.from_topocentric.

Returns:

Name	Type	Description
`earth_rate`	`NDArray`	Array of Earth rate vectors.

as_spherical ¶

as_spherical() -> NDArray

Return the earth rate vector in geocentric spherical coordinates.

See additional documentation regarding geocentric spherical coordinate conventions at: Coordinates.from_spherical.

Returns:

Name	Type	Description
`earth_rate`	`NDArray`	Array of Earth rate vectors.

as_ellipsoidal_harmonic ¶

as_ellipsoidal_harmonic() -> NDArray

Return the earth rate vector in ellipsoidal harmonic coordinates.

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

Returns:

Name	Type	Description
`earth_rate`	`NDArray`	Array of Earth rate vectors.

Gravity ¶

Gravity(coordinates: Coordinates)

Gravity model of Earth.

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

Gravity is initialized with a Coordinates instance and subsequent calls to output methods will return the value of Earth's gravity at those coordinates. Calculations will use the datum of the Coordinates instance.

Standard (constant and approximate) values of gravity are also supported.

Methods:

Name	Description
`from_coordinates`	Construct an instance from a set of coordinates.
`standard_magnitude`	International standard gravity.
`standard`	Standard gravity in a topocentric frame.
`as_geodetic`	Return gravity vector in geodetic coordinates.
`as_ecef`	Return gravity vector in ECEF coordinates.
`as_topocentric`	Return gravity vector in topocentric coordinates.
`as_spherical`	Return gravity vector in geocentric spherical coordinates.
`as_ellipsoidal_harmonic`	Return gravity vector in ellipsoidal harmonic coordinates.

from_coordinates `classmethod` ¶

from_coordinates(coordinates: Coordinates) -> Self

Construct an instance from a set of coordinates.

Parameters:

Name	Type	Description	Default
`coordinates`	`Coordinates`	A Coordinates instance.	required

Returns:

Name	Type	Description
`gravity`	`Self`	A Gravity instance.

standard_magnitude `classmethod` ¶

standard_magnitude() -> float

International standard gravity.

The standard value of gravity is 9.80665 ms^-2 (See Standard [01] and equivalent international standards). This standard value should be used to convert units of "g".

Returns:

Name	Type	Description
`gravity`	`float`	Standard gravity magnitude.

standard `classmethod` ¶

standard(axis_order: str = 'NED') -> NDArray

Standard gravity in a topocentric frame.

International standard gravity in a topocentric (local-level) reference frame.

The standard value of gravity is 9.80665 ms^-2 (See Standard [01] and equivalent international standards). This function returns a vector in a topocentric reference frame with the given axis order. This standard value is approximately the value of gravity at 45 degrees latitude and 0 altitude. It should only be used in simple applications where a single global approximation is appropriate.

Parameters:

Name	Type	Description	Default
`axis_order`	`str`	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.

as_geodetic ¶

as_geodetic() -> NDArray

Return gravity vector in geodetic coordinates.

Return the gravity vector in the local basis of the geodetic coordinates.

See additional documentation regarding geodetic coordinate conventions at: Coordinates.from_geodetic.

Returns:

Name	Type	Description
`gravity`	`NDArray`	Array of gravity vectors.

as_ecef ¶

as_ecef() -> NDArray

Return gravity vector in ECEF coordinates.

See additional documentation regarding ECEF coordinate conventions at: Coordinates.from_ecef.

Returns:

Name	Type	Description
`gravity`	`NDArray`	Array of gravity vectors.

as_topocentric ¶

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

Return gravity vector in topocentric coordinates.

See additional documentation regarding topocentric coordinate conventions at: Coordinates.from_topocentric.

Parameters:

Name	Type	Description	Default
`datum`	`TopocentricDatum \| None`	A datum describing the origin and axis order of the topocentric coordinates.	`None`

Returns:

Name	Type	Description
`gravity`	`NDArray`	Array of gravity vectors.

as_spherical ¶

as_spherical() -> NDArray

Return gravity vector in geocentric spherical coordinates.

See additional documentation regarding spherical coordinate conventions at: Coordinates.from_spherical.

Returns:

Name	Type	Description
`gravity`	`NDArray`	Array of gravity vectors.

as_ellipsoidal_harmonic ¶

as_ellipsoidal_harmonic() -> NDArray

Return gravity vector in ellipsoidal harmonic coordinates.

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

Returns:

Name	Type	Description
`gravity`	`NDArray`	Array of gravity vectors.

GlobalPose ¶

GlobalPose(
    *,
    navigation_frame: str,
    attitude: Rotation,
    position: Coordinates | Translation,
    velocity: Vector | None,
    gravity: NDArray,
    earth_rate: NDArray,
)

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 more details about geodetic 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_attitude`	Return the attitude component of the GlobalPose instance.
`as_position`	Return the position component of the GlobalPose instance.
`as_velocity`	Return the velocity component of the GlobalPose instance.
`navigation_frame_rate`	Return Earth's rotation rate.
`gravity`	Return Earth's gravity.
`angular_rate`	Return a numerical estimate of angular velocity.
`specific_force`	Return a numerical estimate of specific force.

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`	Array of times corresponding to each pose.
`attitude`	`Rotation`	The attitude component of the pose.
`position`	`Coordinates \| Translation`	The position component of the pose.
`velocity`	`Vector \| None`	The velocity component of the pose.

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

Array of times corresponding to each pose.

attitude `property` ¶

attitude: Rotation

The attitude component of the pose.

position `property` ¶

position: Coordinates | Translation

The position component of the pose.

velocity `property` ¶

velocity: Vector | None

The velocity component of the pose.

from_ecef `classmethod` ¶

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

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

from_ecef(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
) -> 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, velocity = None must be specified if velocity is not available. 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`

Returns:

Name	Type	Description
`pose`	`Self`	A GlobalPose instance.

from_geodetic `classmethod` ¶

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

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

from_geodetic(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    datum: GeodeticDatum = WGS84,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
) -> 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, velocity = None must be specified if velocity is not available. Inputs can be specified as inertialsim class 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 output of gravity and 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`

Returns:

Name	Type	Description
`pose`	`Self`	A GlobalPose instance.

from_topocentric `classmethod` ¶

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

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

from_topocentric(
    *,
    attitude: Rotation | ArrayLike,
    position: Coordinates | ArrayLike,
    velocity: Vector | ArrayLike | None,
    datum: TopocentricDatum | None = None,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
) -> 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, velocity = None must be specified if velocity is not available. Inputs can be specified as inertialsim class 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`

Returns:

Name	Type	Description
`pose`	`Self`	A GlobalPose instance.

from_inertial `classmethod` ¶

from_inertial(
    *,
    attitude: Rotation,
    position: Translation,
    velocity: Vector | None,
    gravity: ArrayLike,
) -> Self

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

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

Construct a pose from inertial frame inputs.

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

Velocity inputs are optional, velocity = None must be specified if velocity is not available. Inputs can be specified as inertialsim class 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 inertial frame. If specified as an array, it must be in rotation matrix form.	required
`position`	`Translation \| 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
`gravity`	`ArrayLike`	The gravity vector at each position 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`

Returns:

Name	Type	Description
`pose`	`Self`	A GlobalPose instance.

from_local `classmethod` ¶

from_local(
    *, pose: Pose | ExtendedPose, gravity: ArrayLike
) -> Self

from_local(
    *,
    pose: Pose | ExtendedPose,
    origin: ArrayLike,
    initial_yaw: float,
    local_datum: LocalDatum,
) -> Self

from_local(
    *,
    attitude: Rotation,
    position: Translation,
    velocity: Vector | None,
    gravity: ArrayLike,
) -> Self

from_local(
    *,
    attitude: Rotation,
    position: Translation,
    velocity: Vector | None,
    origin: ArrayLike,
    initial_yaw: float,
    local_datum: LocalDatum,
) -> Self

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

from_local(
    *,
    attitude: ArrayLike,
    position: ArrayLike,
    velocity: ArrayLike | None,
    origin: ArrayLike,
    initial_yaw: float,
    local_datum: LocalDatum,
    time: ArrayLike,
    orthonormalize: bool = False,
) -> Self

from_local(
    *,
    pose: Pose | ExtendedPose | None = None,
    attitude: Rotation | ArrayLike | None = None,
    position: Translation | ArrayLike | None = None,
    velocity: Vector | ArrayLike | None = None,
    origin: ArrayLike | None = None,
    initial_yaw: float | None = None,
    local_datum: LocalDatum | None = None,
    gravity: ArrayLike | None = None,
    time: ArrayLike | None = None,
    orthonormalize: bool = False,
) -> 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 (level with respect to gravity).

If the origin, initial_yaw, and local_datum inputs are all supplied, the remaining inputs will be converted to topocentric coordinates and gravity and Earth's rotation will be fully accounted for. See from_topocentric. If all three inputs are not supplied, the others will be ignored.

Otherwise, the gravity input must be supplied as a vector in the local frame. Earth's rotation will be ignored. Standard gravity can be used or a custom value can be supplied.

See Coordinates.from_local for more details on local frame conventions.

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`	`Translation \| 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`
`origin`	`ArrayLike \| None`	Geodetic coordinates of the local frame origin (latitude, longitude, ellipsoidal altitude). Must be supplied with `initial_yaw` and `local_datum`.	`None`
`initial_yaw`	`float \| None`	Yaw angle (radians) that rotates the navigation (world) frame xy-axes to alignment with the initial sensor (body) frame xy-axes. Must be supplied with `origin` and `local_datum`.	`None`
`local_datum`	`LocalDatum \| None`	The local datum associated with the inputs, specifying either a forward-right-down (FRD) or forward-left-up (FLU) axis ordering convention. The initial_yaw input is with respect to the chosen convention (heading positive clockwise from North in NED convention or yaw positive counter-clockwise from East in ENU convention). Must be supplied with `origin` and `initial_yaw`.	`None`
`gravity`	`ArrayLike \| None`	The gravity vector in local coordinates. Ignored if the `origin`, `initial_yaw`, and `local_datum` inputs are all supplied.	`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`

Returns:

Name	Type	Description
`pose`	`Self`	A GlobalPose instance.

as_attitude ¶

as_attitude() -> Rotation

Return the attitude component of the GlobalPose instance.

Returns:

Name	Type	Description
`attitude`	`Rotation`	A Rotation instance.

as_position ¶

as_position() -> Coordinates | Translation

Return the position component of the GlobalPose instance.

Returns:

Name	Type	Description
`position`	`Coordinates \| Translation`	A Coordinates or Translation instance.

as_velocity ¶

as_velocity() -> Vector | None

Return the velocity component of the GlobalPose instance.

Returns:

Name	Type	Description
`velocity`	`Vector \| None`	A Vector instance.

navigation_frame_rate ¶

navigation_frame_rate(frame: str = 'navigation') -> NDArray

Return Earth's rotation rate.

The rotation rate will be an array of vectors, one for each position coordinate stored in the instance. The rotation rate vectors will be in the coordinate frame specified in the input. The frame input must be one of "navigation" (world) or "sensor" (body).

Parameters:

Name	Type	Description	Default
`frame`	`str`	The frame to return the Earth rate vectors in.	`'navigation'`

Returns:

Name	Type	Description
`earth_rate`	`NDArray`	Earth rate vectors at each position.

gravity ¶

gravity(frame: str = 'navigation') -> NDArray

Return Earth's gravity.

Gravity will be an array of vectors, one for each position coordinate stored in the instance. The gravity vectors will be in the coordinate frame specified in the input. The frame input must be one of "navigation" (world) or "sensor" (body).

Parameters:

Name	Type	Description	Default
`frame`	`str`	The frame to return the gravity vectors in.	`'navigation'`

Returns:

Name	Type	Description
`gravity`	`NDArray`	Gravity vectors at each position.

angular_rate ¶

angular_rate(frame: str = 'sensor') -> NDArray

Return a numerical estimate of angular velocity.

Calculates the angular velocity by a numerical forward difference of the attitude. The angular velocity is assumed piecewise constant between samples.

The frame input must be one of "sensor" (body) or "navigation" (world).

The output will have length 1 less than the number of poses stored in the instance.

Parameters:

Name	Type	Description	Default
`frame`	`str`	The frame to return the angular velocity vectors in.	`'sensor'`

Returns:

Name	Type	Description
`angular_velocity`	`NDArray`	Angular velocity vectors at the first N-1 poses.

specific_force ¶

specific_force(
    frame: str = "sensor", smoother: Callable | None = None
) -> NDArray

Return a numerical estimate of specific force.

Calculates the specific force by a numerical forward difference of the velocity (if available) or a double difference of the position and compensation of the gravity components. The specific force is assumed piecewise constant (in the sensor frame) between samples.

The frame input must be one of "sensor" (body) or "navigation" (world).

The output will have length 1 less than the number of poses stored in the instance.

Parameters:

Name	Type	Description	Default
`frame`	`str`	The frame to return the specific force vectors in.	`'sensor'`
`smoother`	`Callable \| None`	A smoothing function that will be applied to the numerical difference of position (only applied if the instance does not contain velocity data).	`None`

Returns:

Name	Type	Description
`specific_force`	`NDArray`	Specific force vectors at the first N-1 poses.

inertialsim.geodesy ¶

Coordinates ¶

num_coordinates property ¶

num_elements property ¶

time property ¶

geodetic_datum property ¶

topocentric_datum property ¶

from_geodetic classmethod ¶

from_ecef classmethod ¶

from_topocentric classmethod ¶

from_local classmethod ¶

from_spherical classmethod ¶

from_ellipsoidal_harmonic classmethod ¶

as_geodetic ¶

as_ecef ¶

as_topocentric ¶

as_spherical ¶

as_ellipsoidal_harmonic ¶

rigid_transform ¶

EarthRate ¶

from_coordinates classmethod ¶

magnitude ¶

as_geodetic ¶

as_ecef ¶

as_topocentric ¶

as_spherical ¶

as_ellipsoidal_harmonic ¶

Gravity ¶

from_coordinates classmethod ¶

standard_magnitude classmethod ¶

standard classmethod ¶

as_geodetic ¶

as_ecef ¶

as_topocentric ¶

as_spherical ¶

as_ellipsoidal_harmonic ¶

GlobalPose ¶

num_poses property ¶

num_elements property ¶

time property ¶

attitude property ¶

position property ¶

velocity property ¶

from_ecef classmethod ¶

from_geodetic classmethod ¶

from_topocentric classmethod ¶

from_inertial classmethod ¶

from_local classmethod ¶

as_attitude ¶

as_position ¶

as_velocity ¶

navigation_frame_rate ¶

gravity ¶

angular_rate ¶

specific_force ¶

num_coordinates `property` ¶

num_elements `property` ¶

time `property` ¶

geodetic_datum `property` ¶

topocentric_datum `property` ¶

from_geodetic `classmethod` ¶

from_ecef `classmethod` ¶

from_topocentric `classmethod` ¶

from_local `classmethod` ¶

from_spherical `classmethod` ¶

from_ellipsoidal_harmonic `classmethod` ¶

from_coordinates `classmethod` ¶

from_coordinates `classmethod` ¶

standard_magnitude `classmethod` ¶

standard `classmethod` ¶

num_poses `property` ¶

num_elements `property` ¶

time `property` ¶

attitude `property` ¶

position `property` ¶

velocity `property` ¶

from_ecef `classmethod` ¶

from_geodetic `classmethod` ¶

from_topocentric `classmethod` ¶

from_inertial `classmethod` ¶

from_local `classmethod` ¶