ijk2keplerian

Keplerian orbit elements using position and velocity vectors

Syntax

[a,ecc,incl,RAAN,argp,nu,truelon,arglat,lonper] = ijk2keplerian(rijk, vijk)

[a,ecc,incl,RAAN,argp,nu,truelon,arglat,lonper] = ijk2keplerian(rijk, vijk,Name=Value)

Description

[a,ecc,incl,RAAN,argp,nu,truelon,arglat,lonper] = ijk2keplerian(rijk, vijk) calculates Keplerian orbit elements for given position and velocity vectors in the geocentric equatorial coordinate system.

[a,ecc,incl,RAAN,argp,nu,truelon,arglat,lonper] = ijk2keplerian(rijk, vijk,Name=Value) specifies additional options using one or more name-value arguments.

Examples

Convert IJK Position and Velocity

This example shows how to convert the geocentric equatorial coordinate system (IJK) position and velocity to Keplerian orbital elements.

r_ijk = [-2981784 5207055 3161595];
v_ijk = [-3384 -4887 4843];
[a, ecc, incl, RAAN, argp, nu, truelon, arglat, lonper] =...
ijk2keplerian(r_ijk, v_ijk)

a = 
6.7845e+06

ecc = 
9.1950e-04

incl = 
51.7528

RAAN = 
95.2570

argp = 
106.4005

nu = 
290.0096

truelon = 
NaN

arglat = 
NaN

lonper = 
NaN

Input Arguments

rijk — Position component

3-by-1 array | 3-by-n array

Geocentric equatorial position components, specified as a 3-by-1 array or 3-by-n array, in meters. This argument does not support scalar expansion.

Data Types: double

vijk — Velocity component

3-by-1 array | 3-by-n array

Geocentric equatorial velocity components, specified as a 3-by-1 array or 3-by-n array, in m/s. This argument does not support scalar expansion.

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: Action='Warning' displays a warning in the command window indicating that rijk and vijk are parallel or orbit is parabolic or hyperbolic.

CentralBody — Celestial body around which spacecraft orbits

Earth (default) | Moon | Mercury | Venus | Mars | Jupiter | Saturn | Uranus | Neptune | Sun

Celestial body around which the spacecraft orbits, specified as one of Earth, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, or Sun.

Dependencies

You can specify this name-value pair if you leave 'GravitationalParameter' unspecified.

Data Types: string

GravitationalParameter — Gravitational parameter for a custom central body

3.986e14 (default) | positive scalar

Gravitational parameter for a custom central body, specified as a positive scalar.

Dependencies

You can specify this name-value pair if you leave CentralBody unspecified.

Data Types: double

Action — Function behavior

'Warning' (default) | 'None' | 'Error'

Function behavior when rijk and vijk are parallel or if orbit is parabolic or hyperbolic.

Value	Description
'None'	Does not display warning or error. If rijk and vijk are parallel, all outputs are set to NaN. If orbit is parabolic, semimajor axis output a is set to periapsis radius.
'Warning'	Warning in the MATLAB® Command Window indicating rijk and vijk are parallel or orbit is parabolic or hyperbolic. If warning only applies to a subset of inputs, the first input index where the warning applies is displayed.
'Error'	Error in the MATLAB Command Window indicating rijk and vijk are parallel or orbit is parabolic or hyperbolic. If error only applies to a subset of inputs, the first input index where the error applies is displayed.

Tolerance — Tolerance

1e-12 (default) | scalar

Tolerance for orbit circular or parabolic orbit eccentricity, or equatorial orbit inclination, in radians, specified as a scalar. Use this Tolerance name-value argument to specify a tolerance for orbit circular or parabolic eccentricity, or equatorial inclination.

The ijk2keplerian supports these specific orbit trajectories with eccentricity and inclination values:

• circular — ecc is 0.

• parabolic — ecc is 1.

• equatorial — incl is 0 or 180 degrees.

Example: 1e-12

Data Types: double

Output Arguments

a — Semimajor axis

scalar | 1-by-n array

Semimajor axis (half of the longest diameter) of the orbit, returned as a scalar or 1-by-n array in meters.

When the orbit is parabolic, ecc is 1, this argument returns the orbit periapsis radius.

Data Types: double

ecc — Orbit eccentricity

scalar value greater than or equal to 0 | 1-by-n array

Orbit eccentricity (deviation of orbital curve from circular), returned as a scalar or 1-by-n array.

Data Types: double

incl — Inclination

scalar value from 0 to 180 | 1-by-n array

Inclination (tilt angle) of the orbit, returned as a scalar or 1-by-n array, in degrees.

