Skip to content

Commit

Permalink
📚 Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ronisbr
ronisbr committed May 24, 2024
1 parent dbb4f7e commit c700a54
Show file tree
Hide file tree
Showing 6 changed files with 193 additions and 432 deletions.
2 changes: 2 additions & 0 deletions docs/make.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ makedocs(
format = Documenter.HTML(
prettyurls = !("local" in ARGS),
canonical = "https://juliaspace.github.io/SatelliteToolboxTransformations.jl/stable/",
size_threshold = 500 * 1024,
size_threshold_warn = 300 * 1024,
),
sitename = "SatelliteToolboxTransformations.jl",
authors = "Ronan Arraes Jardim Chagas",
Expand Down
3 changes: 1 addition & 2 deletions docs/src/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
SatelliteToolboxTransformations.jl
==================================
# SatelliteToolboxTransformations.jl

This package contains transformations that are useful for the **SatelliteToolbox.jl**
ecosystem. Currently, the following algorithms are available:
Expand Down
287 changes: 81 additions & 206 deletions docs/src/man/ecef_eci.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
Transformations between ECEF and ECI reference frames
=====================================================
# Transformations Between ECEF and ECI Reference Frames

```@meta
CurrentModule = SatelliteToolboxTransformations
DocTestSetup = quote
using SatelliteToolboxTransformations
end
```

```@setup ecef_eci
using SatelliteToolboxTransformations
```

This package currently provides two models to transform reference systems: the IAU-76/FK5
Expand All @@ -29,10 +29,12 @@ described later on.
| `MJ2000()` | ECI | J2000 mean equatorial frame |

!!! 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 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
Expand Down Expand Up @@ -69,20 +71,18 @@ The following keywords are available:
(**Default** = `false`)
- `url::String`: URL of the EOP file.

```jldoctest ECEF_ECI
julia> eop_iau1980 = fetch_iers_eop();
[ Info: Downloading the file 'finals.all.csv' from 'https://datacenter.iers.org/data/csv/finals.all.csv'...
```@repl ecef_eci
eop_iau1980 = fetch_iers_eop()
julia> eop_iau2000a = fetch_iers_eop(Val(:IAU2000A));
[ Info: Downloading the file 'finals2000A.all.csv' from 'https://datacenter.iers.org/data/csv/finals2000A.all.csv'...
eop_iau2000a = fetch_iers_eop(Val(:IAU2000A))
```

## ECEF to ECEF

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

```julia
function r_ecef_to_ecef([T,] ECEFo, ECEFf, JD_UTC::Number, eop)
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
Expand All @@ -91,35 +91,23 @@ be used is given by `T`, which can be `DCM` or `Quaternion`. If `T` is omitted,
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).

```jldoctest ECEF_ECI
julia> r_ecef_to_ecef(PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
1.0 0.0 -4.34677e-7
-6.29476e-13 1.0 -1.44815e-6
4.34677e-7 1.44815e-6 1.0
julia> r_ecef_to_ecef(TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000a)
DCM{Float64}:
1.0 3.08408e-11 -4.34677e-7
-3.14703e-11 1.0 -1.44815e-6
4.34677e-7 1.44815e-6 1.0
julia> r_ecef_to_ecef(Quaternion, PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
+ 1.0 - 7.24073e-7⋅i + 2.17339e-7⋅j - 0.0⋅k
julia> r_ecef_to_ecef(Quaternion, TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000a)
Quaternion{Float64}:
+ 1.0 - 7.24073e-7⋅i + 2.17339e-7⋅j + 1.55778e-11⋅k
```@repl ecef_eci
r_ecef_to_ecef(PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
r_ecef_to_ecef(TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000a)
r_ecef_to_ecef(Quaternion, PEF(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
r_ecef_to_ecef(Quaternion, TIRS(), ITRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000a)
```

## ECI to ECI

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

```julia
function r_eci_to_eci([T,] ECIo, ECIf, JD_UTC::Number[, eop])
function r_eci_to_eci([T,] ECIo, JD_UTCo::Number, ECIf, JD_UTCf::Number[, eop])
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
Expand Down Expand Up @@ -184,100 +172,41 @@ in the API.
the free core nutation 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.

```jldoctest ECEF_ECI
julia> r_eci_to_eci(DCM, GCRF(), J2000(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
1.0 -4.71326e-12 1.53474e-9
4.71332e-12 1.0 -3.53979e-9
-1.53474e-9 3.53979e-9 1.0
julia> r_eci_to_eci(
Quaternion,
TEME(),
GCRF(),
date_to_jd(1986, 6, 19, 21, 35, 0),
eop_iau1980
)
Quaternion{Float64}:
+ 0.999999 + 1.83013e-5⋅i + 0.000665304⋅j - 0.00151324⋅k
julia> r_eci_to_eci(
TOD(),
date_to_jd(1986, 6, 19, 21, 35, 0),
TOD(),
date_to_jd(1987, 5, 19 , 3, 0, 0),
eop_iau1980
)
DCM{Float64}:
1.0 -0.000224088 -9.73787e-5
0.000224087 1.0 -5.80065e-6
9.738e-5 5.77883e-6 1.0
julia> r_eci_to_eci(
Quaternion,
TOD(),
2451545.0,
MOD(),
2451545.0,
eop_iau1980
)
Quaternion{Float64}:
+ 1.0 - 1.40025e-5⋅i + 1.34736e-5⋅j - 3.10785e-5⋅k
julia> r_eci_to_eci(
J2000(),
TEME(),
date_to_jd(1986, 6, 19, 21, 35, 0)
)
DCM{Float64}:
0.999995 0.0030265 0.00133055
-0.00302645 0.999995 -3.86125e-5
-0.00133066 3.45854e-5 0.999999
julia> r_eci_to_eci(
CIRS(),
GCRF(),
date_to_jd(1986, 6, 19, 21, 35, 0),
eop_iau2000a
)
DCM{Float64}:
0.999999 3.88389e-8 -0.00133066
7.18837e-9 1.0 3.45897e-5
0.00133066 -3.45897e-5 0.999999
julia> r_eci_to_eci(
Quaternion,
CIRS(),
GCRF(),
date_to_jd(1986, 6, 19, 21, 35, 0),
eop_iau2000a
)
Quaternion{Float64}:
+ 1.0 + 1.72949e-5⋅i + 0.000665332⋅j + 7.91263e-9⋅k
julia> r_eci_to_eci(
DCM,
GCRF(),
J2000(),
date_to_jd(1986, 6, 19, 21, 35, 0),
eop_iau1980
)
DCM{Float64}:
1.0 -4.71326e-12 1.53474e-9
4.71332e-12 1.0 -3.53979e-9
-1.53474e-9 3.53979e-9 1.0
```@repl ecef_eci
r_eci_to_eci(DCM, GCRF(), J2000(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
r_eci_to_eci(Quaternion, TEME(), GCRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
r_eci_to_eci(
TOD(),
date_to_jd(1986, 6, 19, 21, 35, 0),
TOD(),
date_to_jd(1987, 5, 19 , 3, 0, 0),
eop_iau1980
)
r_eci_to_eci(Quaternion, TOD(), 2451545.0, MOD(), 2451545.0, eop_iau1980)
r_eci_to_eci(J2000(), TEME(), date_to_jd(1986, 6, 19, 21, 35, 0))
r_eci_to_eci(CIRS(), GCRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000a)
r_eci_to_eci(Quaternion, CIRS(), GCRF(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau2000a)
r_eci_to_eci(DCM, GCRF(), J2000(), date_to_jd(1986, 6, 19, 21, 35, 0), eop_iau1980)
```

## ECEF to ECI

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

```julia
function r_ecef_to_eci([T,] ECEF, ECI, JD_UTC::Number[, eop])
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
Expand Down Expand Up @@ -321,114 +250,60 @@ be available, reducing the precision.
the free core nutation 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.

```jldoctest ECEF_ECI
julia> r_ecef_to_eci(DCM, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
-0.619267 0.78518 -0.00132979
-0.78518 -0.619267 3.33509e-5
-0.000797312 0.00106478 0.999999
julia> r_ecef_to_eci(ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
-0.619267 0.78518 -0.00132979
-0.78518 -0.619267 3.33509e-5
-0.000797312 0.00106478 0.999999
julia> r_ecef_to_eci(PEF(), J2000(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
-0.619271 0.785176 -0.00133066
-0.785177 -0.619272 3.45854e-5
-0.000796885 0.00106622 0.999999
julia> r_ecef_to_eci(PEF(), J2000(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
-0.619267 0.78518 -0.00133066
-0.78518 -0.619267 3.45854e-5
-0.000796879 0.00106623 0.999999
julia> r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
+ 0.43631 - 0.000590997⋅i + 0.000305106⋅j + 0.899796⋅k
julia> r_ecef_to_eci(ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
DCM{Float64}:
-0.619267 0.78518 -0.00132979
-0.78518 -0.619267 3.33516e-5
-0.000797311 0.00106478 0.999999
julia> r_ecef_to_eci(TIRS(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
-0.619271 0.785176 -0.00133066
-0.785177 -0.619272 3.45884e-5
-0.000796885 0.00106623 0.999999
julia> r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
Quaternion{Float64}:
+ 0.43631 - 0.000590997⋅i + 0.000305106⋅j + 0.899796⋅k
```@repl ecef_eci
r_ecef_to_eci(DCM, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_ecef_to_eci(ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_ecef_to_eci(PEF(), J2000(), date_to_jd(1986, 06, 19, 21, 35, 0))
r_ecef_to_eci(PEF(), J2000(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_ecef_to_eci(ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
r_ecef_to_eci(TIRS(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0))
r_ecef_to_eci(Quaternion, ITRF(), GCRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
```

# ECI to ECEF
## ECI to ECEF

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

```julia
function r_eci_to_ecef([T,] ECI, ECEF, JD_UTC::Number[, eop])
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.

!!! note

This function actually calls [`r_ecef_to_eci`](@ref) first and then uses `inv_rotation`.
Hence, it has a slightly overhead on top of [`r_ecef_to_eci`](@ref), which should be
negligible for both rotation representations that are supported.

```jldoctest ECEF_ECI
julia> r_eci_to_ecef(DCM, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
-0.619267 -0.78518 -0.000797312
0.78518 -0.619267 0.00106478
-0.00132979 3.33509e-5 0.999999
julia> r_eci_to_ecef(GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
-0.619267 -0.78518 -0.000797312
0.78518 -0.619267 0.00106478
-0.00132979 3.33509e-5 0.999999
julia> r_eci_to_ecef(J2000(), PEF(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
-0.619271 -0.785177 -0.000796885
0.785176 -0.619272 0.00106622
-0.00133066 3.45854e-5 0.999999
julia> r_eci_to_ecef(J2000(), PEF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
DCM{Float64}:
-0.619267 -0.78518 -0.000796879
0.78518 -0.619267 0.00106623
-0.00133066 3.45854e-5 0.999999
julia> r_eci_to_ecef(Quaternion, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
Quaternion{Float64}:
+ 0.43631 + 0.000590997⋅i - 0.000305106⋅j - 0.899796⋅k
julia> r_eci_to_ecef(GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
DCM{Float64}:
-0.619267 -0.78518 -0.000797311
0.78518 -0.619267 0.00106478
-0.00132979 3.33516e-5 0.999999
julia> r_eci_to_ecef(GCRF(), TIRS(), date_to_jd(1986, 06, 19, 21, 35, 0))
DCM{Float64}:
-0.619271 -0.785177 -0.000796885
0.785176 -0.619272 0.00106623
-0.00133066 3.45884e-5 0.999999
julia> r_eci_to_ecef(Quaternion, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
Quaternion{Float64}:
+ 0.43631 + 0.000590997⋅i - 0.000305106⋅j - 0.899796⋅k
```@repl ecef_eci
r_eci_to_ecef(DCM, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_eci_to_ecef(GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_eci_to_ecef(J2000(), PEF(), date_to_jd(1986, 06, 19, 21, 35, 0))
r_eci_to_ecef(J2000(), PEF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_eci_to_ecef(Quaternion, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau1980)
r_eci_to_ecef(GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
r_eci_to_ecef(GCRF(), TIRS(), date_to_jd(1986, 06, 19, 21, 35, 0))
r_eci_to_ecef(Quaternion, GCRF(), ITRF(), date_to_jd(1986, 06, 19, 21, 35, 0), eop_iau2000a)
```

0 comments on commit c700a54

Please sign in to comment.