变换 2024.5.24

快速入门

从Python包索引安装Transformations包及其所有依赖项。

python -m pip install -U transformations

请参阅示例以了解如何使用编程接口。

源代码和支持可在GitHub上找到。

需求

此修订版已与以下需求和依赖项进行测试（其他版本可能也适用）

• CPython 3.9.13, 3.10.11, 3.11.9, 3.12.3

• NumPy 1.26.4

修订版

2024.5.24

• 修复GitHub上docstring示例未正确渲染的问题。

2024.4.24

• 支持NumPy 2。

2024.1.6

• 移除对Python 3.8和numpy 1.22（NEP 29）的支持。

2022.9.26

• 在叠加矩阵上添加维度检查（#2）。

2022.8.26

• 更新元数据。

• 移除对Python 3.7（NEP 29）的支持。

2021.6.6

• 移除对Python 3.6（NEP 29）的支持。

2020.1.1

• 移除对Python 2.7和3.5的支持。

2019.4.22

• 修复设置要求。

注意

Transformations.py不再积极开发，存在一些已知问题和数值不稳定性。该模块主要被其他3D变换和四元数模块所取代。

• Pytransform3d

• Scipy.spatial.transform

• Transforms3d (包含此模块的大部分代码)

• Numpy-quaternion

• Blender.mathutils

API 还不稳定，预计在版本之间会发生变化。

此 Python 代码未针对速度进行优化。有关某些函数的更快实现，请参考 transformations.c 模块。

可以使用 epydoc 生成 HTML 格式的文档。

可以使用 numpy.linalg.inv(M) 使用 numpy.linalg.inv(M) 逆矩阵，使用 numpy.dot(M0, M1) 连接矩阵，或者使用 numpy.dot(M, v) 转换齐次坐标数组 (v)，其中 v 为形状 (4, -1) 的列向量，分别使用 numpy.dot(v, M.T) 转换形状 (-1, 4) 的行向量（“点数组”）。

此模块遵循“右列列向量”和“行主存储”（C 连续）约定。平移分量位于变换矩阵的右侧列，即 M[:3, 3]。可能需要使用变换矩阵的转置来与其他图形系统接口，例如 OpenGL 的 glMultMatrixd()。另请参阅 [16]。

计算使用 numpy.float64 精度执行。

期望向量、点、四元数和矩阵函数参数为“类似数组”，即元组、列表或 numpy 数组。

除非另有说明，返回类型为 numpy 数组。

除非另有说明，角度以弧度为单位。

四元数 w+ix+jy+kz 表示为 [w, x, y, z]。

三个欧拉角可以以 24 种方式应用/解释，可以使用 4 个字符字符串或编码 4-元组进行指定。

轴 4 字符串：例如，'sxyz' 或 'ryxy'

• 第一个字符：应用于 's' 静态或 'r' 旋转框架的旋转

• 其余字符：连续旋转轴 'x'、'y' 或 'z'

轴 4-元组：例如，(0, 0, 0, 0) 或 (1, 1, 1, 1)

• 内轴：最右侧矩阵的轴代码（'x'：0，'y'：1，'z'：2）

• 奇偶性：如果内轴 'x' 后跟 'y'，'y' 后跟 'z'，或 'z' 后跟 'x'，则偶数（0）。否则为奇数（1）。

• 重复：第一个和最后一个轴相同（1）或不同（0）。

• 框架：旋转应用于静态（0）或旋转（1）框架。

参考文献

1. 矩阵和变换。罗纳德·戈尔登。在“图形宝石 I”中，第 472-475 页。Morgan Kaufmann，1990 年。

2. 更多矩阵和变换：剪切和伪透视。罗纳德·戈尔登。在“图形宝石 II”中，第 320-323 页。Morgan Kaufmann，1991 年。

3. 将矩阵分解为简单变换。斯宾塞·托马斯。在“图形宝石 II”中，第 320-323 页。Morgan Kaufmann，1991 年。

4. 从变换矩阵中恢复数据。罗纳德·戈尔登。在“图形宝石 II”中，第 324-331 页。Morgan Kaufmann，1991 年。

