Cartesian Coordinates¶

Functions for working with Cartesian state vectors and conversions.

State Conversions¶

state_koe_to_eci `builtin` ¶

state_koe_to_eci(x_oe: Union[ndarray, Sequence], angle_format: AngleFormat, axis: int = -1) -> ndarray

Convert osculating orbital elements to Cartesian state.

Transforms a state vector from osculating Keplerian orbital elements to Cartesian position and velocity coordinates.

Parameters:

Name	Type	Description	Default
`x_oe`	`ndarray or list`	Osculating orbital elements `[a, e, i, RAAN, omega, M]` where `a` is semi-major axis (meters), `e` is eccentricity (dimensionless), `i` is inclination (radians or degrees), `RAAN` is right ascension of ascending node (radians or degrees), `omega` is argument of periapsis (radians or degrees), and `M` is mean anomaly (radians or degrees). Also accepts a batch of vectors with the 6 components along `axis` (for example shape `(n, 6)`).	required
`angle_format`	`AngleFormat`	Angle format for angular elements (`RADIANS` or `DEGREES`).	required
`axis`	`int`	The axis of `x_oe` along which the 6 components of a single vector lie; the remaining axes enumerate the batch. For a batch of shape `(n, 6)` the components lie along the last axis, so the default `-1` applies; a `(6, n)` column layout uses `axis=0`.	`-1`

Returns:

Type	Description
`ndarray`	numpy.ndarray: Cartesian state `[x, y, z, vx, vy, vz]` where position is in meters and velocity is in meters per second. For batched input the output takes the batch layout of `x_oe`.

Example

import brahe as bh
import numpy as np

# Orbital elements for a circular orbit
oe = np.array([7000000.0, 0.0, 0.0, 0.0, 0.0, 0.0])  # a, e, i, RAAN, omega, M
x_cart = bh.state_koe_to_eci(oe, bh.AngleFormat.RADIANS)
print(f"Cartesian state: {x_cart}")

state_eci_to_koe `builtin` ¶

state_eci_to_koe(x_cart: Union[ndarray, Sequence], angle_format: AngleFormat, axis: int = -1) -> ndarray

Convert Cartesian state to osculating orbital elements.

Transforms a state vector from Cartesian position and velocity coordinates to osculating Keplerian orbital elements.

Parameters:

Name	Type	Description	Default
`x_cart`	`ndarray or list`	Cartesian state `[x, y, z, vx, vy, vz]` where position is in meters and velocity is in meters per second. Also accepts a batch of vectors with the 6 components along `axis` (for example shape `(n, 6)`).	required
`angle_format`	`AngleFormat`	Angle format for output angular elements (`RADIANS` or `DEGREES`).	required
`axis`	`int`	The axis of `x_cart` along which the 6 components of a single vector lie; the remaining axes enumerate the batch. For a batch of shape `(n, 6)` the components lie along the last axis, so the default `-1` applies; a `(6, n)` column layout uses `axis=0`.	`-1`

Returns:

Type Description

ndarray

numpy.ndarray: Osculating orbital elements [a, e, i, RAAN, omega, M] where a is semi-major axis (meters), e is eccentricity (dimensionless), i is inclination (radians or degrees), RAAN is right ascension of ascending node (radians or degrees), omega is argument of periapsis (radians or degrees), and M is mean anomaly (radians or degrees). For batched input the output takes the batch layout of x_cart.

Example

import brahe as bh
import numpy as np

# Cartesian state vector
x_cart = np.array([7000000.0, 0.0, 0.0, 0.0, 7546.0, 0.0])  # [x, y, z, vx, vy, vz]
oe = bh.state_eci_to_koe(x_cart, bh.AngleFormat.RADIANS)
print(f"Orbital elements: a={oe[0]:.0f}m, e={oe[1]:.6f}, i={oe[2]:.6f} rad")

Arbitrary Central Body¶

state_koe_to_inertial_for_body `builtin` ¶

state_koe_to_inertial_for_body(x_oe: Union[ndarray, Sequence], central_body: CentralBody, angle_format: AngleFormat, axis: int = -1) -> ndarray

Convert osculating orbital elements referenced to a body's mean equator at J2000 to the equivalent Cartesian state in that body's ICRF-aligned inertial (BCI) frame. Inverse of state_inertial_to_koe_for_body.

