GitHub

Transformations of Orbit Representations

Orbit State Vector

We provide a set of functions to transform an OrbitStateVector between any frame described in Transformations Between ECEF and ECI Reference Frames.

From ECI to ECI

The functions

sv_eci_to_eci(sv::OrbitStateVector, ECIo, ECIf[, jd_utc::Number][, eop]) -> OrbitStateVector
sv_eci_to_eci(sv::OrbitStateVector, ECIo, [jd_utco::Number, ]ECIf[, jd_utcf::Number][, eop]) -> OrbitStateVector

can be used to transform the orbit state vector sv from an Earth-Centered Inertial (ECI) reference frame ECIo to another ECI reference frame ECIf. If the origin and destination frame contain only one of date frame, the first signature is used and the Julian Day jd_utc [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, the second signature must be used in which the Julian Day jd_utco [UTC] is the epoch of the origin frame and the Julian Day jd_utcf [UTC] is the epoch of the destination frame. If the epochs are not provided, the algorithm will use the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

The specification about the origin and destination frames, as well as the requirements for the EOP data, are the same as described for the r_eci_to_eci function.

The following example shows how we can convert a state vector from the MOD (Mean of Date) reference frame to the TOD (True of Date) reference frame:

julia> jd_utc = date_to_jd(2004, 4, 6, 7, 51, 28.386009)2.453101827411875e6
julia> r_mod  = [5094.02837450; 6127.87081640; 6380.24851640]3-element Vector{Float64}:
 5094.0283745
 6127.8708164
 6380.2485164
julia> v_mod  = [-4.7462630520; 0.7860140450; 5.5317905620]3-element Vector{Float64}:
 -4.746263052
  0.786014045
  5.531790562
julia> sv_mod = OrbitStateVector(jd_utc, r_mod, v_mod)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [5.09403, 6.12787, 6.38025]             km
      v : [-0.00474626, 0.000786014, 0.00553179]  km/s
julia> sv_tod = sv_eci_to_eci(sv_mod, MOD(), TOD())OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [5.09451, 6.12737, 6.38035]             km
      v : [-0.00474609, 0.000786077, 0.00553193]  km/s

From ECI to ECEF

The function

sv_eci_to_ecef(sv::OrbitStateVector, ECI, ECEF[, jd_utc][, eop]) -> OrbitStateVector

can be used to convert the orbit state vector sv from an Earth-Centered Inertial (ECI) reference frame to an Earth-Centered, Earth-Fixed (ECEF) reference frame at the Julian Day jd_utc [UTC]. If the epoch jd_utc is not provided, the algorithm will use the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

It is assumed that the input velocity and acceleration in sv are obtained by an observer on the ECI frame. Thus, the output will contain the velocity and acceleration as measured by an observer on the ECEF frame.

The specification about the origin and destination frames, as well as the requirements for the EOP data, are the same as described for the r_eci_to_ecef function.

The following example shows how we can convert a state vector from the J2000 reference frame reference frame to PEF (True of Date) reference frame:

julia> jd_ut1 = date_to_jd(2004, 4, 6, 7, 51, 28.386009) - 0.4399619 / 864002.453101827406783e6
julia> r_j2000  = [5102.50960000; 6123.01152000; 6378.13630000]3-element Vector{Float64}:
 5102.5096
 6123.01152
 6378.1363
julia> v_j2000  = [-4.7432196000; 0.7905366000; 5.5337561900]3-element Vector{Float64}:
 -4.7432196
  0.7905366
  5.53375619
julia> sv_j2000 = OrbitStateVector(jd_ut1, r_j2000, v_j2000)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:27.946)
      r : [5.10251, 6.12301, 6.37814]             km
      v : [-0.00474322, 0.000790537, 0.00553376]  km/s
julia> sv_pef   = sv_eci_to_ecef(sv_j2000, J2000(), PEF(), jd_ut1)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:27.946)
      r : [-1.03348, 7.90131, 6.38034]            km
      v : [-0.00322563, -0.00287244, 0.00553193]  km/s

From ECEF to ECI

The function

sv_ecef_to_eci(sv::OrbitStateVector, ECEF, ECI[, jd_utc][, eop]) -> OrbitStateVector

can be used to convert the orbit state vector sv from the Earth-Centered, Earth-Fixed (ECEF) reference frame to the Earth-Centered Inertial (ECI) reference frame at the Julian day jd_utc [UTC]. If the epoch jd_utc is not provided, the algorithm will use the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

It is assumed that the input velocity and acceleration in sv are obtained by an observer on the ECEF frame. Thus, the output will contain the velocity and acceleration as measured by an observer on the ECI frame.

The specification about the origin and destination frames, as well as the requirements for the EOP data, are the same as described for the r_ecef_to_eci function.

The following example shows how we can convert a state vector from the PEF reference frame reference frame to J2000 reference frame:

julia> jd_ut1 = date_to_jd(2004, 4, 6, 7, 51, 28.386009) - 0.4399619 / 864002.453101827406783e6
julia> r_pef = [-1033.47503130; 7901.30558560; 6380.34453270]3-element Vector{Float64}:
 -1033.4750313
  7901.3055856
  6380.3445327
julia> v_pef = [-3.2256327470; -2.8724425110; +5.5319312880]3-element Vector{Float64}:
 -3.225632747
 -2.872442511
  5.531931288
