|
| 1 | +# Working with orientation and rotation |
| 2 | + |
| 3 | +Orientations and rotations in 3D can be represented in multiple different ways. Components which (may) have a 3D angular state, such as [`Body`](@ref), [`Spherical`](@ref) and [`FreeMotion`](@ref), offer the user to select the orientation representation, either Euler angles or quaternions. |
| 4 | + |
| 5 | +## Euler angles |
| 6 | +[Euler angles](https://en.wikipedia.org/wiki/Euler_angles) represent orientation using rotations around three axes, and thus uses three numbers to represent the orientation. The benefit of this representation is that it is minimal (only three numbers used), but the drawback is that any 3-number orientation representation suffers from a kinematic singularity. This representation is beneficial when you know that the singularity will not come into play in your simulation. |
| 7 | + |
| 8 | +Most components that may use Euler angles also allow you to select the sequence of axis around which to perform the rotations, e.g., `sequence = [1,2,3]` performs rotations around ``x`` first, then ``y`` and ``z``. |
| 9 | + |
| 10 | +## Quaternions |
| 11 | +A [quaternion](https://en.wikipedia.org/wiki/Quaternion) represents an orientation using 4 numbers. This is a non-minimal representation, but in return it is also singularity free. Multibody.jl uses non-unit quaternions to represent orientation when `quat = true` is provided to components that support this option. The convention used for quaternions is ``[s, v_1, v_2, v_3]``, sometimes also referred to as ``[w, i, j, k]``, i.e., the real/scalar part comes first, followed by the three imaginary numbers. |
| 12 | + |
| 13 | +Multibody.jl depends on [Rotations.jl](https://github.com/JuliaGeometry/Rotations.jl) which in turn uses [Quaternions.jl](https://github.com/JuliaGeometry/Quaternions.jl) for quaternion computations. If you manually create quaternions using these packages, you may convert them to a vector to provide, e.g., initial conditions, using `vec(Q)`. |
| 14 | + |
| 15 | +### Examples using quaternions |
| 16 | +- [Free motions](@ref) (second example on the page) |
| 17 | +- [Three springs](@ref) |
| 18 | +- [Bodies in space](@ref) (may use, see comment) |
| 19 | + |
| 20 | +## Rotation matrices |
| 21 | +Rotation matrices represent orientation using a ``3\times 3`` matrix ``\in SO(3)``. These are used in the equations of multibody components and connectors, but should for the most part be invisible to the user. In particular, they should never appear as state variables after simplification. |
| 22 | + |
| 23 | + |
| 24 | +## Conversion between formats |
| 25 | +You may convert between different representations of orientation using the appropriate constructors from Rotations.jl, for example: |
| 26 | +```@example ORI |
| 27 | +using Multibody.Rotations |
| 28 | +using Multibody.Rotations: params |
| 29 | +using Multibody.Rotations.Quaternions |
| 30 | +using LinearAlgebra |
| 31 | +
|
| 32 | +R = RotMatrix{3}(I(3)) |
| 33 | +``` |
| 34 | + |
| 35 | +```@example ORI |
| 36 | +# Convert R to a quaternion |
| 37 | +Q = QuatRotation(R) |
| 38 | +``` |
| 39 | + |
| 40 | +```@example ORI |
| 41 | +# Convert Q to a 4-vector |
| 42 | +Qvec = params(Q) |
| 43 | +``` |
| 44 | + |
| 45 | +```@example ORI |
| 46 | +# Convert R to Euler angles in the sequence XYZ |
| 47 | +E = RotXYZ(R) |
| 48 | +``` |
| 49 | + |
| 50 | +```@example ORI |
| 51 | +# Convert E to a 3-vector |
| 52 | +Evec = params(E) |
| 53 | +``` |
| 54 | + |
| 55 | +## Conventions for modeling |
| 56 | +See [Orientations and directions](@ref) |
| 57 | + |
| 58 | + |
| 59 | +## Orientation API |
| 60 | +See [Orientation utilities](@ref) |
0 commit comments