hom_mat3d_rotate (Operator)

Name

`hom_mat3d_rotate` — Add a rotation to a homogeneous 3D transformation matrix.

Signature

`hom_mat3d_rotate( : : HomMat3D, Phi, Axis, Px, Py, Pz : HomMat3DRotate)`

Description

`hom_mat3d_rotate` adds a rotation by the angle `Phi` around the axis passed in the parameter `Axis` to the homogeneous 3D transformation matrix `HomMat3D` and returns the resulting matrix in `HomMat3DRotate`. The axis can be specified by passing the strings 'x', 'y', or 'z', or by passing a vector [x,y,z] as a tuple.

The rotation is described by a 3×3 rotation matrix R. It is performed relative to the global (i.e., fixed) coordinate system; this corresponds to the following chain of transformation matrices:

`Axis` = 'x':

`Axis` = 'y':

`Axis` = 'z':

`Axis` = [x,y,z]:

The point (`Px`,`Py`,`Pz`) is the fixed point of the transformation, i.e., this point remains unchanged when transformed using `HomMat3DRotate`. To obtain this behavior, first a translation is added to the input transformation matrix that moves the fixed point onto the origin of the global coordinate system. Then, the rotation is added, and finally a translation that moves the fixed point back to its original position. This corresponds to the following chain of transformations:

To perform the transformation in the local coordinate system, i.e., the one described by `HomMat3D`, use `hom_mat3d_rotate_local`.

Attention

Note that homogeneous matrices are stored row-by-row as a tuple; the last row is usually not stored because it is identical for all homogeneous matrices that describe an affine transformation. For example, the homogeneous matrix is stored as the tuple [ra, rb, rc, td, re, rf, rg, th, ri, rj, rk, tl]. However, it is also possible to process full 4×4 matrices, which represent a projective 4D transformation.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Processed without parallelization.

Parameters

`HomMat3D` (input_control)  hom_mat3d `→` (real)

Input transformation matrix.

`Phi` (input_control)  angle.rad `→` (real / integer)

Rotation angle.

Default value: 0.78

Suggested values: 0.1, 0.2, 0.3, 0.4, 0.78, 1.57, 3.14

Typical range of values: ```0 ≤ Phi ≤ 6.28318530718```

`Axis` (input_control)  string(-array) `→` (string / real / integer)

Axis, to be rotated around.

Default value: 'x'

Suggested values: 'x', 'y', 'z'

`Px` (input_control)  point3d.x `→` (real / integer)

Fixed point of the transformation (x coordinate).

Default value: 0

Suggested values: 0, 16, 32, 64, 128, 256, 512, 1024

`Py` (input_control)  point3d.y `→` (real / integer)

Fixed point of the transformation (y coordinate).

Default value: 0

Suggested values: 0, 16, 32, 64, 128, 256, 512, 1024

`Pz` (input_control)  point3d.z `→` (real / integer)

Fixed point of the transformation (z coordinate).

Default value: 0

Suggested values: 0, 16, 32, 64, 128, 256, 512, 1024

`HomMat3DRotate` (output_control)  hom_mat3d `→` (real)

Output transformation matrix.

Result

If the parameters are valid, the operator `hom_mat3d_rotate` returns TRUE. If necessary, an exception is raised.

Possible Predecessors

`hom_mat3d_identity`, `hom_mat3d_translate`, `hom_mat3d_scale`, `hom_mat3d_rotate`

Possible Successors

`hom_mat3d_translate`, `hom_mat3d_scale`, `hom_mat3d_rotate`

`hom_mat3d_invert`, `hom_mat3d_identity`, `hom_mat3d_rotate_local`, `pose_to_hom_mat3d`, `hom_mat3d_to_pose`, `hom_mat3d_compose`