FrameSystem{O, N, S, D}

A FrameSystem instance manages a collection of user-defined FramePointNode, FrameAxesNode and Direction objects, enabling computation of arbitrary transformations between them. It is created by specifying the maximum transformation order O, the outputs datatype N and an AbstractTimeScale instance S; the parameter D is the length of the output ad shall always be 3O.

The following transformation orders are accepted:

• 1: position
• 2: position and velocity
• 3: position, velocity and acceleration
• 4: position, velocity, acceleration and jerk

FrameSystem{O, N, S}()

Create a new, empty FrameSystem object of order O, datatype N and timescale S. The parameter S can be dropped, in case the default (BarycentricDynamicalTime) is used.

order(R::Rotation{O}) where O

Return the rotation order O.

order(frames::FrameSystem{O}) where O

Return the frame system order O.

timescale(frames::FrameSystem{O, N, S}) where {O, N, S}

Return the frame system order timescale S.

has_point(frames::FrameSystem, id)

Check if id point is within frames.

points(f::FrameSystem)

Return the registered points names/ids map.

points_graph(frames::FrameSystem)

Return the frame system points graph.

has_axes(frames::FrameSystem, ax)

Check if ax axes is within frames.

axes(f::FrameSystem)

Return the registered axes names/ids map.

axes_graph(frames::FrameSystem)

Return the frame system axes graph.

has_axes(frames::FrameSystem, name::Symbol)

Check if name direction is within frames.

directions(f::FrameSystem)

Return the registered directions names.

directions_map(f::FrameSystem)

Return the direction dictionary.

Rotation{O, N}

A container to efficiently compute O-th order rotation matrices of type N between two set of axes. It stores the Direction Cosine Matrix (DCM) and its time derivatives up to the (O-1)-th order. Since this type is immutable, the data must be provided upon construction and cannot be mutated later.

The rotation of state vector between two set of axes is computed with an ad-hoc overload of the product operator. For example, a 3rd order Rotation object R, constructed from the DCM A and its time derivatives δA and δ²A rotates a vector v = [p, v, a] as:

̂v = [A*p, δA*p + A*v, δ²A*p + 2δA*v + A*a]

A Rotation object R call always be converted to a SMatrix or a MMatrix by invoking the proper constructor.

Examples

julia> A = angle_to_dcm(π/3, :Z)
DCM{Float64}:
  0.5       0.866025  0.0
 -0.866025  0.5       0.0
  0.0       0.0       1.0

julia> R = Rotation(A);

julia> SM = SMatrix(R)
3×3 SMatrix{3, 3, Float64, 9} with indices SOneTo(3)×SOneTo(3):
  0.5       0.866025  0.0
 -0.866025  0.5       0.0
  0.0       0.0       1.0

julia> MM = MMatrix(R)
3×3 MMatrix{3, 3, Float64, 9} with indices SOneTo(3)×SOneTo(3):
  0.5       0.866025  0.0
 -0.866025  0.5       0.0
  0.0       0.0       1.0

Rotation(dcms::DCM...)

Create a Rotation object from a Direction Cosine Matrix (DCM) and any of its time derivatives. The rotation order is inferred from the number of inputs, while the rotation type is obtained by promoting the DCMs types.

Examples

julia> A = angle_to_dcm(π/3, :Z); 

julia> δA = DCM(0.0I); 

julia> δ²A = DCM(0.0I); 

julia> R = Rotation(A, δA, δ²A); 

julia> typeof(R) 
Rotation{3, Float64}

julia> R2 = Rotation(A, B, C, DCM(0.0im*I)); 

julia> typeof(R2)
Rotation{4, ComplexF64}

Rotation{O}(dcms::DCM...) where O

Create a Rotation object of order O. If the number of dcms is smaller than O, the remaining slots are filled with null DCMs, otherwise if the number of inputs is greater than O, only the first O DCMs are used.

Rotation{S1}(dcms::NTuple{S2, DCM{N}}) where {S1, S2, N}