Data Types: double

RAAN — Right ascension of ascending node

scalar value from 0 to 360 | 1-by-n array

Angle in the equatorial plane from the x-axis to the location of the ascending node (point at which the satellite crosses the equator from south to north), returned as a scalar or 1-by-n array, in degrees.

Data Types: double

argp — Angle between spacecraft ascending node and periapsis

scalar value from 0 to 360 | 1-by-n array

Angle between the spacecraft ascending node and periapsis (closest point of orbit to Earth), returned as a scalar or 1-by-n array, in degrees.

Data Types: double

nu — Angle between periapsis and current position of spacecraft

scalar value from 0 to 360 | 1-by-n array

Angle between periapsis and current position of spacecraft, returned as a scalar or 1-by-n array, in degrees.

Data Types: double

truelon — Angle between x-axis and spacecraft position vector

scalar value from 0 to 360 | 1-by-n array

Angle between the x-axis and spacecraft position vector, returned as a scalar or 1-by-n array, in degrees.

Data Types: double

arglat — Angle between ascending node and spacecraft position vector

scalar value from 0 to 360 | 1-by-n array

Angle between the ascending node and the spacecraft position vector, returned as a scalar or 1-by-n array, in degrees.

Data Types: double

lonper — Angle between x-axis and eccentricity vector

scalar value from 0 to 360 | 1-by-n array

Angle between the x-axis and the eccentricity vector, returned as a scalar or 1-by-n array, in degrees.

Data Types: double

More About

Gravitational Parameter, Equatorial Radius, and Rotation Rate of Central Bodies

Gravitational parameter, equatorial radius, and rotation rate of celestial bodies are essential parameters for characterizing the physical and dynamical properties of planets and other astronomical objects and play a crucial role in celestial mechanics and astrodynamics.

Gravitational Parameter (μ) — The gravitational parameter μ is the product of the gravitational constant (G) and the mass (M) of the central body.

Equatorial Radius — The equatorial radius of a planet is the distance from the center of the planet to its equator, in m. It is a measure of the size of the planet and is larger than the polar radius due to the rotation of the planet, which causes a bulging effect at the equator. This phenomenon is known as equatorial bulge or oblateness.

Rotation Rate — The rotation rate of a planet refers to how quickly the planet spins around its own axis. It is measured using the angular velocity, which is the rate at which the planet rotates, measured in radians per second or degrees per hour. The rotation rate affects various planetary phenomena, including day and night cycles, weather patterns, and the shape of the planet (due to centrifugal forces).

The values of these three parameters for the celestial bodies included in the Aerospace Toolbox are listed in this table.

Planetary Data

Central Body	Gravitational Parameter (m³/s²)	Equatorial Radius (m)	Rotation Rate (rad/s)
Earth	3.986004418e14	6.378137e6	7.292115146706979e-5
Moon	4.902801076e12	1.7382e6	2.66166e-6
Sun	1.327124400179870e20	6.96000e8	2.8653291e-6
Mercury	2.20320804864179e13	2.4397e6	1.24001e-6
Venus	3.248585988264598e14	6.0518e6	-2.99244942e-7
Mars	4.2828314258067e13	3.3962e6	7.088218e-5
Jupiter	1.267127678577960e17	7.1492e7	1.7585336e-4
Saturn	3.794062606113729e16	6.0268e7	1.6378499e-4
Uranus	5.794549007071873e15	2.5559e7	-1.0123719e-4
Neptune	6.836534063879261e15	2.4764e7	1.08338e-4

References

[1] Vallado, D. A. Fundamentals of Astrodynamics and Applications. alg. 5. McGraw-Hill, 1997.

[2] NASA. "Planetary Fact Sheet." NASA National Space Science Data Center. https://nssdc.gsfc.nasa.gov/planetary/factsheet/.

Version History

Introduced in R2019a

R2025a: ijk2keplerian Function Changes

The ijk2keplerian function has these updates:

• ijk2keplerian now includes options for modifying the gravitational parameter (μ).

  To support this capability, the function has three new name-value arguments: CentralBody, GravitationalParameter, and Action.

• ijk2keplerian now accepts vector inputs and returns vector outputs. This function continues to support scalar inputs and outputs.

• The ijk2keplerian function now better supports circular, parabolic, and equatorial orbits using a tolerance value. To specify a tolerance for orbit circular or parabolic eccentricity, or equatorial inclination, use the new Tolerance name-value argument. In releases prior to R2025a, the tolerance value was 1e-12.

• The ijk2keplerian function now outputs the orbit periapsis radius as the value for the semi-major axis a when the orbit is parabolic, ecc is 1.