Unlike state_koe_to_eci (whose elements are referenced to the ICRF axes), the inclination and RAAN here are measured against the body mean equator at J2000 (the plane normal to the body's IAU pole at J2000 TDB, x-axis at the ascending node of that equator on the ICRF equator - the standard IAU orientation convention (Archinal et al., "Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015", Celest Mech Dyn Astr 130, 22 (2018), https://doi.org/10.1007/s10569-017-9805-5); this ascending node is where z_ICRF x p_hat points, since that vector is perpendicular to both poles and hence lies in both equatorial planes). The output state is in the body-centered ICRF-aligned frame, so it composes directly with the body-fixed transforms (state_bci_to_bcbf-style) and with the numerical propagators, which integrate in that frame. CentralBody.Earth is an exact passthrough of state_koe_to_eci.

Parameters:

Name	Type	Description	Default
`x_oe`	`ndarray or list`	Osculating orbital elements `[a, e, i, RAAN, omega, M]` referenced to the body mean equator at J2000, where the semi-major axis is in meters and angles are in the given format. Also accepts a batch of vectors with the 6 components along `axis` (for example shape `(n, 6)`).	required
`central_body`	`CentralBody`	Central body (supplies the GM and the IAU pole / body-fixed frame).	required
`angle_format`	`AngleFormat`	Angle format for input angular elements (`RADIANS` or `DEGREES`).	required
`axis`	`int`	The axis of `x_oe` along which the 6 components of a single vector lie; the remaining axes enumerate the batch. For a batch of shape `(n, 6)` the components lie along the last axis, so the default `-1` applies; a `(6, n)` column layout uses `axis=0`.	`-1`

Returns:

Type	Description
`ndarray`	numpy.ndarray: Cartesian state `[x, y, z, vx, vy, vz]` in the body-centered ICRF-aligned frame. Units: (m; m/s) For batched input the output takes the batch layout of `x_oe`.

Raises:

Type	Description
`RuntimeError`	If `central_body` is a barycenter, has no positive GM, or is a `Custom` body without a pole / `fixed_frame`.

Example

import brahe as bh
import numpy as np

# A 90 deg polar orbit referenced to Mars's equator (not the ICRF pole)
oe = np.array([bh.R_MARS + 300e3, 0.01, 92.6, 45.0, 270.0, 0.0])
x_cart = bh.state_koe_to_inertial_for_body(oe, bh.CentralBody.Mars, bh.AngleFormat.DEGREES)

state_inertial_to_koe_for_body `builtin` ¶

state_inertial_to_koe_for_body(x_cart: Union[ndarray, Sequence], central_body: CentralBody, angle_format: AngleFormat, axis: int = -1) -> ndarray

Convert a Cartesian state in a body's ICRF-aligned inertial (BCI) frame to osculating orbital elements referenced to that body's mean equator at J2000.

Unlike state_eci_to_koe (whose elements are referenced to the ICRF axes), the inclination and RAAN here are measured against the body mean equator at J2000: the reference plane is normal to the body's IAU pole (alpha0, delta0) evaluated at J2000 TDB, with the x-axis at the ascending node of that equator on the ICRF equator - the standard IAU orientation convention (Archinal et al., "Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015", Celest Mech Dyn Astr 130, 22 (2018), https://doi.org/10.1007/s10569-017-9805-5). This ascending node is where z_ICRF x p_hat points: that vector is perpendicular to both poles, hence lies in both equatorial planes. This is the natural frame for polar / sun-synchronous / frozen orbits about the Moon, Mars, and other bodies whose spin pole is tilted relative to the ICRF pole. CentralBody.Earth is an exact passthrough of state_eci_to_koe. Inverse of state_koe_to_inertial_for_body.

Parameters:

Name	Type	Description	Default
`x_cart`	`ndarray or list`	Cartesian state `[x, y, z, vx, vy, vz]` in the body-centered ICRF-aligned frame (e.g. LCI for the Moon, MCI for Mars), position in meters and velocity in meters per second. Also accepts a batch of vectors with the 6 components along `axis` (for example shape `(n, 6)`).	required
`central_body`	`CentralBody`	Central body (supplies the GM and the IAU pole / body-fixed frame).	required
`angle_format`	`AngleFormat`	Angle format for output angular elements (`RADIANS` or `DEGREES`).	required
`axis`	`int`	The axis of `x_cart` along which the 6 components of a single vector lie; the remaining axes enumerate the batch. For a batch of shape `(n, 6)` the components lie along the last axis, so the default `-1` applies; a `(6, n)` column layout uses `axis=0`.	`-1`

Returns:

Type	Description
`ndarray`	numpy.ndarray: Osculating orbital elements `[a, e, i, RAAN, omega, M]` referenced to the body mean equator at J2000. For batched input the output takes the batch layout of `x_cart`.

Raises:

Type	Description
`RuntimeError`	If `central_body` is a barycenter, has no positive GM, or is a `Custom` body without a pole / `fixed_frame`.

Example

import brahe as bh
import numpy as np

# Cartesian state in the Moon-centered inertial (LCI) frame
x_cart = np.array([1837.4e3, 0.0, 0.0, 0.0, 1600.0, 0.0])
oe = bh.state_inertial_to_koe_for_body(x_cart, bh.CentralBody.Moon, bh.AngleFormat.RADIANS)

Cartesian Coordinates¶

State Conversions¶

state_koe_to_eci builtin ¶

state_eci_to_koe builtin ¶

Arbitrary Central Body¶

state_koe_to_inertial_for_body builtin ¶

state_inertial_to_koe_for_body builtin ¶

See Also¶

state_koe_to_eci `builtin` ¶

state_eci_to_koe `builtin` ¶

state_koe_to_inertial_for_body `builtin` ¶

state_inertial_to_koe_for_body `builtin` ¶