Create a Rotation object from a tuple of Direction Cosine Matrix (DCM) and its time derivatives. If S1 < S2, only the first S1 DCMs are considered, otherwise the remaining orders are filled with null DCMs.

Examples

julia> A = angle_to_dcm(π/3, :Z);

julia> B = angle_to_dcm(π/4, π/6, :XY);

julia> R3 = Rotation{3}((A,B));

julia> R3[1] == A
true 

julia> R3[3] 
DCM{Float64}:
 0.0  0.0  0.0
 0.0  0.0  0.0
 0.0  0.0  0.0

Rotation{O}(u::UniformScaling{N}) where {O, N}
Rotation{O, N}(u::UniformScaling) where {O, N}

Create an O-order identity Rotation object of type N with identity position rotation and null time derivatives.

Examples

julia> Rotation{1}(1.0I) 
Rotation{1, Float64}(([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0],))

julia> Rotation{1, Int64}(I)
Rotation{1, Int64}(([1 0 0; 0 1 0; 0 0 1],))

Rotation{S1}(rot::Rotation{S2, N}) where {S1, S2, N}
Rotation{S1, N}(R::Rotation{S2}) where {S1, S2, N}

Transform a Rotation object of order S2 to order S1 and type N. The behaviour of these functions depends on the values of S1 and S2:

• S1 < S2: Only the first S1 components of rot are considered.
• S1 > S2: The missing orders are filled with null DCMs.

Examples

julia> A = angle_to_dcm(π/3, :Z);

julia> B = angle_to_dcm(π/4, π/6, :XY);

julia> R1 = Rotation(A, B);

julia> order(R1)
2

julia> R2 = Rotation{1}(R1);

julia> order(R2)
1

julia> R2[1] == A 
true

julia> R3 = Rotation{3}(R1);

julia> R3[3]
DCM{Float64}:
 0.0  0.0  0.0
 0.0  0.0  0.0
 0.0  0.0  0.0

Rotation(m::DCM{N}, ω::AbstractVector) where N

Create a 2nd order Rotation object of type N to rotate between two set of axes a and b from a Direction Cosine Matrix (DCM) and the angular velocity vector ω of b with respect to a, expressed in b

inv(rot::Rotation)

Compute the invese of the rotation object rot. The operation is efficiently performed by taking the transpose of each rotation matrix within rot.

vector3(frame::FrameSystem, from, to, axes, ep::Epoch)

Compute 3-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired epoch ep.

Requires a frame system of order ≥ 1.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the observing point
• to – ID or instance of the target point
• axes – ID or instance of the output state vector axes
• ep – Epoch of the observer. Its timescale must match that of the frame system.

vector3(frame, from, to, axes, t::Number)

Compute 3-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired time t expressed in seconds since J2000.

vector6(frame::FrameSystem, from, to, axes, ep::Epoch)

Compute 6-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired epoch ep.

Requires a frame system of order ≥ 2.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the observing point
• to – ID or instance of the target point
• axes – ID or instance of the output state vector axes
• ep – Epoch of the observer. Its timescale must match that of the frame system.

vector6(frame, from, to, axes, t::Number)

Compute 6-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired time t expressed in seconds since J2000.

vector9(frame::FrameSystem, from, to, axes, ep::Epoch)

Compute 9-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired epoch ep.

Requires a frame system of order ≥ 3.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the observing point
• to – ID or instance of the target point
• axes – ID or instance of the output state vector axes
• ep – Epoch of the observer. Its timescale must match that of the frame system.

vector9(frame, from, to, axes, t::Number)

Compute 9-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired time t expressed in seconds since J2000.

vector12(frame::FrameSystem, from, to, axes, ep::Epoch)

Compute 12-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired epoch ep.

Requires a frame system of order ≥ 4.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the observing point
• to – ID or instance of the target point
• axes – ID or instance of the output state vector axes
• ep – Epoch of the observer. Its timescale must match that of the frame system.

vector12(frame, from, to, axes, t::Number)

Compute 12-elements state vector of a target point relative to an observing point, in a given set of axes, at the desired time t expressed in seconds since J2000.

