eci2ecef

Position, velocity, and acceleration vectors in Earth-centered Earth-fixed (ECEF) coordinate system

Syntax

[r_ecef,v_ecef,a_ecef] = eci2ecef(utc,r_eci,v_eci,a_eci)

[r_ecef,v_ecef,a_ecef] = eci2ecef(utc,r_eci,v_eci,a_eci,Name,Value)

Description

[r_ecef,v_ecef,a_ecef] = eci2ecef(utc,r_eci,v_eci,a_eci) calculates position, velocity, and acceleration vectors in Earth-centered Earth-fixed (ECEF) coordinate system for given position, velocity, and acceleration vectors in the Earth-centered inertial (ECI) coordinate system at a specific Coordinated Universal Time (UTC). For more information on the Earth-centered Earth-fixed coordinate system, see Algorithms.

[r_ecef,v_ecef,a_ecef] = eci2ecef(utc,r_eci,v_eci,a_eci,Name,Value) calculates the position, velocity, and acceleration vectors at a higher precision using Earth orientation parameters. If Earth orientation parameters are not specified, the function sets them to 0.

Examples

Convert ECI Position and Velocity to ECEF

This example shows how to convert ECI position and velocity to ECEF at 12:00 on January 4, 2019.

r_eci = [-2981784 5207055 3161595];
v_eci = [-3384 -4887 4843];
utc = [2019 1 4 12 0 0];
[r_ecef, v_ecef] = eci2ecef(utc, r_eci, v_eci)

r_ecef = 3×1
106 ×

   -5.7627
   -1.6827
    3.1560

v_ecef = 3×1
103 ×

    3.8319
   -4.0243
    4.8370

Convert ECI Position to ECEF Including Polar Motion Effects

This example shows how to convert ECI position to ECEF at 12:00 on January 4, 2019 including effects of polar motion.

r_eci = [-2981784 5207055 3161595];
utc = [2019 1 4 12 0 0];
mjd = mjuliandate(utc);
pm = polarMotion(mjd, 'action', 'none')*180/pi;
r_ecef = eci2ecef(utc, r_eci, 'pm', pm)

r_ecef = 3×1
106 ×

   -5.7627
   -1.6827
    3.1560

Convert ECI Position to ECEF Using datetime Arrays

This example shows how to convert ECI position and velocity to ECEF at 12:00 on January 4, 2019 with datetime array utcDT.

r_eci = [-2981784 5207055 3161595];
v_eci = [-3384 -4887 4843];
utcDT = datetime(2019, 1, 4, 12, 0, 0)

utcDT = datetime
   04-Jan-2019 12:00:00

[r_ecef, v_ecef] = eci2ecef(utcDT, r_eci, v_eci)

r_ecef = 3×1
106 ×

   -5.7627
   -1.6827
    3.1560

v_ecef = 3×1
103 ×

    3.8319
   -4.0243
    4.8370

Input Arguments

utc — Coordinated Universal Time

scalar | 1-by-6 array | 1-by-6 matrix | scalar datetime array

Coordinated Universal Time (UTC) specified as one of these:

• 1-by-6 array of UTC values in the order year, month, day, hour, minutes, and seconds:

  Time Value	Enter
  Year	Double value that is a whole number greater than 1, such as 2013.
  Month	Double value that is a whole number greater than 0, within the range 1 to 12.
  Day	Double value that is a whole number greater than 0, within the range 1 to 31.
  Hour	Double value that is a whole number greater than 0, within the range 1 to 24.
  Minute and second	Double value that is a whole number greater than 0, within the range 1 to 60.

• Scalar datetime array. To create the array, use the datetime function.

Example: [2000 1 12 4 52 12.4] is a one row-by-6 column array of UTC values.

Data Types: double

r_eci — Position components

3-by-1 array

ECI position components, specified as a 3-by-1 array.

Data Types: double

v_eci — Velocity components

3-by-1 array

ECI velocity components, specified as a 3-by-1 array.

Data Types: double

a_eci — Acceleration components

