ECEF and ECI

ECEF and ECI

This package currently provides two models to transform reference systems: the IAU-76/FK5 and the IAU-2006/2010 (CIO approach). The following table lists the available coordinate frames and how they can be referenced in the functions that will be described later on.

ReferenceTypeCoordinate frame name
ITRF()ECEFInternational Terrestrial Reference Frame
PEF()ECEFPseudo-Earth Fixed reference frame
TIRS()ECEFTerrestrial Intermediate Reference System
MOD()ECIMean-Of-Date reference frame
TOD()ECITrue-Of-Data reference frame
GCRF()ECIGeocentric Celestial Reference Frame (GCRF)
J2000()ECIJ2000 reference frame
TEME()ECITrue Equator, Mean Equinox reference frame
CIRS()ECICeletial Intermediate Reference System
Note

ECEF stands for Earth-Centered, Earth-Fixed whereas ECI stands for Earth-Centered Inertial.

Warning

In all the functions that will be presented here, it is not possible yet to mix frames between the IAU-76/FK5 and IAU-2006/2010 models in the same call. Hence, if it is required to compute the rotation between frames in different models, then the recommended approach is to first compute the rotation from the origin frame to the ITRF or GCRF, and then compute the rotation from the ITRF or GCRF to the destination frame. However, this will only work for past dates since EOP data is required.

EOP Data

The conversions here sometimes requires additional data related to the Earth orientation. This information is provided by IERS (International Earth Rotation and Reference Systems Service). The SatelliteToolbox.jl has the capability to automatically download and parse the IERS EOP (Earth Orientation Parameters) data.

The function that will automatically download the files, store them in the file system, and parse the data is:

function get_iers_eop(data_type::Symbol = :IAU1980; force_download = false)

in which:

