keplerian2ijk

R2026b

Position and velocity vectors in geocentric equatorial coordinate system of celestial bodies using Keplerian orbit elements

Syntax

[rijk,vijk] = keplerian2ijk(a,ecc,incl,RAAN,argp,nu)

[rijk,vijk] = keplerian2ijk(___,Name=Value)

Description

[rijk,vijk] = keplerian2ijk(a,ecc,incl,RAAN,argp,nu) calculates the position and velocity vectors in a celestial body-centered equatorial coordinate system (IJK) for given Keplerian orbit elements of noncircular, inclined orbits.

[rijk,vijk] = keplerian2ijk(___,Name=Value) specifies orbit element properties using one or more name-value pair arguments. For example, 'truelon','17' specifies the angle between the x-axis and spacecraft position vector. Specify name-value pair arguments after all other input arguments.

Examples

Convert Keplerian Orbital Elements

This example shows how to convert Keplerian orbital elements to a celestial body-centered equatorial coordinate system (IJK) position and velocity.

a = 6786230;
ecc = .01;
incl = 52;
RAAN = 95;
argp = 93;
nu = 300;
[r_ijk, v_ijk] = keplerian2ijk(a, ecc, incl, RAAN, argp, nu)

r_ijk = 3×1
106 ×

   -2.7489
    5.4437
    2.8977

v_ijk = 3×1
103 ×

   -3.5694
   -4.5794
    5.0621

Convert Keplerian Orbital Elements for Equatorial Orbit

This example shows how to convert Keplerian orbital elements to a celestial body-centered equatorial coordinate system (IJK) position and velocity for equatorial orbit.

a = 6786230;
ecc = .1;
incl = 0;
RAAN = 95;
argp = 93;
nu = 300;
lonper = 45;
[r_ijk, v_ijk] = keplerian2ijk(a,ecc,incl,RAAN,argp,nu,lonper=lonper)

r_ijk = 3×1
106 ×

    6.1804
   -1.6560
         0

v_ijk = 3×1
103 ×

    1.4489
    7.9848
         0

Input Arguments

a — Semimajor axis

scalar | 1-by-n array | n-by-1 array

Semimajor axis (half of the longest diameter) of the orbit, specified as a scalar, 1-by-n array, or n-by-1 array, in meters. This argument supports scalar expansion.

Data Types: double

ecc — Orbit eccentricity

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

Orbit eccentricity (deviation of orbital curve from circular), specified as a scalar, 1-by-n array, or n-by-1 array. This argument supports scalar expansion.

Data Types: double

incl — Inclination

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

Inclination (tilt angle) of the orbit, specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion.

Data Types: double

RAAN — Right ascension of ascending node

0 (default) | scalar value from 0 to 360 | 1-by-n array | n-by-1 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, specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion. The function does not use this value for equatorial orbits.

Data Types: double

argp — Angle between spacecraft ascending node and periapsis

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

Angle between the spacecraft ascending node and the periapsis (closest point of orbit to Earth), specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion. The function does not use this value for circular and equatorial orbits.

Data Types: double

nu — Angle between periapsis and current position of spacecraft

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

Angle between the periapsis and the current position of spacecraft, specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion. The function does not use this value for circular orbits.

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: 45

truelon — Angle between x-axis and spacecraft position vector

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

Angle between the x-axis and the spacecraft position vector, specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion. The function uses this value only for circular equatorial orbits (where eccentricity and inclination are zero).

Data Types: double

arglat — Angle between ascending node and spacecraft position vector

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

Angle between the ascending node and the spacecraft position vector, specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion. The function uses this value only for circular inclined orbits (where eccentricity is zero and inclination is nonzero).

Data Types: double

lonper — Angle between x-axis and eccentricity vector

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

Angle between the x-axis and the eccentricity vector, specified as a scalar, 1-by-n array, or n-by-1 array, in degrees. This argument supports scalar expansion. The function uses this value only for noncircular equatorial orbits (where eccentricity is nonzero and inclination is zero).

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 orbit is parabolic, semimajor axis output a is set to periapsis radius.
'Warning'	Warning in the MATLAB® Command Window indicating that the orbit is either 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 that the orbit is either parabolic or hyperbolic. If error only applies to a subset of inputs, the first input index where the error applies is displayed.

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

Output Arguments

rijk — Position component

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

Geocentric equatorial position components, returned as a 3-by-1 array or 3-by-n array, in meters.

vijk — Velocity component

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

Geocentric equatorial velocity components, returned as a 3-by-1 array or 3-by-n array, in m/s.

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.292115e-5
Moon	4.902801076e12	1.7381e6	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] NASA. "Planetary Fact Sheet." NASA National Space Science Data Center. Accessed June 30, 2026. https://nssdc.gsfc.nasa.gov/planetary/factsheet/.

[2] National Geospatial-Intelligence Agency. World Geodetic System 1984: Its Definition and Relationships with Local Geodetic Systems. Version 1.0.0. Department of Defense, July 8, 2014.

[3] Pavlis, N. K., S. A. Holmes, S. C. Kenyon, and J. K. Factor. "The Development and Evaluation of the Earth Gravitational Model 2008 (EGM2008)." Journal of Geophysical Research 117, B04406 (2012). doi:10.1029/2011JB008916.

Version History

Introduced in R2019a

R2026b: Standardized planetary constant values

Planetary constants for all supported central bodies are now standardized to WGS84, EGM2008, and NASA NSSDC reference values. You might see small numerical differences in results compared to previous releases.

R2025a: keplerian2ijk Function Changes

The keplerian2ijk function has these updates:

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

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

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