3-by-1 array

ECI acceleration components, specified as a 3-by-1 array.

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: 'dUT1',0.234

dAT — Difference between TAI and UTC

0 (default) | scalar

Difference between International Atomic Time (TAI) and UTC, specified as a scalar, in seconds.

Example: 32

Data Types: double

dUT1 — Difference between UTC and Universal Time

0 (default) | scalar

Difference between UTC and Universal Time (UT1), specified as a scalar, in seconds.

Example: 0.234

Data Types: double

pm — Polar displacement

array of zeroes (default) | 1-by-2 array

Polar displacements due to the motion of Earth crust along the x- and y-axis, in degrees.

Tip

To calculate the displacement, use the polarMotion function.

Example: pm = polarMotion(mjd, 'action', 'none')*180/pi;

Data Types: double

dCIP — Adjustment to the CIP

1-by-2 array

Adjustment to the location of the Celestial Intermediate Pole (CIP), in degrees, specified as a comma-separated pair consisting of dCIP and an M-by-2 array. This location (dDeltaX, dDeltaY) is along the x- and y- axes. By default, this function assumes a 1-by-2 array of zeroes.

For historical values, see the International Earth Rotation and Reference Systems Service Web site (https://www.iers.org) and navigate to Data/Products/Tools > Earth orientation data.

• M-by-2 array

  Specify a M-by-2 array of location adjustment values, where M is the number of direction cosine or transformation matrices to be converted. Each row corresponds to one set of dDeltaX and dDeltaY values.

Example: [-0.2530e-6 -0.0188e-6]

Data Types: double

lod — Excess length of day

0 (default) | scalar

Excess length of day (difference between astronomically determined duration of day and 86400 SI seconds), specified as a scalar, in seconds.

Example: 32

Data Types: double

Output Arguments

r_ecef — Position components

3-by-1 array

ECEF position components, specified as a 3-by-1 array.

v_ecef — Velocity components

3-by-1 array

ECEF velocity components, specified as a 3-by-1 array.

a_ecef — Acceleration components

3-by-1 array

ECEF acceleration components, specified as a 3-by-1 array.

Algorithms

The eci2ecef function uses these Earth-centric coordinate systems:

• Earth Centered Inertial Frame (ECI) — The inertial frame used is the International Celestial Reference Frame (ICRF). This frame can be treated as equal to the ECI coordinate system realized at J2000 (Jan 1 2000 12:00:00 TT). For more information, see ECI and ECEF Coordinates.

• Earth-centered Earth-fixed Frame (ECEF) — The fixed-frame used is the International Terrestrial Reference Frame (ITRF). This reference frame is realized by the IAU2000/2006 reduction from the ICRF coordinate system. For more information, see ECEF Coordinates.

References

[1] Vallado, D. A. Fundamentals of Astrodynamics and Applications. alg. 4. New York: McGraw-Hill, 1997.

[2] Gottlieb, R. G., "Fast Gravity, Gravity Partials, Normalized Gravity, Gravity Gradient Torque and Magnetic Field: Derivation, Code and Data," Technical Report NASA Contractor Report 188243, NASA Lyndon B. Johnson Space Center, Houston, Texas, February 1993.

[3] Konopliv, A. S., S. W. Asmar, E. Carranza, W. L. Sjogen, D. N. Yuan., "Recent Gravity Models as a Result of the Lunar Prospector Mission, Icarus", Vol. 150, no. 1, pp 1–18, 2001.

[4] Lemoine, F. G., D. E. Smith, D.D. Rowlands, M.T. Zuber, G. A. Neumann, and D. S. Chinn, "An improved solution of the gravity field of Mars (GMM-2B) from Mars Global Surveyor", Journal Of Geophysical Research, Vol. 106, No. E10, pp 23359-23376, October 25, 2001.

[5] Seidelmann, P.K., Archinal, B.A., A’hearn, M.F. et al. "Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: 2006." Celestial Mech Dyn Astr 98, 155–180 (2007).

Version History

Introduced in R2019a