julia> eop_IAU1980 = get_iers_eop();
[ Info: Downloading file 'EOP_IAU1980.TXT' from 'https://datacenter.iers.org/data/latestVersion/223_EOP_C04_14.62-NOW.IAU1980223.txt'.

julia> eop_IAU2000A = get_iers_eop(:IAU2000A);
[ Info: Downloading file 'EOP_IAU2000A.TXT' from 'https://datacenter.iers.org/data/latestVersion/224_EOP_C04_14.62-NOW.IAU2000A224.txt'.

ECEF to ECEF

One ECEF frame can be converted to another one by the following function:

function rECEFtoECEF([T,] ECEFo, ECEFf, JD_UTC::Number, eop_data)

where it will be computed the rotation from the ECEF reference frame ECEFo to the ECEF reference frame ECEFf at the Julian Day [UTC] JD_UTC. The rotation description that will be used is given by T, which can be DCM or Quaternion. If T is omitted, then it defaults to DCM. The EOP data eop_data in this case is always necessary. Hence, the user must initialize it as described in the section EOP Data.

julia> rECEFtoECEF(PEF(), ITRF(), DatetoJD(1986,6,19,21,35,0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
  1.0          0.0         -4.3531e-7
 -6.30011e-13  1.0         -1.44727e-6
  4.3531e-7    1.44727e-6   1.0

julia> rECEFtoECEF(TIRS(), ITRF(), DatetoJD(1986,6,19,21,35,0), eop_IAU2000A)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
  1.0          3.08408e-11  -4.3531e-7
 -3.14708e-11  1.0          -1.44727e-6
  4.3531e-7    1.44727e-6    1.0

julia> rECEFtoECEF(Quaternion, PEF(), ITRF(), DatetoJD(1986,6,19,21,35,0), eop_IAU1980)
Quaternion{Float64}:
  + 0.9999999999997147 - 7.236343481310813e-7.i + 2.1765518308012794e-7.j + 0.0.k

julia> rECEFtoECEF(Quaternion, TIRS(), ITRF(), DatetoJD(1986,6,19,21,35,0), eop_IAU2000A)
Quaternion{Float64}:
  + 0.9999999999997146 - 7.236343481345639e-7.i + 2.176551830689726e-7.j + 1.5577911634233308e-11.k

ECI to ECI

One ECI frame can be converted to another ECI frame by one of the following functions:

function rECEFtoECI([T,] ECIo, ECIf, JD_UTC::Number [, eop_data])
function rECEFtoECI([T,] ECIo, JD_UTCo::Number, ECIf, JD_UTCf::Number [, eop_data])

where it will be computed compute the rotation from the ECI reference frame ECIo to another ECI reference frame ECIf. If the origin and destination frame contain only one of date frame, then the first signature is used and JD_UTC is the epoch of this frame. On the other hand, if the origin and destination frame contain two of date frame[1], e.g. TOD => MOD, then the second signature must be used in which JD_UTCo is the epoch of the origin frame and JD_UTCf is the epoch of the destination frame. The rotation description that will be used is given by T, which can be DCM or Quaternion. If T is omitted, then it defaults to DCM. The EOP data eop_data, as described in section EOP Data, is required in some conversions, as described in the following table.

[1]

TEME is an of date frame.

ModelECIoECIfEOP DataFunction Signature
IAU-76/FK5GCRFJ2000EOP IAU1980First
IAU-76/FK5GCRFMODEOP IAU1980First
IAU-76/FK5GCRFTODEOP IAU1980First
IAU-76/FK5GCRFTEMEEOP IAU1980First
IAU-76/FK5J2000GCRFEOP IAU1980First
IAU-76/FK5J2000MODNot requiredFirst
IAU-76/FK5J2000TODNot requiredFirst
IAU-76/FK5J2000TEMENot requiredFirst
IAU-76/FK5MODGCRFEOP IAU1980First
IAU-76/FK5MODJ2000Not requiredFirst
IAU-76/FK5MODTODNot requiredSecond
IAU-76/FK5MODTEMENot requiredSecond
IAU-76/FK5TODGCRFEOP IAU1980First
IAU-76/FK5TODJ2000Not requiredFirst
IAU-76/FK5TODMODNot requiredSecond
IAU-76/FK5TODTEMENot requiredSecond
IAU-76/FK5TEMEGCRFEOP IAU1980First
IAU-76/FK5TEMEJ2000Not requiredFirst
IAU-76/FK5TEMEMODNot requiredSecond
IAU-76/FK5TEMETODNot requiredSecond
IAU-2006/2010GCRFCIRSNot required¹First
IAU-2006/2010CIRSCIRSNot required¹Second

¹: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

Note

In this function, if EOP corrections are not provided, then MOD and TOD frames will be computed considering the original IAU-76/FK5 theory. Otherwise, the corrected frame will be used.

julia> rECItoECI(DCM, GCRF(), J2000(), DatetoJD(1986, 6, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
  1.0          -2.45469e-12   4.56602e-10
  2.45466e-12   1.0          -1.84455e-9
 -4.56602e-10   1.84455e-9    1.0

julia> rECItoECI(Quaternion, TEME(), GCRF(), DatetoJD(1986, 6, 19, 21, 35, 0), eop_IAU1980)
Quaternion{Float64}:
  + 0.9999986335698654 + 1.8300414020900853e-5.i + 0.0006653038276169474.j - 0.0015132396749411375.k

julia> rECItoECI(TOD(), DatetoJD(1986,6,19,21,35,0), TOD(), DatetoJD(1987,5,19,3,0,0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 1.0          -0.000224087  -9.73784e-5
 0.000224086   1.0          -5.79859e-6
 9.73797e-5    5.77677e-6    1.0

julia> rECItoECI(Quaternion, TOD(), JD_J2000, MOD(), JD_J2000, eop_IAU1980)
Quaternion{Float64}:
  + 0.9999999993282687 - 1.400220690336851e-5.i + 1.3473593746216003e-5.j - 3.107834312843103e-5.k

julia> rECItoECI(J2000(), TEME(), DatetoJD(1986,6,19,21,35,0))
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
  0.999995    0.0030265    0.00133055
 -0.00302645  0.999995    -3.86125e-5
 -0.00133066  3.45854e-5   0.999999

julia> rECItoECI(CIRS(), GCRF(), DatetoJD(1986,6,19,21,35,0), eop_IAU2000A)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 0.999999     3.88379e-8  -0.00133066
 7.18735e-9   1.0          3.45882e-5
 0.00133066  -3.45882e-5   0.999999

julia> rECItoECI(Quaternion, CIRS(), GCRF(), DatetoJD(1986,6,19,21,35,0), eop_IAU2000A)
Quaternion{Float64}:
  + 0.9999997785177528 + 1.7294102099105917e-5.i + 0.0006653310148723835.j + 7.912627369563795e-9.k

ECEF to ECI

One ECEF frame can be convert to one ECI frame using the following function:

function rECEFtoECI([T,] ECEF, ECI, JD_UTC::Number [, eop_data])

where it will be compute the rotation from the ECEF frame ECEF to the ECI frame ECI at the Julian Day [UTC] JD_UTC. The rotation description that will be used is given by T, which can be DCM or Quaternion. If it is omitted, then it defaults to DCM. The EOP data eop_data, as described in section EOP Data, is required in some conversions, as described in the following table.

ModelECIECEFEOP Data
IAU-76/FK5GCRFITRFEOP IAU1980
IAU-76/FK5J2000ITRFEOP IAU1980
IAU-76/FK5MODITRFEOP IAU1980
IAU-76/FK5TODITRFEOP IAU1980
IAU-76/FK5TEMEITRFEOP IAU1980
IAU-76/FK5GCRFPEFEOP IAU1980
IAU-76/FK5J2000PEFNot required¹
IAU-76/FK5MODPEFNot required¹
IAU-76/FK5TODPEFNot required¹
IAU-76/FK5TEMEPEFNot required¹
IAU-2006/2010CIRSITRFEOP IAU2000A
IAU-2006/2010GCRFITRFEOP IAU2000A
IAU-2006/2010CIRSTIRSNot required¹
IAU-2006/2010GCRFTIRSNot required¹ ²

¹: In this case, the Julian Time UTC will be assumed equal to Julian Time UT1 to compute the Greenwich Mean Sidereal Time. This is an approximation, but should be sufficiently accurate for some applications. Notice that, if EOP Data is provided, the Julian Day UT1 will be accurately computed.

²: In this case, the terms that account for the free-core nutation and time dependent effects of the Celestial Intermediate Pole (CIP) position with respect to the GCRF will not be available, reducing the precision.

Note

In this function, if EOP corrections are not provided, then MOD and TOD frames will be computed considering the original IAU-76/FK5 theory. Otherwise, the corrected frame will be used.

julia> rECEFtoECI(DCM, ITRF(), GCRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267      0.78518     -0.00132979
 -0.78518      -0.619267     3.33492e-5
 -0.000797313   0.00106478   0.999999

julia> rECEFtoECI(ITRF(), GCRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267      0.78518     -0.00132979
 -0.78518      -0.619267     3.33492e-5
 -0.000797313   0.00106478   0.999999

julia> rECEFtoECI(ITRF(), GCRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU2000A)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267      0.78518     -0.00132979
 -0.78518      -0.619267     3.33502e-5
 -0.000797312   0.00106478   0.999999

julia> rECEFtoECI(PEF(), J2000(), DatetoJD(1986, 06, 19, 21, 35, 0))
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619271      0.785176    -0.00133066
 -0.785177     -0.619272     3.45854e-5
 -0.000796885   0.00106622   0.999999

julia> rECEFtoECI(PEF(), J2000(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267      0.78518     -0.00133066
 -0.78518      -0.619267     3.45854e-5
 -0.000796879   0.00106623   0.999999

julia> rECEFtoECI(TIRS(), GCRF(), DatetoJD(1986, 06, 19, 21, 35, 0))
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619271      0.785176    -0.00133066
 -0.785177     -0.619272     3.45884e-5
 -0.000796885   0.00106623   0.999999

julia> rECEFtoECI(Quaternion, ITRF(), GCRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
Quaternion{Float64}:
  + 0.4363098936462618 - 0.0005909969666939257.i + 0.00030510511316206974.j + 0.8997962182293519.k

julia> rECEFtoECI(Quaternion, ITRF(), GCRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU2000A)
Quaternion{Float64}:
  + 0.4363098936309669 - 0.000590996988144556.i + 0.0003051056555230158.j + 0.8997962182365703.k

ECI to ECEF

One ECI frame can be converted to one ECEF frame using the following function:

function rECItoECEF([T,] ECI, ECEF, JD_UTC::Number [, eop_data])

which has the same characteristics of the function rECEFtoECI described in Section ECEF to ECI, but with the inputs ECI and ECEF swapped.

Note

This function actually calls rECEFtoECI first and then uses inv_rotation. Hence, it has a slightly overhead on top of rECEFtoECI, which should be negligible for both rotation representations that are supported.

julia> rECItoECEF(DCM, GCRF(), ITRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267    -0.78518     -0.000797313
  0.78518     -0.619267     0.00106478
 -0.00132979   3.33492e-5   0.999999

julia> rECItoECEF(GCRF(), ITRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267    -0.78518     -0.000797313
  0.78518     -0.619267     0.00106478
 -0.00132979   3.33492e-5   0.999999

julia> rECItoECEF(GCRF(), ITRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU2000A)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267    -0.78518     -0.000797312
  0.78518     -0.619267     0.00106478
 -0.00132979   3.33502e-5   0.999999

julia> rECItoECEF(J2000(), PEF(), DatetoJD(1986, 06, 19, 21, 35, 0))
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619271    -0.785177    -0.000796885
  0.785176    -0.619272     0.00106622
 -0.00133066   3.45854e-5   0.999999

julia> rECItoECEF(J2000(), PEF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619267    -0.78518     -0.000796879
  0.78518     -0.619267     0.00106623
 -0.00133066   3.45854e-5   0.999999

julia> rECItoECEF(GCRF(), TIRS(), DatetoJD(1986, 06, 19, 21, 35, 0))
3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9}:
 -0.619271    -0.785177    -0.000796885
  0.785176    -0.619272     0.00106623
 -0.00133066   3.45884e-5   0.999999

julia> rECItoECEF(Quaternion, GCRF(), ITRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU1980)
Quaternion{Float64}:
  + 0.4363098936462618 + 0.0005909969666939257.i - 0.00030510511316206974.j - 0.8997962182293519.k

julia> rECItoECEF(Quaternion, GCRF(), ITRF(), DatetoJD(1986, 06, 19, 21, 35, 0), eop_IAU2000A)
Quaternion{Float64}:
  + 0.4363098936309669 + 0.000590996988144556.i - 0.0003051056555230158.j - 0.8997962182365703.k