rotation3(frame::FrameSystem, from, to, ep::Epoch)

Compute the rotation that transforms a 3-elements state vector from one specified set of axes to another at a given epoch.

Requires a frame system of order ≥ 1.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the axes to transform from
• to – ID or instance of the axes to transform to
• ep – Epoch of the rotation. Its timescale must match that of the frame system.

Output

A Rotation object of order 1.

rotation3(frame::FrameSystem, from, to, t::Number)

Compute the rotation that transforms a 3-elements state vector from one specified set of axes to another at a given time t, expressed in seconds since J2000.

rotation6(frame::FrameSystem, from, to, ep::Epoch)

Compute the rotation that transforms a 6-elements state vector from one specified set of axes to another at a given epoch.

Requires a frame system of order ≥ 2.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the axes to transform from
• to – ID or instance of the axes to transform to
• ep – Epoch of the rotation. Its timescale must match that of the frame system.

Output

A Rotation object of order 2.

rotation6(frame::FrameSystem, from, to, t::Number)

Compute the rotation that transforms a 6-elements state vector from one specified set of axes to another at a given time t, expressed in seconds since J2000.

rotation9(frame::FrameSystem, from, to, ep::Epoch)

Compute the rotation that transforms a 9-elements state vector from one specified set of axes to another at a given epoch.

Requires a frame system of order ≥ 3.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the axes to transform from
• to – ID or instance of the axes to transform to
• ep – Epoch of the rotation. Its timescale must match that of the frame system.

Output

A Rotation object of order 3.

rotation9(frame::FrameSystem, from, to, t::Number)

Compute the rotation that transforms a 9-elements state vector from one specified set of axes to another at a given time t, expressed in seconds since J2000.

rotation12(frame::FrameSystem, from, to, ep::Epoch)

Compute the rotation that transforms a 12-elements state vector from one specified set of axes to another at a given epoch.

Requires a frame system of order ≥ 4.

Inputs

• frame – The FrameSystem container object
• from – ID or instance of the axes to transform from
• to – ID or instance of the axes to transform to
• ep – Epoch of the rotation. Its timescale must match that of the frame system.

Output

A Rotation object of order 4.

rotation12(frame::FrameSystem, from, to, t::Number)

Compute the rotation that transforms a 12-elements state vector from one specified set of axes to another at a given time t, expressed in seconds since J2000.

direction3(frames::FrameSystem, name::Symbol, axes, ep::Epoch)

Compute the direction vector name of order 3 at epoch ep expressed in the axes frame.

Requires a frame system of order ≥ 1.

direction3(frames::FrameSystem, name::Symbol, axes, t::Number)

Compute the direction vector name of order 3 at epoch t, where t is expressed in seconds since J2000.

Requires a frame system of order ≥ 1.

direction6(frames::FrameSystem, name::Symbol, axes, ep::Epoch)

Compute the direction vector name of order 6 at epoch ep expressed in the axes frame.

Requires a frame system of order ≥ 2.

direction6(frames::FrameSystem, name::Symbol, axes, t::Number)

Compute the direction vector name of order 6 at epoch t, where t is expressed in seconds since J2000.

Requires a frame system of order ≥ 2.

direction9(frames::FrameSystem, name::Symbol, axes, ep::Epoch)

Compute the direction vector name of order 9 at epoch ep expressed in the axes frame.

Requires a frame system of order ≥ 3.

direction9(frames::FrameSystem, name::Symbol, axes, t::Number)

Compute the direction vector name of order 9 at epoch t, where t is expressed in seconds since J2000.

Requires a frame system of order ≥ 3.

direction12(frames::FrameSystem, name::Symbol, axes, ep::Epoch)

Compute the direction vector name of order 12 at epoch ep expressed in the axes frame.

Requires a frame system of order ≥ 4.

direction12(frames::FrameSystem, name::Symbol, axes, t::Number)

Compute the direction vector name of order 12 at epoch t, where t is expressed in seconds since J2000.

Requires a frame system of order ≥ 4.