Rotation Angles To Direction Cosine Matrix — Robotics/Orientation 3D
Robotics/Orientation_3D/Rotation_Angles_To_Direction_Cosine_Matrix · 1 input / 1 output port(s) at insert · exports to Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text
Description#
The block's own DESCRIPTION_HTML, rendered verbatim — the same text the config dialog's info panel and the library navigator show. Fix a wrong sentence in the block's .cpp (R-D9), never here.
Rotation Angles to Direction Cosine Matrix
Robotics / Orientation 3D
Builds the [3,3] direction cosine matrix described by three rotation angles, in whichever of the twelve rotation orders the configuration names:
DCM = R(axis₃, r₃) · R(axis₂, r₂) · R(axis₁, r₁)
The angles are applied in the order they are listed – ZYX turns r₁ about Z first, r₂ about Y next and r₃ about X last – so the last rotation is the leftmost factor. Each elementary factor is a frame rotation:
- R(X,a) = rows [1 0 0], [0 cos a sin a], [0 −sin a cos a]
- R(Y,a) = rows [cos a 0 −sin a], [0 1 0], [sin a 0 cos a]
- R(Z,a) = rows [cos a sin a 0], [−sin a cos a 0], [0 0 1]
A direction cosine matrix re-expresses a fixed vector's components in the rotated frame: v' = DCM · v. It is orthogonal, so its inverse is its transpose, and its determinant is +1.
Ports
- r – the three angles in radians, a [3,1] column [r₁ r₂ r₃]T in the order they are applied. Any real value is accepted; the block is periodic in each angle and nothing is wrapped.
- DCM – the direction cosine matrix, [3,3]. Its size is fixed and does not follow the input's.
Parameters
- Rotation Order – which three axes the three angles turn about,
and in which order. Twelve values, the six Tait-Bryan sequences that use
three different axes and the six proper Euler sequences that repeat the
first axis last:
- ZYX – the default, and the aerospace convention: yaw, then pitch, then roll.
- ZXY, YXZ, YZX, XYZ, XZY – the other five Tait-Bryan sequences.
- ZYZ, ZXZ, YXY, YZY, XYX, XZX – the six proper Euler sequences.
- Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. Nothing is exposed as a tunable parameter: the rotation order is structural, so it is baked into the arithmetic at export time rather than left on the shared parameter object.
The nine entries are expanded symbolically before anything is emitted, so no generated core carries a matrix multiply. Each entry comes out as at most two signed products of at most three factors, and the whole block costs six trigonometric calls and eighteen multiplies whichever order is selected.
The three HDL targets are simulation-only real arithmetic, not synthesizable fixed point: a sine and a cosine of a value arriving on a port are a lookup table or a CORDIC in hardware, not an expression. They quantize at the port boundary only.
Simulink bridge
Both directions, onto aerolibtransform2/Rotation Angles to
Direction Cosine Matrix in the Aerospace Blockset.
Rotation Order maps to rotationOrder, and the twelve values
are spelled identically on both sides, so the round trip is lossless.
Its name is drawn on two lines, so the real library path carries an
embedded newline between to and Direction; the
flattened one-line spelling resolves to nothing at all. And the block defines
no SampleTime parameter, so the rate stays on the ICore side
and a block configured with an explicit positive rate reports that the rate did
not cross.
Notes
- Algebraic and stateless: the output depends only on the current input, so the block cannot break an algebraic loop.
- ⚠ A direction cosine matrix is the TRANSPOSE of the rotation matrix Quaternion To Rotation Matrix produces for the same rotation. They hold the same nine numbers and neither is wrong: this one maps components into the rotated frame, that one turns a vector within a frame. Transpose to cross between them.
- Deliberately no state space. Every entry is a product of sines and cosines of the input, so there is no linear form to fabricate and model reduction is right to refuse the block.
- Two orders that look alike are not alike. Several sequences coincide when the three angles are equal, so a model that reads the order wrongly can still look right on symmetric data. Feed it three different angles before trusting a comparison.
Code facts#
| Fact | Value |
|---|---|
| registered type | Robotics/Orientation_3D/Rotation_Angles_To_Direction_Cosine_Matrix |
| family | Robotics/Orientation_3D |
| solver environment class | ICoreBlock_0_Robotics_1_Orientation_3D_2_Rotation_Angles_To_Direction_Cosine_Matrix |
| source | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Robotics/Orientation_3D/Rotation_Angles_To_Direction_Cosine_Matrix/ICoreBlock_0_Robotics_1_Orientation_3D_2_Rotation_Angles_To_Direction_Cosine_Matrix.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Robotics/Orientation_3D/Rotation_Angles_To_Direction_Cosine_Matrix/ICoreBlock_0_Robotics_1_Orientation_3D_2_Rotation_Angles_To_Direction_Cosine_Matrix.h |
| default size on canvas | 126 × 76 px |
| ports at insert | 1 in, 1 out |
| code generators implemented | Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text |
Ports#
| # | Direction | Signal type | Description label |
|---|---|---|---|
| 1 | in | ICoreDouble | r |
| 2 | out | ICoreDouble | DCM |
Ports the constructor creates. A block whose port list changes with its configuration adds or removes ports at load time; the count above is the one a freshly inserted block has.
Configuration variables#
| Config variable | Default | Simulink parameter |
|---|---|---|
Rotation Order | options~~ORDERS[0] | rotationOrder |
Every block also carries Sampling Time (s) from ICoreBlockSolverEnvironment: zero or less inherits the solver's rate, a positive value runs the block at that period.
Simulink bridge#
| support | Support::Both |
| Simulink path | aerolibtransform2/Rotation Angles to\nDirection Cosine Matrix |
| port-count rule | PortsParam::None |
SampleTime parameter | no — the counterpart defines none; the rate stays on the ICore side |
| ICore config | Simulink parameter | Value translation |
|---|---|---|
Rotation Order | rotationOrder | ZYX → ZYX, ZYZ → ZYZ, ZXY → ZXY, ZXZ → ZXZ, YXZ → YXZ, YXY → YXY, YZX → YZX, YZY → YZY, XYZ → XYZ, XYX → XYX, XZY → XZY, XZX → XZX |
Caveat (shown to the user): the twelve rotation orders are spelled identically on both sides, so the order crosses without translation. Note the Simulink block defines no SampleTime parameter: an ICore rate set explicitly stays on this side and is reported. Its library path carries an embedded newline, the block's name being drawn on two lines
Catalog contract: src/ICoreBlocks/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h
Description vs code#
The checker has a blind spot here — it could not resolve something (a grouped port bullet, a computed config name), which is reported and never counted as a pass. A reader has to settle it:
B0no sample under docs/generated/samples/ — nothing to cross-check (P8.1)
The verdict above is
tools/docs/check_block_descriptions.py(P7.1), which compares LISTS. It cannot read a sentence: "stateless" on a block with a state, an initial-value semantic the recursion does not implement, a "not synthesizable" caveat the HDL banner contradicts. That is the agent audit (P7.3) on BLOCK_DESCRIPTION_AUDIT.md, and this tool's green is not a substitute for one.
File banner (developer view)#
The top comment of the block's .cpp — the maths, the realization and the export strategy, addressed to whoever changes it. It must not contradict the description above (P7.5).
Rotation Angles to Direction Cosine Matrix -- three angles to a [3,3] DCM, twelve orders DCM = R(axis3, r3) * R(axis2, r2) * R(axis1, r1)
with R(X,a), R(Y,a), R(Z,a) the three elementary FRAME rotations
R(X,a) = |1 0 0 | R(Y,a) = | c 0 -s | R(Z,a) = | c s 0 | |0 c s | | 0 1 0 | |-s c 0 | |0 -s c | | s 0 c | | 0 0 1 |
and the three axes read off the "Rotation Order" configuration -- ZYX means r1 turns about Z first, r2 about Y next, r3 about X last, so the leftmost factor is the LAST rotation.
⚠ THE TWELVE ORDERS ARE ONE CONSTRUCTION, NOT TWELVE FORMULAS. The order is data: three axis letters pick three elementary matrices, and the product is expanded once. Writing out twelve transcribed answers is the shape of this block that goes wrong, because eleven of them are never the default and a wrong sign in one is invisible until somebody selects it.
MEASURED against MATLAB R2026a's angle2dcm on 2026-09-10, at r = (0.3, -0.45, 0.7): ALL TWELVE orders agree to at most 1.11e-16 (eleven of them at exactly 0), and the Simulink library block itself agrees at exactly 0 in XZY, a non-default order.
⚠ A DCM IS THE TRANSPOSE OF THIS FAMILY'S ROTATION MATRIX. Quaternion_To_Rotation_Matrix answers the ACTIVE rotation -- it turns a vector inside one frame -- while a direction cosine matrix re-expresses a fixed vector's components in the rotated frame. Same nine numbers, transposed. Measured: for the quaternion equivalent to (0.3, -0.45, 0.7) in ZYX, this block's (0,1) is 0.2661 and the rotation matrix's (0,1) is -0.9425, this block's (1,0).
THE SYMBOLIC EXPANSION IS THE POINT. dcmExpr() below multiplies the three elementary matrices as SUMS OF SIGNED PRODUCTS at export time, so no generated core carries a 3x3 matrix multiply: each entry becomes at most two signed products of at most three factors, and the whole block costs six trigonometric calls and eighteen multiplies. The C++ reference walks the very same expansion, so the reference and all ten exports cannot drift.
The three hardware targets are SIMULATION-ONLY real arithmetic, not synthesizable Q16.16: the entries need a sine and a cosine of a value arriving on a port, which is a table or a CORDIC in hardware rather than an expression. They quantize only at the port boundary.
Sample results#
No sample run is committed for this block. Samples come from the headless harness (DOCS_PLAN.md P8.1) into docs/generated/samples/; until one exists this block's behaviour is witnessed by the parity and export-verification suites, not by a plot here.