hom_mat3d_rotate

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

Add a rotation to a homogeneous 3D transformation matrix.

hom_mat3d_rotate adds a rotation around the Axis-axis by the angle Phi to the homogeneous 3D transformation matrix HomMat3D and returns the resulting matrix in HomMat3DRotate. The rotation is described by a 3x3 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':

                   /        0 \                     / 1    0         0     \
  HomMat3DRotate = |  Rx    0 | * HomMat3D     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 = |  Ry    0 | * HomMat3D     Ry = |     0     1    0     |
                   |        0 |                     \ -sin(Phi) 0 cos(Phi) /
                   \ 0 0 0  1 / 


Axis = 'z':

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

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:

                   / 1 0 0 +Px \   /        0 \   / 1 0 0 -Px \ 
  HomMat3DRotate = | 0 1 0 +Py | * |   R    0 | * | 0 1 0 -Py | * HomMat3D
                   | 0 0 1 +Pz |   |        0 |   | 0 0 1 -Pz |
                   \ 0 0 0  1  /   \ 0 0 0  1 /   \ 0 0 0  1  /

Attention

Note that homogeneous matrices are stored row-by-row as a tuple; the last row is 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].

Parameters

`HomMat3D` (input_control)	affine3d-array `->` real
Input transformation matrix.
Number of elements: 12

`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 `->` string
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)	affine3d-array `->` real
Output transformation matrix.
Number of elements: 12

Result

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

Parallelization Information

hom_mat3d_rotate is reentrant and processed without parallelization.

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

Module

Basic operators