RoMa快速入门旋转矩阵、四元数、旋转向量与欧拉角互转全解教程【免费下载链接】romaRoMa: A lightweight library to deal with 3D rotations in PyTorch.项目地址: https://gitcode.com/gh_mirrors/roma1/romaRoMaRotation Manipulation是一个面向 PyTorch 的轻量级 3D 旋转处理库专为 PyTorch 中的 3D 旋转设计。它提供旋转矩阵、四元数、旋转向量、欧拉角四种常用表示之间的可微互转以及刚体变换、测地距离、球面插值等旋转空间工具是机器学习与梯度优化场景中处理 3D 旋转的实用工具箱。为什么需要 RoMa在 3D 视觉、机器人学、姿态估计等领域旋转的表达方式五花八门表示方式维度特点旋转矩阵 RotMat3×3直观、可线性应用但参数冗余四元数 UnitQuat4无万向锁、插值稳定但约束多旋转向量 RotVec3紧凑适合回归网络输出欧拉角 Euler3人类易读但存在奇异点手动实现这些表示的互转既容易出错又难以保证反向传播时梯度的正确性。RoMa 的核心价值在于所有映射都是可微的可以直接嵌入神经网络做端到端训练这在 roma/mappings.py 中通过自定义 SVD 的 backward 实现见ProcrustesWithJVP相关逻辑保证了从任意 3×3 矩阵回归旋转矩阵时的梯度质量。一键安装最快配置方法安装只需一行 pip 命令pip install roma导入后即可使用全部 API 通过 roma/init.py 统一导出无需关心子模块结构。四表示互转核心 API 速查1. 旋转向量 ↔ 四元数 ↔ 旋转矩阵这是最常用的转换链路对应 roma/mappings.py 中的函数import torch import roma rotvec torch.randn(2, 3, 3) # 支持任意批次维度 q roma.rotvec_to_unitquat(rotvec) # 旋转向量 - 四元数 (xyzw) R roma.unitquat_to_rotmat(q) # 四元数 - 旋转矩阵 Rbis roma.rotvec_to_rotmat(rotvec) # 旋转向量 - 旋转矩阵一步到位反向转换同样一步完成R roma.rotmat_to_unitquat(q) # 实际为 rotmat_to_unitquat(R) rotvec roma.rotmat_to_rotvec(R) 注意RoMa 的四元数默认采用xyzw排列顺序。若你的数据来自其他库如 wxyz 顺序可用roma.quat_xyzw_to_wxyz()/roma.quat_wxyz_to_xyzw()快速转换。2. 欧拉角支持任意轴序欧拉角转换实现在 roma/euler.py 中convention参数接受如 xyz、ZYX 等任意轴序字符串且支持角度/弧度切换# 欧拉角deg- 四元数 / 旋转向量 / 旋转矩阵 q roma.euler_to_unitquat(xyz, angles, degreesTrue) rv roma.euler_to_rotvec(xyz, angles) R roma.euler_to_rotmat(ZYX, angles) # 四元数 / 旋转矩阵 - 欧拉角 angles roma.unitquat_to_euler(xyz, q, degreesTrue) angles roma.rotmat_to_euler(xyz, R)从任意输入回归旋转矩阵如果你的网络输出是一个接近旋转但不严格正交的 3×3 矩阵直接loss到目标矩阵会破坏旋转约束。RoMa 提供三条投影路径均在 roma/mappings.py函数输入说明roma.special_procrustes(M)3×3 任意矩阵SVD 正交化最通用的做法roma.special_gramschmidt(M)3×2 矩阵6D 连续旋转表示Zhou et al. 方案roma.symmatrixvec_to_unitquat(x)10 维向量从 4×4 对称矩阵系数恢复四元数R roma.special_procrustes(torch.randn(2, 3, 3))相关回归方法还可参考项目论文Deep Regression on Manifolds: a 3D Rotation Case Study3DV 2021。旋转空间度量与插值判断两个旋转差多远、在两个姿态之间平滑过渡是动画、SLAM 中的高频需求工具集中在 roma/utils.py测地距离旋转角度差R1, R2 roma.random_rotmat(size5), roma.random_rotmat(size5) theta roma.utils.rotmat_geodesic_distance(R1, R2) # 两矩阵间的最小旋转角球面线性插值SLERP沿测地线取最短路径比线性插值更平滑steps torch.linspace(0, 1.0, 5) rotvec_interp roma.rotvec_slerp(rotvec0, rotvec1, steps) q_interp roma.unitquat_slerp(q0, q1, steps)此外还有quat_product四元数乘法、quat_conjugation共轭、rotvec_inverse求逆等基础算子完整示例可参考 examples/snippets/quat_operations.py 与 examples/snippets/rotvec_slerp.py。进阶刚体变换 Rigid当旋转还要配合平移时roma/transforms.py 提供了roma.Rigid类把旋转矩阵 R 和平移向量 t 封装为刚体变换t torch.randn(2, 3) T roma.Rigid(R, t) identity T T.inverse() # 变换与其逆相乘 单位变换 M identity.to_homogeneous() # 转为 4×4 齐次矩阵运算符用于变换复合T.apply(v)对点集应用变换T.inverse()求逆变换非常适合机器人学中的坐标帧计算。新手常见问题 FAQQ1批次维度怎么处理所有 API 都自动支持任意前缀批次维度batch dimstorch.randn(2, 3, 3)、torch.randn(4, 5, 3)均可直接传入无需手动reshape。Q2为什么我的四元数转出来是 xyzw 而不是 wxyzRoMa 统一使用quat [x, y, z, w]顺序与其他库交换数据时记得先做顺序转换。Q3欧拉角转矩阵出现 NaN欧拉角在特定姿态存在万向锁Gimbal Lock若下游对角度精度敏感建议优先用四元数或旋转向量表示。Q4想校验自己的矩阵是否是合法旋转矩阵用roma.utils.is_rotation_matrix(R)即可检查正交性与行列式为 1。总结RoMa 用一行pip install就能补齐 PyTorch 生态中 3D 旋转的完整拼图四种表示互转、旋转回归、度量与插值、刚体变换全部可微可用。无论是训练姿态估计网络还是做基于梯度的 3D 重建从 README.md 的使用示例出发配合 examples/snippets/ 下的代码片段即可快速上手。【免费下载链接】romaRoMa: A lightweight library to deal with 3D rotations in PyTorch.项目地址: https://gitcode.com/gh_mirrors/roma1/roma创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考