Skip to content

Commit

Permalink
📚 Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ronisbr
ronisbr committed Jan 1, 2025
1 parent 4006272 commit e36a786
Show file tree
Hide file tree
Showing 7 changed files with 124 additions and 65 deletions.
60 changes: 30 additions & 30 deletions docs/src/man/ecef_eci.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@ described later on.
| `ITRF()` | ECEF | International terrestrial reference frame |
| `PEF()` | ECEF | Pseudo-earth fixed reference frame |
| `TIRS()` | ECEF | Terrestrial intermediate reference system |
| `ERS()` | ECEF | Earth reference system |
| `MOD()` | ECI | Mean-of-date reference frame |
| `TOD()` | ECI | True-of-data reference frame |
| `GCRF()` | ECI | Geocentric celestial reference frame (GCRF) |
| `ERS()` | ECEF | Earth reference system |
| `MOD()` | ECI | Mean-of-date reference frame |
| `TOD()` | ECI | True-of-data reference frame |
| `GCRF()` | ECI | Geocentric celestial reference frame (GCRF) |
| `J2000()` | ECI | J2000 reference frame |
| `TEME()` | ECI | True equator, mean equinox reference frame |
| `CIRS()` | ECI | Celestial intermediate reference system |
Expand All @@ -43,7 +43,7 @@ described later on.
However, this will only work for past dates since the Earth orientation parameters are
required.

## Earth orientation parameters (EOP)
## Earth Orientation Parameters (EOP)

