hom_mat3d_rotate_localT_hom_mat3d_rotate_localHomMat3dRotateLocalhom_mat3d_rotate_localHomMat3dRotateLocalHomMat3dRotateLocal (Operator)

Name

hom_mat3d_rotate_localT_hom_mat3d_rotate_localHomMat3dRotateLocalhom_mat3d_rotate_localHomMat3dRotateLocalHomMat3dRotateLocal — Add a rotation to a homogeneous 3D transformation matrix.

Signature

hom_mat3d_rotate_local( : : HomMat3D, Phi, Axis : HomMat3DRotate)

hom_mat3d_rotate_localhom_mat3d_rotate_localHomMat3dRotateLocalhom_mat3d_rotate_localHomMat3dRotateLocalHomMat3dRotateLocal adds a rotation by the angle PhiPhiPhiPhiPhiphi around the axis passed in the parameter AxisAxisAxisAxisAxisaxis to the homogeneous 3D transformation matrix HomMat3DHomMat3DHomMat3DHomMat3DHomMat3DhomMat3D and returns the resulting matrix in HomMat3DRotateHomMat3DRotateHomMat3DRotateHomMat3DRotateHomMat3DRotatehomMat3DRotate. The axis can by specified by passing the strings 'x', 'y', or 'z', or by passing a vector [x,y,z] as a tuple.

The rotation is decribed by a 3×3 rotation matrix R. In contrast to hom_mat3d_rotatehom_mat3d_rotateHomMat3dRotatehom_mat3d_rotateHomMat3dRotateHomMat3dRotate, it is performed relative to the local coordinate system, i.e., the coordinate system described by HomMat3DHomMat3DHomMat3DHomMat3DHomMat3DhomMat3D; this corresponds to the following chain of transformation matrices:

Axis = 'x':

                              /        0 \          / 1    0         0     \
  HomMat3DRotate = HomMat3D * |  Rx    0 |     Rx = | 0 cos(Phi) -sin(Phi) |
                              |        0 |          \ 0 sin(Phi)  cos(Phi) /
                              \ 0 0 0  1 /

Axis = 'y':

                              /        0 \          /  cos(Phi) 0 sin(Phi) \
  HomMat3DRotate = HomMat3D * |  Ry    0 |     Ry = |     0     1    0     |
                              |        0 |          \ -sin(Phi) 0 cos(Phi) /
                              \ 0 0 0  1 /

Axis = 'z':

                              /        0 \          / cos(Phi) -sin(Phi) 0 \
  HomMat3DRotate = HomMat3D * |  Rz    0 |     Rz = | sin(Phi)  cos(Phi) 0 |
                              |        0 |          \    0         0     1 /
                              \ 0 0 0  1 /

Axis = [x,y,z]:

                              /        0 \
  HomMat3DRotate = HomMat3D * |  Ra    0 |
                              |        0 |
                              \ 0 0 0  1 /

                       T                  T
               Ra = u*u + cos(Phi)*( I-u*u ) + sin(Phi)*S

                      AxisAxisAxisAxisAxisaxis       / x' \
               u  = --------  =  | y' |
                    ||AxisAxisAxisAxisAxisaxis||     \ z' /

                   / 1 0 0 \         /  0  -z'  y' \
               I = | 0 1 0 |     S = |  z'  0  -x' |
                   \ 0 0 1 /         \ -y'  x'  0  /

The fixed point of the transformation is the origin of the local coordinate system, i.e., this point remains unchanged when transformed using HomMat3DRotateHomMat3DRotateHomMat3DRotateHomMat3DRotateHomMat3DRotatehomMat3DRotate.

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

    / ra rb rc td \
    | re rf rg th |
    | ri rj rk tl |
    \ 0  0  0  1  /

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.

Parallelization

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters

HomMat3DHomMat3DHomMat3DHomMat3DHomMat3DhomMat3D (input_control) hom_mat3d → (real)

Input transformation matrix.

PhiPhiPhiPhiPhiphi (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 Phi Phi Phi Phi phi ≤ 6.28318530718

AxisAxisAxisAxisAxisaxis (input_control) string(-array) → (string / real / integer)

Axis, to be rotated around.

Default value: 'x' "x" "x" "x" "x" "x"

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

HomMat3DRotateHomMat3DRotateHomMat3DRotateHomMat3DRotateHomMat3DRotatehomMat3DRotate (output_control) hom_mat3d → (real)

Output transformation matrix.

Result

If the parameters are valid, the operator hom_mat3d_rotate_localhom_mat3d_rotate_localHomMat3dRotateLocalhom_mat3d_rotate_localHomMat3dRotateLocalHomMat3dRotateLocal returns 2 (H_MSG_TRUE). If necessary, an exception is raised.