hom_mat3d_rotate_localHomMat3dRotateLocalHomMat3dRotateLocalhom_mat3d_rotate_localT_hom_mat3d_rotate_local🔗

Short description🔗

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

Signature🔗

hom_mat3d_rotate_local( hom_mat3d HomMat3D, angle.rad Phi, string Axis, out hom_mat3d HomMat3DRotate )

Description🔗

hom_mat3d_rotate_localHomMat3dRotateLocal adds a rotation by the angle Phiphiphi around the axis passed in the parameter Axisaxisaxis to the homogeneous 3D transformation matrix HomMat3DhomMat3Dhom_mat_3d and returns the resulting matrix in HomMat3DRotatehomMat3DRotatehom_mat_3drotate. 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. In contrast to hom_mat3d_rotateHomMat3dRotate, it is performed relative to the local coordinate system, i.e., the coordinate system described by HomMat3DhomMat3Dhom_mat_3d; this corresponds to the following chain of transformation matrices:

Axisaxisaxis = 'x'"x":

\[\begin{eqnarray*} \textrm{HomMat3DRotate} = \textrm{HomMat3D} \cdot \mvHomMatrixThreeDRotTrans{\mvRotationMatrixVar{}{x}} {\mvVectorThreeDPlain{0}{0}{0}} \qquad \mvRotationMatrixVar{}{x} = \mvMatrix{ 1 & 0 & 0 \\ 0 & \cos(\textrm{Phi}) & - \sin(\textrm{Phi}) \\ 0 & \sin(\textrm{Phi}) & \cos(\textrm{Phi})} \end{eqnarray*}\]

Axisaxisaxis = 'y'"y":

\[\begin{eqnarray*} \textrm{HomMat3DRotate} = \textrm{HomMat3D} \cdot \mvHomMatrixThreeDRotTrans{\mvRotationMatrixVar{}{y}} {\mvVectorThreeDPlain{0}{0}{0}} \qquad \mvRotationMatrixVar{}{y} = \mvMatrix{ \cos(\textrm{Phi}) & 0 & \sin(\textrm{Phi}) \\ 0 & 1 & 0 \\ - \sin(\textrm{Phi}) & 0 & \cos(\textrm{Phi})} \end{eqnarray*}\]

Axisaxisaxis = 'z'"z":

\[\begin{eqnarray*} \textrm{HomMat3DRotate} = \textrm{HomMat3D} \cdot \mvHomMatrixThreeDRotTrans{\mvRotationMatrixVar{}{z}} {\mvVectorThreeDPlain{0}{0}{0}} \qquad \mvRotationMatrixVar{}{z} = \mvMatrix{ \cos(\textrm{Phi}) & - \sin(\textrm{Phi}) & 0 \\ \sin(\textrm{Phi}) & \cos(\textrm{Phi}) & 0 \\ 0 & 0 & 1} \end{eqnarray*}\]

Axisaxisaxis = [x, y, z][x, y, z]:

\[\begin{eqnarray*} \textrm{HomMat3DRotate} = \textrm{HomMat3D} \cdot \mvHomMatrixThreeDRotTrans{\mvRotationMatrixVar{}{a}} {\mvVectorThreeDPlain{0}{0}{0}} \qquad \mvRotationMatrixVar{}{a} = \mvVectorVar{u} \cdot \mvTranspose{\mvVectorVar{u}} + cos(\textrm{Phi}) \cdot (\mvIdentMatrixVar - \mvVectorVar{u} \cdot \mvTranspose{\mvVectorVar{u}}) + sin(\textrm{Phi}) \cdot \mvMatrixVar{S} \end{eqnarray*}\]

\[\begin{eqnarray*} \mvVectorVar{u} = \frac{\textrm{Axis}}{\|\textrm{Axis}\|} = \mvVectorThreeD{x'}{y'}{z'} \qquad \mvIdentMatrixVar = \mvMatrix{1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1} \qquad \mvMatrixVar{S} = \mvMatrix{0 & -z' & y' \\ z' & 0 & -x' \\ -y' & x' & 0} \end{eqnarray*}\]

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

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 \(\mvHomMatrixThreeDElements{ ra & rb & rc & td \\ re & rf & rg & th \\ ri & rj & rk & tl}\) 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🔗

Execution information

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

Parameters🔗

HomMat3DhomMat3Dhom_mat_3d (input_control) hom_mat3d → (real)HTuple (double)HHomMat3D, HTuple (double)Sequence[float]Htuple (double)

Input transformation matrix.

Phiphiphi (input_control) angle.rad → (real / integer)HTuple (double / Hlong)HTuple (double / int / long)Union[float, int]Htuple (double / Hlong)

Rotation angle.

Default: 0.780.78
Suggested values: 0.1, 0.2, 0.3, 0.4, 0.78, 1.57, 3.140.1, 0.2, 0.3, 0.4, 0.78, 1.57, 3.14
Value range: 0 ≤ Phi ≤ 6.28318530718

Axisaxisaxis (input_control) string(-array) → (string / real / integer)HTuple (HString / double / Hlong)HTuple (string / double / int / long)MaybeSequence[Union[str, float, int]]Htuple (char* / double / Hlong)

Axis, to be rotated around.

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

HomMat3DRotatehomMat3DRotatehom_mat_3drotate (output_control) hom_mat3d → (real)HTuple (double)HHomMat3D, HTuple (double)Sequence[float]Htuple (double)

Output transformation matrix.

Result🔗

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

Combinations with other operators🔗

Combinations

Possible predecessors

hom_mat3d_identityHomMat3dIdentity, hom_mat3d_translate_localHomMat3dTranslateLocal, hom_mat3d_scale_localHomMat3dScaleLocal, hom_mat3d_rotate_localHomMat3dRotateLocal

Possible successors

hom_mat3d_translate_localHomMat3dTranslateLocal, hom_mat3d_scale_localHomMat3dScaleLocal, hom_mat3d_rotate_localHomMat3dRotateLocal

Module🔗

Foundation