Some conversions here requires additional data related to the Earth orientation. This
information is provided by [IERS](https://www.iers.org) (International Earth Rotation and
Expand All @@ -63,7 +63,7 @@ in which `data_type` specifies what EOP type is desired (`Val(:IAU1980)` for IAU
This function returns an instance of the structure [`EopIau1980`](@ref) or
[`EopIau2000A`](@ref) depending on the selection of `data_type`. The returned value should
be passed to the reference frame conversion functions as described in the following.

The following keywords are available:

- `force_download::Bool`: If the EOP file exists and is less than 7 days old, it will not be
Expand All @@ -82,14 +82,14 @@ eop_iau2000a = fetch_iers_eop(Val(:IAU2000A))
One ECEF frame can be converted to another one by the following function:

```julia
r_ecef_to_ecef([T,] ECEFo, ECEFf, JD_UTC::Number, eop) -> T
r_ecef_to_ecef([T, ]ECEFo, ECEFf, jd_utc::Number, eop) -> T
```

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
where it will compute the rotation from the ECEF reference frame `ECEFo` to the ECEF
reference frame `ECEFf` at the Julian Day `jd_utc` [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` in this case is always necessary. Hence, the user must
initialize it as described in the section [Earth orientation parameters (EOP)](@ref).
initialize it as described in the section [Earth Orientation Parameters (EOP)](@ref).

```@repl ecef_eci
r_ecef_to_ecef(PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
Expand All @@ -106,20 +106,20 @@ r_ecef_to_ecef(Quaternion, TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), e
One ECI frame can be converted to another ECI frame by one of the following functions:

```julia
r_eci_to_eci([T,] ECIo, ECIf, JD_UTC::Number[, eop]) -> T
r_eci_to_eci([T,] ECIo, JD_UTCo::Number, ECIf, JD_UTCf::Number[, eop]) -> T
r_eci_to_eci([T, ]ECIo, ECIf, jd_utc::Number[, eop]) -> T
r_eci_to_eci([T, ]ECIo, jd_utco::Number, ECIf, jd_utcf::Number[, eop]) -> T
```

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 [Earth
orientation parameters (EOP)](@ref), is required in some conversions, as described in the
following table.
where it will 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, 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. 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 [Earth Orientation Parameters (EOP)](@ref), is
required in some conversions, as described in the following table.

[^1]: TEME is an *of date* frame.

Expand Down Expand Up @@ -206,14 +206,14 @@ r_eci_to_eci(DCM, GCRF(), J2000(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau19
One ECEF frame can be convert to one ECI frame using the following function:

```julia
r_ecef_to_eci([T,] ECEF, ECI, JD_UTC::Number[, eop]) -> T
r_ecef_to_eci([T, ]ECEF, ECI, jd_utc::Number[, eop]) -> T
```

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 [Earth orientation parameters (EOP)](@ref), is
required in some conversions, as described in the following table.
where it will compute the rotation from the `ECEF` frame to the `ECI` frame 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 [Earth Orientation Parameters (EOP)](@ref), is required in some
conversions, as described in the following table.

| Model | ECEF | ECI | EOP Data |
|:----------------------------|:-------|:---------|:----------------|
Expand Down Expand Up @@ -278,11 +278,11 @@ r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), e
One ECI frame can be converted to one ECEF frame using the following function:

```julia
r_eci_to_ecef([T,] ECI, ECEF, JD_UTC::Number[, eop]) -> T
r_eci_to_ecef([T, ]ECI, ECEF, jd_utc::Number[, eop]) -> T
```

which has the same characteristics of the function [`r_ecef_to_eci`](@ref) described in
Section [ECEF to ECI](@ref), but with the inputs `ECI` and `ECEF` swapped.
Section [ECEF to ECI](@ref), but with the inputs `ECI` and `ECEF` swapped.

!!! note

Expand Down
114 changes: 85 additions & 29 deletions docs/src/man/orbit_representations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,26 @@ in [Transformations Between ECEF and ECI Reference Frames](@ref).

### From ECI to ECI

The function
The functions

```julia
sv_eci_to_eci(sv::OrbitStateVector, args...) -> OrbitStateVector
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 `OrbitStateVector` `sv` from one ECI frame to another. The
arguments `args...` must match those of the function [`r_eci_to_eci`](@ref) **without** the
rotation representation.
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. The algorithm might also require the
Earth Orientation Parameters (EOP) `eop` depending on the source and destination frames.

[^1]: TEME is an *of date* 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_eci`](@ref) 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:
Expand All @@ -37,28 +48,29 @@ v_mod = [-4.7462630520; 0.7860140450; 5.5317905620]
sv_mod = OrbitStateVector(jd_utc, r_mod, v_mod)
sv_tod = sv_eci_to_eci(sv_mod, MOD(), jd_utc, TOD(), jd_utc)
sv_tod = sv_eci_to_eci(sv_mod, MOD(), TOD())
```

### From ECI to ECEF

The function

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

can be used to convert the orbit state vector `sv` from the Earth-Centered Inertial (ECI)
reference frame `ECI` to the Earth-Centered, Earth-Fixed (ECEF) reference frame at the
Julian day `jd_utc` [UTC]. The `eop` may be required depending on the selection of the input
and output reference system. For more information, see the documentation of the function
[`r_eci_to_ecef`](@ref).
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.

!!! info
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.

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`](@ref) 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:
Expand All @@ -80,20 +92,21 @@ sv_pef = sv_eci_to_ecef(sv_j2000, J2000(), PEF(), jd_ut1)
The function

```julia
sv_ecef_to_eci(sv::OrbitStateVector, ECEF, ECI, jd_utc[, eop]) -> OrbitStateVector
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 `ECEF` to the Earth-Centered Inertial (ECI) reference frame at the
Julian day `jd_utc` [UTC]. The `eop` may be required depending on the selection of the input
and output reference system. For more information, see the documentation of the function
[`r_ecef_to_eci`](@ref).
(`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.

!!! info
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.

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`](@ref) function.

The following example shows how we can convert a state vector from the PEF reference frame
reference frame to J2000 reference frame:
Expand All @@ -115,12 +128,17 @@ sv_j2000 = sv_ecef_to_eci(sv_pef, PEF(), J2000(), jd_ut1)
The function

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

can be used to transform the orbit state vector `sv` from an ECEF frame to another ECEF
frame. The arguments `args...` must match those of the function [`r_ecef_to_ecef`](@ref)
**wihtout** the rotation representation.
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`](@ref) function.

The following example shows how we can convert a state vector from the ITRF reference frame
reference frame to PEF reference frame:
Expand All @@ -138,3 +156,41 @@ sv_itrf = OrbitStateVector(jd_utc, r_itrf, v_itrf)
sv_pef = sv_ecef_to_ecef(sv_itrf, ITRF(), PEF(), jd_utc, eop_iau1980)
```

## Other Orbit Representations

We provide the following function:

```julia
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. 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`](@ref) function.

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

```@repl transformation_orbit
orb_tod = KeplerianElements(
date_to_jd(2025, 1, 1),
8000e3,
0.015,
28.5 |> deg2rad,
100 |> deg2rad,
200 |> deg2rad,
45 |> deg2rad
)
orb_j2000 = orb_eci_to_eci(orb_tod, TOD(), J2000())
```
3 changes: 2 additions & 1 deletion src/orbit/orb_eci_to_eci.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
export orb_eci_to_eci

"""
orb_eci_to_eci(orb::T, args...) where T<:Orbit -> T
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
Expand All @@ -31,6 +30,8 @@ Parameters (EOP) `eop` depending on the source and destination frames.
For more information, including how to specify the origin and destination reference
frames, see the **Extended Help**.
`¹`: TEME is an *of date* frame.
# Returns
- `T`: Orbit representation converted to the `ECIf` reference frame.
Expand Down
2 changes: 1 addition & 1 deletion src/orbit/sv_ecef_to_eci.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
export sv_ecef_to_eci

"""
sv_ecef_to_eci(sv::OrbitStateVector, ECEF, ECI, jd_utc[, eop]) -> OrbitStateVector
sv_ecef_to_eci(sv::OrbitStateVector, ECEF, ECI[, jd_utc][, eop]) -> OrbitStateVector
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`
Expand Down
2 changes: 1 addition & 1 deletion src/orbit/sv_eci_to_ecef.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
export sv_eci_to_ecef

"""
sv_eci_to_ecef(sv::OrbitStateVector, ECI, ECEF, jd_utc[, eop]) -> OrbitStateVector
sv_eci_to_ecef(sv::OrbitStateVector, ECI, ECEF[, jd_utc][, eop]) -> OrbitStateVector
Compute 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].
Expand Down
6 changes: 4 additions & 2 deletions src/orbit/sv_eci_to_eci.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@
export sv_eci_to_eci

"""
sv_eci_to_eci(sv::OrbitStateVector, ECIo, ECIf[, jd_utc::Number][, eop]) -> T
sv_eci_to_eci(sv::OrbitStateVector, ECIo, [jd_utco::Number, ]ECIf[, jd_utcf::Number][, eop]) -> T
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
Convert 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
Expand All @@ -30,6 +30,8 @@ Parameters (EOP) `eop` depending on the source and destination frames.
For more information, including how to specify the origin and destination reference
frames, see the **Extended Help**.
`¹`: TEME is an *of date* frame.
# Returns
- `OrbitStateVector`: Orbit state vector `sv` converted to the `ECIf` reference frame.
Expand Down
2 changes: 1 addition & 1 deletion test/runtests.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,4 +92,4 @@ const _BACKENDS = (
include("./differentiability/eop.jl")
include("./differentiability/reference_frames.jl")
include("./differentiability/time.jl")
end
end

0 comments on commit e36a786

Please sign in to comment.