1+ # # [Frame System Overview](@id tutorial_00_frames)
2+ # _This example was generated on DATEOFTODAY._
3+
4+ # The core object of `FrameTransformations` is the [`FrameSystem`](@ref), which provides
5+ # the capability to compute relative position, orientation and their time derivatives up to
6+ # order 3 (jerk), between standard and user-defined point and axes. It works by creating two
7+ # separate graphs that silently store and manage all the parent-child relationships between
8+ # the user-registered axes and points, in the form of `FramePointNode` and `FrameAxesNode`.
9+
10+ # These two objects define two precise entities:
11+ # - **Axes**: defines an orientation in space. These are related each other by means of a
12+ # [`Rotation`](@ref) transformation which relate one axes to a parent axes in
13+ # a certain time interval.
14+ # - **Points**: defines a location in space. These are related each other by
15+ # means of a [`Translation`]@(ref) transformation which relate one point to a parent point in a
16+ # particular axes in a certain time interval.
17+
18+ # Additionally, it is possible to create `Direction`s, as vector valued functions that could
19+ # be used to define custom frames.
20+
21+ # -
22+ # md # !!! note
23+ # md # A single [`FrameSystem`](@ref) instance simultaneously handles both the axes and
24+ # md # point graphs, regardless of what the user registers in it. For instance, if no
25+ # md # points are added, the point graph will remain empty. The same applies for directions.
26+ # -
27+
28+ # Additionally, any node can have several childs, each with different transformations with
29+ # respect to the parent node. However, they shall be **registered** within the
30+ # [`FrameSystem`](@ref) before being used in a transformation or as parents of other nodes.
31+
32+
33+ # ## Basic Constructors
34+ # The creation of a generic [`FrameSystem`](@ref) requires the definition of the maximum
35+ # desired transformation order and of its `DataType`, which in most applications is a `Float64`.
36+ # The transformation order is always one greater than the maximum desired time derivative.
37+ # For instance, if the user only desires to compute position and velocity components (i.e.,
38+ # order 1 time-derivative), the transformation order to be used is 2. Thus, the maximum
39+ # allowed transformation order is 4.
40+
41+ # In this example, we highlight the most basic way to initialise a [`FrameSystem`](@ref):
42+
43+ using FrameTransformations
44+ using Tempo
45+
46+ F = FrameSystem {2,Float64} ()
47+
48+ # From this example, you can see that within the frame system there are both point and axes
49+ # graphs. However, at the moment they are completely empty since the graph was just created.
50+
51+ # Each [`FrameSystem`](@ref) object is assigned a reference timescale that is used to perform
52+ # computations with epochs and to parse ephemeris files. The default timescale is the
53+ # `BarycentricDynamicalTime`, however, the user is free to select the most suited timescale
54+ # for his applications. In this example, we set the `InternationalAtomicTime` as the reference scale.
55+
56+ F = FrameSystem {2,Float64,InternationalAtomicTime} ()
57+
58+ # ## Graph Inspection
59+
60+ # Once a [`FrameSystem`](@ref) is constructed (and populated) there are many routines devoted
61+ # to inspect its content. As already said, there are three main *objects* that are contained
62+ # in the `FrameSystem`: **points**, **axes** and **directions**. For each of them series of
63+ # utility functions are made available in order to check for the presence of a registered point:
64+
65+ has_point (F, 1 )
66+
67+ # a registered axes:
68+
69+ has_axes (F, 1 )
70+
71+ # or a registered direction:
72+
73+ has_direction (F, :Root )
74+
75+ # Additionally, the possibility to get a dictionary containing all name-id relationships is
76+ # made available for axes, via the [`axes_alias`](@ref) method:
77+
78+ axes_alias (F)
79+
80+ # and points, via the [`points_alias`](@ref) method:
81+
82+ points_alias (F)
83+
84+ # Finally, the `FrameSystem` order and timescale might be retrieved via the associated methods:
85+
86+ order (F)
87+
88+ # -
89+
90+ FrameTransformations. timescale (F)
91+
92+ # Refer to the [API](@ref frames_api) for additional details.
93+
94+ # ## Basic Usage
95+
96+ # md # !!! note
97+ # md # Work in progress
98+
99+ # ## Ephemerides Support
100+
101+ # In certain scenarios, the transformations require usage of binary ephemeris kernels, e.g.,
102+ # the JPL's DE440 files. To support this applications, this package has an interface relying
103+ # on [JSMDInterfaces.jl](https://github.com/JuliaSpaceMissionDesign/JSMDInterfaces.jl)
104+ # `AbstractEphemerisProvider`s. Currently, this package is shipped with extension for the
105+ # following two ephemeris readers:
106+ # * [Ephemerides.jl](https://github.com/JuliaSpaceMissionDesign/Ephemerides.jl)
107+ # * [CalcephEphemeris.jl](https://github.com/JuliaSpaceMissionDesign/CalcephEphemeris.jl)
108+
109+ # Once the desired ephemeris provider is created, it can be used to register points or axes.
110+ # In this example we begin loading an old DE421 kernels to pass to the ephemeris reader.
111+
112+ using Ephemerides, Downloads
113+
114+ url = " https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/a_old_versions/de421.bsp"
115+ E = EphemerisProvider (Downloads. download (url));
116+
117+ F = FrameSystem {2,Float64} ()
118+
119+ # Before registering any node, a set of root axes and a root node shall be anyway registered.
120+
121+ add_axes_icrf! (F)
122+ add_point! (F, :SSB , 0 , 1 )
123+
124+ # Points from the `EphemerisProvider` can be now registered.
125+
126+ add_point_ephemeris! (F, E, :Sun , 10 )
127+ add_point_ephemeris! (F, E, :EMB , 3 )
128+
129+ # Here the parent point will be inferred from the ephemeris.
130+
131+ F
0 commit comments