julia> sv_pef   = OrbitStateVector(jd_ut1, r_pef, v_pef)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:27.946)
      r : [-1.03348, 7.90131, 6.38034]            km
      v : [-0.00322563, -0.00287244, 0.00553193]  km/s
julia> sv_j2000 = sv_ecef_to_eci(sv_pef, PEF(), J2000(), jd_ut1)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:27.946)
      r : [5.10251, 6.12301, 6.37814]             km
      v : [-0.00474322, 0.000790537, 0.00553376]  km/s

From ECEF to ECEF

The function

sv_ecef_to_ecef(sv::OrbitStateVector, ECEFo, ECEFf[, jd_utc::Number], eop) -> OrbitStateVector

can be used to convert the orbit state vector sv from an Earth-Centered, Earth-Fixed (ECEF) reference frame ECEFo to another ECEF reference frame ECEFf at the Julian Day jd_utc [UTC]. If the epoch jd_utc is not provided, the algorithm will use the epoch of the orbit state vector sv (sv.t). The algorithm also requires the Earth Orientation Parameters (EOP) eop.

The specification about the origin and destination frames, as well as the requirements for the EOP data, are the same as described for the r_ecef_to_ecef function.

The following example shows how we can convert a state vector from the ITRF reference frame reference frame to PEF reference frame:

julia> eop_iau1980 = fetch_iers_eop()EopIau1980:
     Data │ Timespan
 ─────────┼──────────────────────────────────────────────
        x │ 1973-01-02T00:00:00 -- 2026-08-15T00:00:00
        y │ 1973-01-02T00:00:00 -- 2026-08-15T00:00:00
  UT1-UTC │ 1973-01-02T00:00:00 -- 2026-08-15T00:00:00
      LOD │ 1973-01-02T00:00:00 -- 2025-08-06T00:00:00
      δΔψ │ 1973-01-02T00:00:00 -- 2025-10-23T00:00:00
      δΔϵ │ 1973-01-02T00:00:00 -- 2025-10-23T00:00:00
julia> jd_utc = date_to_jd(2004, 4, 6, 7, 51, 28.386009)2.453101827411875e6
julia> r_itrf = [-1033.4793830; 7901.2952754; 6380.3565958]3-element Vector{Float64}:
 -1033.479383
  7901.2952754
  6380.3565958
julia> v_itrf = [-3.225636520; -2.872451450; +5.531924446]3-element Vector{Float64}:
 -3.22563652
 -2.87245145
  5.531924446
julia> sv_itrf = OrbitStateVector(jd_utc, r_itrf, v_itrf)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [-1.03348, 7.9013, 6.38036]             km
      v : [-0.00322564, -0.00287245, 0.00553192]  km/s
julia> sv_pef = sv_ecef_to_ecef(sv_itrf, ITRF(), PEF(), jd_utc, eop_iau1980)OrbitStateVector{Float64, Float64}:
  epoch : 2.4531e6 (2004-04-06T07:51:28.386)
      r : [-1.03348, 7.90131, 6.38034]            km
      v : [-0.00322563, -0.00287244, 0.00553193]  km/s

Other Orbit Representations

We provide the following function:

orb_eci_to_eci(orb::T, ECIo, ECIf[, jd_utc::Number][, eop]) where T<: Orbit -> T
orb_eci_to_eci(orb::T, ECIo, [jd_utco::Number, ]ECIf[, jd_utcf::Number][, eop]) where T<:Orbit -> T

to convert the orbit representation orb from an Earth-Centered Inertial (ECI) reference frame ECIo to another ECI reference frame ECIf. If the origin and destination frame contain only one of date frame, the first signature is used and the Julian Day jd_utc [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, the second signature must be used in which the Julian Day jd_utco [UTC] is the epoch of the origin frame and the Julian Day jd_utcf [UTC] is the epoch of the destination frame. If the epochs are not provided, the algorithm will use the epoch of the orbit state vector sv (sv.t). The algorithm might also require the Earth Orientation Parameters (EOP) eop depending on the source and destination frames.

The specification about the origin and destination frames, as well as the requirements for the EOP data, are the same as described for the r_eci_to_eci function.

The following example shows how we can convert Keplerian elements from the TOD reference frame reference frame to J2000 reference frame:

julia> orb_tod = KeplerianElements(
           date_to_jd(2025, 1, 1),
           8000e3,
           0.015,
           28.5 |> deg2rad,
           100  |> deg2rad,
           200  |> deg2rad,
           45   |> deg2rad
       )KeplerianElements{Float64, Float64}:
           Epoch :    2.46068e6 (2025-01-01T00:00:00)
 Semi-major axis : 8000.0   km
    Eccentricity :    0.015
     Inclination :   28.5   °
            RAAN :  100.0   °
 Arg. of Perigee :  200.0   °
    True Anomaly :   45.0   °
julia> orb_j2000 = orb_eci_to_eci(orb_tod, TOD(), J2000())KeplerianElements{Float64, Float64}:
           Epoch :    2.46068e6 (2025-01-01T00:00:00)
 Semi-major axis : 8000.0    km
    Eccentricity :    0.015
     Inclination :   28.6376 °
            RAAN :   99.6403 °
 Arg. of Perigee :  200.045  °
    True Anomaly :   45.0    °
  • 1TEME is an of date frame.