5. 欧拉角转换。肯·绍梅克。在“图形宝石 IV”中，第 222-229 页。Morgan Kaufmann，1994 年。

6. 弧球旋转控制。肯·绍梅克。在“图形宝石 IV”中，第 175-192 页。Morgan Kaufmann，1994 年。

7. 表示姿态：欧拉角、单位四元数和旋转矢量。詹姆斯·迪贝尔。2006 年。

8. 讨论解决两个向量集之间最佳旋转的方案。W Kabsch。Acta Cryst. 1978. A34，827-828。

9. 使用单位四元数的绝对方位的闭式解。BKP Horn。J Opt Soc Am A. 1987. 4(4):629-642。

10. 四元数。肯·绍梅克。http://www.sfu.ca/~jwa3/cmpt461/files/quatut.pdf

11. 从四元数到矩阵及其返回。JMP van Waveren。2005 年。http://www.intel.com/cd/ids/developer/asmo-na/eng/293748.htm

12. 均匀随机旋转。肯·绍梅克。在“图形宝石 III”中，第 124-132 页。Morgan Kaufmann，1992 年。

13. 分子建模中的四元数。CFF Karney。J Mol Graph Mod，25(5)：595-604

14. 从旋转矩阵中提取四元数的新方法。Itzhack Y Bar-Itzhack，J Guid Contr Dynam。2000。23(6)：1085-1087。

15. 计算机视觉中的多视图几何。作者：Hartley和Zissermann。剑桥大学出版社；第2版。2004年。第4章，算法4.7，第130页。

16. 列向量与行向量。http://steve.hollasch.net/cgindex/math/matrix/column-vec.html

示例

>>> alpha, beta, gamma = 0.123, -1.234, 2.345
>>> origin, xaxis, yaxis, zaxis = [0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]
>>> I = identity_matrix()
>>> Rx = rotation_matrix(alpha, xaxis)
>>> Ry = rotation_matrix(beta, yaxis)
>>> Rz = rotation_matrix(gamma, zaxis)
>>> R = concatenate_matrices(Rx, Ry, Rz)
>>> euler = euler_from_matrix(R, 'rxyz')
>>> numpy.allclose([alpha, beta, gamma], euler)
True
>>> Re = euler_matrix(alpha, beta, gamma, 'rxyz')
>>> is_same_transform(R, Re)
True
>>> al, be, ga = euler_from_matrix(Re, 'rxyz')
>>> is_same_transform(Re, euler_matrix(al, be, ga, 'rxyz'))
True
>>> qx = quaternion_about_axis(alpha, xaxis)
>>> qy = quaternion_about_axis(beta, yaxis)
>>> qz = quaternion_about_axis(gamma, zaxis)
>>> q = quaternion_multiply(qx, qy)
>>> q = quaternion_multiply(q, qz)
>>> Rq = quaternion_matrix(q)
>>> is_same_transform(R, Rq)
True
>>> S = scale_matrix(1.23, origin)
>>> T = translation_matrix([1, 2, 3])
>>> Z = shear_matrix(beta, xaxis, origin, zaxis)
>>> R = random_rotation_matrix(numpy.random.rand(3))
>>> M = concatenate_matrices(T, R, Z, S)
>>> scale, shear, angles, trans, persp = decompose_matrix(M)
>>> numpy.allclose(scale, 1.23)
True
>>> numpy.allclose(trans, [1, 2, 3])
True
>>> numpy.allclose(shear, [0, math.tan(beta), 0])
True
>>> is_same_transform(R, euler_matrix(axes='sxyz', *angles))
True
>>> M1 = compose_matrix(scale, shear, angles, trans, persp)
>>> is_same_transform(M, M1)
True
>>> v0, v1 = random_vector(3), random_vector(3)
>>> M = rotation_matrix(angle_between_vectors(v0, v1), vector_product(v0, v1))
>>> v2 = numpy.dot(v0, M[:3, :3].T)
>>> numpy.allclose(unit_vector(v1), unit_vector(v2))
True