Axes
Core
FrameTransformations.add_axes!
— Functionadd_axes!(fs::FrameSystem{O, T}, ax::FrameAxesNode{O, T}) where {O,T}
Add axes to the frame system.
add_axes!(frames, name::Symbol, id::Int, class::Int, funs, parentid)
Add a new axes node to frames
.
Inputs
frames
– Target frame systemname
– Axes name, must be unique withinframes
id
– Axes ID, must be unique withinframes
funs
–FrameAxesFunctions
object storing the functions to compute the DCM and, eventually, its time derivatives.parentid
– Axes ID of the parent axes. Not required only for the root axes.
This is a low-level function and is NOT meant to be directly used. Instead, to add a set of axes to the frame system, see add_axes_projected!
, add_axes_rotating!
and add_axes_fixedoffset!
.
FrameTransformations.add_axes_fixedoffset!
— Functionadd_axes_fixedoffset!(frames, name::Symbol, id::Int, parent, dcm:DCM)
Add axes name
with id id
to frames
with a fixed-offset from parent
. Fixed offset axes have a constant orientation with respect to their parent
axes, represented by dcm
, a Direction Cosine Matrix (DCM).
See also
See also add_axes!
.
FrameTransformations.add_axes_projected!
— Functionadd_axes_projected!(frames, name, id, parent, fun)
Add inertial axes name
and id id
as a set of projected axes to frames
. The axes relation to the parent
axes are given by a fun
.
Projected axes are similar to rotating axis, except that all the positions, velocity, etc ... are rotated by the 0-order rotation (i.e. the derivatives of the rotation matrix are null, despite the rotation depends on time).
See also
See also add_axes!
.
FrameTransformations.add_axes_rotating!
— Functionadd_axes_rotating!(frames, name::Symbol, id::Int, parent, fun, δfun=nothing,
δ²fun=nothing, δ³fun=nothing)
Add axes
as a set of rotating axes to frames
. The orientation of these axes depends only on time and is computed through the custom functions provided by the user.
The input functions must accept only time as argument and their outputs must be as follows:
fun
: return a Direction Cosine Matrix (DCM).δfun
: return the DCM and its 1st order time derivative.δ²fun
: return the DCM and its 1st and 2nd order time derivatives.δ³fun
: return the DCM and its 1st, 2nd and 3rd order time derivatives.
If δfun
, δ²fun
or δ³fun
are not provided, they are computed via automatic differentiation.
It is expected that the input functions and their outputs have the correct signature. This function does not perform any checks on the output types.
FrameTransformations.add_axes_alias!
— Functionadd_axes_alias!(frames, target, alias::Symbol)
Add a name alias
to a target
axes registered in frames
.
FrameTransformations.add_axes_ephemeris!
— Functionadd_axes_ephemeris!(frames::FrameSystem{O, T}, eph::AbstractEphemerisProvider,
name::Symbol, id::Int, seq::Symbol) where {O, T}
Add axes coming from an AbstractEphemerisProvider
subtype to frames
. The axes are identifies by the id
and a have a user defined name
. The rotation matrix is build using the rotation sequence specified in seq
. The axes type is specified by class
.
This is an interface only, concrete subtypes of AbstractEphemerisProvider
requires an proper implementation.
Celestial
FrameTransformations.add_axes_gcrf!
— Functionadd_axes_gcrf!(frames::FrameSystem)
Add the Geocentric Celestial Reference Frame (GCRF) to the frames graph. The axes are automatically named GCRF
and assigned the 23 ID. These axes can only be defined as a set of root axes or as child of the ICRF (ID = 1).
See also
See also add_axes_icrf!
and AXESID_GCRF
.
FrameTransformations.add_axes_icrf!
— Functionadd_axes_icrf!(frames::FrameSystem)
Add the International Celestial Reference Frame (ICRF) as the root axes of the frames graph. The axes are automatically named ICRF
and assigned the 1 ID.
See also
See also add_axes!
, add_axes_gcrf!
and AXESID_ICRF
.
FrameTransformations.add_axes_eme2000!
— Functionadd_axes_eme2000!(frames, name::Symbol=:EME2000, parentid::Int=AXESID_ICRF,
id::Int = AXESID_EME2000)
Add Mean Equator Mean Equinox of J2000 axes to frames
. Custom name
, id
and parentid
can be assigned by the user.
See also
See also DCM_ICRF_TO_EME2000
.
Ecliptic
FrameTransformations.add_axes_ecl2000!
— Functionadd_axes_ecl2000!(frames, name::Symbol=:ECL2000, parentid::Int, id::Int = AXESID_ECL2000;
model::IERSModel=iers1996)
Add Ecliptic Equinox of J2000 (ECL2000) axes to frames
. Custom id
, name
and parentid
can be assigned by the user. The admissible parent axes are the following:
- ICRF: for the International Celestial Reference Frame, with ID = 1
- GCRF: for the Geocentric Celestial Reference Frame, with ID = 23
- EME2000: the Mean Earth/Moon Ephemeris of J2000, with ID = 22
The obliquity of the ecliptic is computed using the IERS convention model
. To retrieve the same orientation of the ECLIPJ2000 axes avaialble in the SPICE Toolkit, the iers1996
model must be used.
Terrestrial
FrameTransformations.add_axes_itrf!
— Functionadd_axes_itrf!(fr::FrameSystem, name::Symbol, parentid::Int=AXESID_ICRF, id::Int=AXESID_ITRF,
model::IERSModel=iers2010b)
Add International Terrestrial Reference Frame (ITRF) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
If the ID of the parent set of axes
is neither the ICRF (ID = 1) nor the GCRF (ID = 23), an error is thrown.
FrameTransformations.add_axes_tirf!
— Functionadd_axes_tirf!(fr::FrameSystem, name::Symbol, id::Int, parentid::Int=AXESID_ICRF,
model::IERSModel=iers2010b)
Add Terrestrial Intermediate Reference Frame (TIRF) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
Despite this class of axes has a rotation matrix that depends on time, its derivatives are assumed null.
The ID of the parent
set of axes must be 1 (ICRF) or 23 (GCRF) otherwise an error is thrown.
FrameTransformations.add_axes_cirf!
— Functionadd_axes_cirf!(fr::FrameSystem, name::Symbol, id::Int, parentid::Int=AXESID_ICRF,
model::IERSModel=iers2010b)
Add Celestial Intermediate Reference Frame (CIRF) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
Despite this class of axes has a rotation matrix that depends on time, its derivatives are assumed null.
The ID of the parent
set of axes must be 1 (ICRF) or 23 (GCRF) otherwise an error is thrown.
FrameTransformations.add_axes_mod!
— Functionadd_axes_mod!(fr, name::Symbol, axesid::Int, parentid::Int,
model::IERSConventions.IERSModel=iers2010b)
Add Mean Equator and Equinox of Date (MOD) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
The Mean-of-Date axes are obtained by applying the frame bias and precession matrix. For this reason, if the IERS 1996 conventions are used, the rotation is actually computed starting from the EME2000 rather than the GCRF.
Despite this class of axes has a rotation matrix that depends on time, its derivatives are assumed null.
The ID of the parent
set of axes must be 1 (ICRF) or 23 (GCRF) otherwise an error is thrown.
FrameTransformations.add_axes_tod!
— Functionadd_axes_tod!(fr::FrameSystem, name::Symbol, id::Int, parentid::Int=AXESID_ICRF,
model::IERSModel=iers2010b)
Add True Equator of Date (TOD) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
The True-of-Date axes are obtained by applying the frame bias, precession and nutation matrix. For this reason, if the IERS 1996 conventions are used, the rotation is actually computed starting from the EME2000 rather than the GCRF.
Despite this class of axes has a rotation matrix that depends on time, its derivatives are assumed null.
The ID of the parent
set of axes must be 1 (ICRF) or 23 (GCRF) otherwise an error is thrown.
FrameTransformations.add_axes_gtod!
— Functionadd_axes_gtod!(fr::FrameSystem, name::Symbol, id::Int, parentid::Int=AXESID_ICRF,
model::IERSModel=iers2010b)
Add Greenwich True-of-Date (GTOD) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
Despite this class of axes has a rotation matrix that depends on time, its derivatives are assumed null.
The ID of the parent
set of axes must be 1 (ICRF) or 23 (GCRF) otherwise an error is thrown.
FrameTransformations.add_axes_pef!
— Functionadd_axes_pef!(fr::FrameSystem, name::Symbol, id::Int, parentid::Int=AXESID_ICRF,
model::IERSModel=iers2010b)
Add Pseudo-Earth Fixed (PEF) axes to fr
. Use the model
argument to specify which IERS convention should be used for the computations.
The ID of the parent
set of axes must be 1 (ICRF) or 23 (GCRF) otherwise an error is thrown.
Planetary
FrameTransformations.add_axes_bci2000!
— Functionadd_axes_bci2000!(fr, axes::AbstractFrameAxes, center, data)
Add Body-Centered Inertial (BCI) axes at J2000 with name
and id
to fr
. The center point (i.e., the reference body) is center
.
The parent axes are automatically set to the ICRF (ID = 1). If the ICRF is not defined in fr
, an error is thrown.
See also
See also add_axes_fixedoffset!
, add_axes_bcrtod!
.
FrameTransformations.add_axes_bcrtod!
— Functionadd_axes_bcrtod!(fr, name, id, center; deriv=true)
Add Body-Centered Rotating (BCR), True-of-Date (TOD) axes with name
and id
to fr
. The center point (i.e., the reference body) is center
.
These axes are the equivalent of SPICE's IAU_<BODY_NAME>
frames.
The parent axes are automatically set to the ICRF (ID = 1). If the ICRF is not defined in fr
, an error is thrown.
See also
See also add_axes_rotating!
, add_axes_bci2000!
.
Lunar
FrameTransformations.add_axes_me421!
— Functionadd_axes_me421!(frames, name::Symbol, parentid::Int, axesid::Int=AXESID_MOONME_DE421)
Add DE421 Moon's Mean Earth/Mean Rotation (ME) axes to frames
.
The parent
set of axes must either the DE440 Principal Axes (PA440, ID =
- or the DE421 Principal Axes (PA421, ID =
31006), otherwise an error is thrown. Depending on that, the relative axes orientation will be automatically selected by this function.
FrameTransformations.add_axes_pa421!
— Functionadd_axes_pa421!(frames, eph::AbstractEphemerisProvider, name::Symbol,
id::Int=AXESID_MOONPA_DE421)
Add DE421 Moon's Principal Axes (PA) axes to frames
. The libration angles are extracted from the eph
ephemeris kernels, an error is thrown if such orientation data is not available.
The parent axes are automatically set to the ICRF (ID = 1). If such axes are not registered in the frame system, an error is thrown.
To properly read the ephemeris kernels, the ID associated to the input axes
must match NAIF's FRAME ID for the Moon PA DE421 axes (31006).
FrameTransformations.add_axes_pa440!
— Functionadd_axes_pa440!(frames, eph::AbstractEphemerisProvider, name::Symbol,
id::Int=AXESID_MOONPA_DE440)
Add DE440 Moon's Principal Axes (PA) axes to frames
. The libration angles are extracted from the eph
ephemeris kernels, an error is thrown if such orientation data is not available.
The parent axes are automatically set to the ICRF (ID = 1). If such axes are not registered in the frame system, an error is thrown.
To properly read the ephemeris kernels, the ID associated to the input axes
must match NAIF's FRAME ID for the Moon PA DE440 axes (31008).
Topocentric
FrameTransformations.add_axes_topocentric!
— Functionadd_axes_topocentric!(frames, name::Symbol, id::Int, parent, λ, ϕ, mount)
Add topocentric axes to frames
at a specified location and mounting.
The orientation relative to the parent axes parent
is defined throuh the longitude λ
, the geodetic latitude ϕ
and the mounting type mount
, which may be any of the following:
:NED
(North, East, Down): the X-axis points North, the Y-axis is directed eastward and the Z-axis points inwards towards the nadir.:SEZ
(South, East, Zenith): the X-axis points South, the Y-axis is directed East, and the Z-axis points outwards towards the zenith.:ENU
(East, North, Up): the X-axis points East, the Y-axis is directed North and the Z-axis points outwards towards the zenith.
The parent axes must be a set of body-fixed reference axes. This is under user resposibility.
Others
FrameTransformations.add_axes_twodir!
— Functionfunction add_axes_twodir!(frames::FrameSystem{O,T}, name::Symbol, id, parent,
dir1::Symbol, dir2::Symbol, seq::Symbol; project::Bool=false) where {O,T}
Add a set of axes to frames
based on two directions.
A right-handed coordinate system is generated based on the specified sequence direction (seq
), which determines the order in which the vectors are used to define the basis. The project
flag specifies whether the resulting axes are inertial or not.
See also
See also add_axes_projected!
and add_axes_rotating!
.
FrameTransformations.add_axes_frozen!
— Functionadd_axes_frozen!(fr, name, id, frozen, e)
Create a frozen axes version of frozen
at epoch e
, with name
and id
and add it to frames
.
The parent axes are automatically assigned to the frozen
parent.
FrameTransformations.add_axes_fixed_quaternion!
— Functionadd_axes_fixed_quaternion!(frames::FrameSystem, name::Symbol, id::Int, parent, q::Quaternion)
Add axes name
with id id
to frames
with a fixed-offset from parent
. Fixed offset axes have a constant orientation with respect to their parent
axes, represented by the quaternion q
.
See also
See also add_axes_fixedoffset!
.
FrameTransformations.add_axes_fixed_angles!
— Functionadd_axes_fixed_angles!(frames, name::Symbol, id::Int, parent, θ::AbstractVector{N}, seq::Symbol)
Add axes name
with id id
to frames
with a fixed-offset from parent
. Fixed offset axes have a constant orientation with respect to their parent
axes, represented by Euler angles θ
.
The rotation sequence is defined by seq
specifing the rotation axes. The possible values depends on the number of rotations as follows:
- 1 rotation (
θ₁
)::X
,:Y
, or:Z
. - 2 rotations (
θ₁
,θ₂
)::XY
,:XZ
,:YX
,:YZ
,:ZX
, or:ZY
. - 3 rotations (
θ₁
,θ₂
,θ₃
)::XYX
,XYZ
,:XZX
,:XZY
,:YXY
,:YXZ
,:YZX
,:YZY
,:ZXY
,:ZXZ
,:ZYX
, or:ZYZ
See also
See also add_axes_fixedoffset!
.
FrameTransformations.add_axes_fixed_angleaxis!
— Functionadd_axes_fixed_angleaxis!(frames, name::Symbol, id::Int, parent, ϕ::Number, v::AbstractVector{N})
Add axes name
with id id
to frames
with a fixed-offset from parent
. Fixed offset axes have a constant orientation with respect to their parent
axes, represented by Euler angle ϕ
[rad] and Euler axis v
.
See also
See also add_axes_fixedoffset!
.
Utils
IDs
This is a list of NAIF IDs for standard axes that are used in astrodynamic applications.
FrameTransformations.AXESID_ICRF
— ConstantAXESID_ICRF
NAIF Axes ID for the International Celestial Reference Frame (ICRF).
FrameTransformations.AXESID_MOONME_DE421
— ConstantAXESID_MOONME_DE421
NAIF axes id for the DE421 Moon Mean Earth/Mean Rotation axes (ME421).
FrameTransformations.AXESID_MOONPA_DE421
— ConstantAXESID_MOONPA_DE421
NAIF axes id for the DE421 Moon Principal Axes (PA421).
FrameTransformations.AXESID_MOONPA_DE440
— ConstantAXESID_MOONPA_DE440
NAIF Axes id for the DE440 Moon Principal Axes (PA440).
FrameTransformations.AXESID_ECL2000
— ConstantAXESID_ECL2000
NAIF Axes ID for the Mean Ecliptic Equinox of J2000 (ECL2000).
FrameTransformations.AXESID_EME2000
— ConstantAXESID_EME2000
Axes ID for the Mean Dynamical Equator and Equinox of J2000.0.
In SPICE the J2000 (EME2000) and ICRF axes are considered equal, thus there exist no specific NAIF ID for the EME2000 axes. 22 has been chosen because it is the first unassigned axes ID among the built-in SPICE frames.
FrameTransformations.AXESID_GCRF
— ConstantAXESID_GCRF
Axes ID for the Geocentric Celestial Reference Frame (GCRFF)
Although the ICRF and GCRF axes are identical, they are based upon a different timescale. A different ID is here assigned to provide a robust way of distinguishing between the two. 23 has been chosen because it is one of the unassigned axes ID among the built-in SPICE frames.
Rotation Matrices
FrameTransformations.DCM_ICRF_TO_EME2000
— ConstantDCM_ICRF_TO_EME2000
DCM for the rotation from the International Celestial Reference Frame (ICRF
) and the Mean Equator and Equinox of J2000.0 (EME2000
). This corresponds to the J2000
frame in the SPICE toolkit.
The frame bias is here computed using the IAU 2006 Precession model, similarly to ESA's GODOT. Some other software libraries, such as Orekit, use the frame bias of the IAU 2000 precession model. The two definitions differ of about 1 arcsecond.
Moreover, according to Hilton there are multiple possibilities to define the proper rotation between the ICRS and the EME2000. The transformation implemented here correspond to Eq. 6 using the parameters in Table 3, line 1 (RIERS).
References
- Hilton, James L., and Catherine Y. Hohenkerk. – Rotation matrix from the mean dynamical equator and equinox at J2000. 0 to the ICRS. – Astronomy & Astrophysics 513.2 (2004): 765-770. DOI: 10.1051/0004-6361:20031552
- SOFA docs