RoMa完整指南：PyTorch 3D旋转工具箱，一站搞定四元数、旋转矩阵与欧拉角互转

RoMa完整指南PyTorch 3D旋转工具箱一站搞定四元数、旋转矩阵与欧拉角互转【免费下载链接】romaRoMa: A lightweight library to deal with 3D rotations in PyTorch.项目地址: https://gitcode.com/gh_mirrors/roma1/romaRoMa是一个轻量级的PyTorch 3D 旋转操作库Rotation Manipulation为机器学习与梯度优化提供可微分的 3D 旋转表示转换四元数、旋转矩阵、旋转向量与欧拉角互转还内置旋转空间度量、SLERP 球面插值、6D 旋转回归和刚体点云配准让姿态估计、三维重建与机器人学任务一步到位。 什么是 RoMa为什么需要它在 3D 视觉、SLAM、机器人控制中一个物体怎么转可以用多种数学形式描述旋转矩阵rotmat3×3 正交矩阵直观但冗余单位四元数unitquat4 维向量无万向锁GPU 批量运算高效旋转向量rotvec3 维向量角度 × 轴最紧凑欧拉角 / Tait-Bryan 角人类可读但存在万向锁。RoMa 把这些表示之间的转换全部实现为可微分函数——也就是说神经网络可以直接输出这些量并做反向传播小角度等数值边界情况也经过专门处理避免了学术代码里常见的 NaN 梯度问题。 快速安装一条命令完成最简单的方式是通过 pip 直接安装pip install roma如果想使用最新源码版本可以克隆仓库后本地安装git clone https://gitcode.com/gh_mirrors/roma1/roma cd roma pip install .项目元信息见 pyproject.toml源码采用 3-Clause BSD 许可证见 LICENSE。安装后验证一下python -m unittest即可运行完整的单元测试套件位于test/目录。 RoMa 支持的 4 种旋转表示表示张量形状特点旋转向量 rotvec...x3最紧凑轴角形式单位四元数 unitquat...x4XYZW 约定计算稳定旋转矩阵 rotmat...x3x3列向量约定R x欧拉角 euler...x3支持任意旋转约定如xyzRoMa 的所有函数都支持任意数量的批次维度batch dims——无论你的数据形状是(3,)、(2,3)还是(B,H,W,3)同一套 API 都能直接批量处理这在大规模训练中非常省心。 核心功能一四种表示自由互转RoMa 在 roma/mappings.py 和 roma/euler.py 中提供了完整的互转矩阵rotvec_to_unitquat/unitquat_to_rotvec旋转向量 ↔ 四元数unitquat_to_rotmat/rotmat_to_unitquat四元数 ↔ 旋转矩阵rotvec_to_rotmat/rotmat_to_rotvec旋转向量 ↔ 旋转矩阵euler_to_unitquat/rotmat_to_euler欧拉角与其余表示互转支持degreesTrue度数模式quat_xyzw_to_wxyz不同四元数分量约定的转换典型流程示例更多可参考 examples/snippets/rotvec_to_unitquat.pyimport torch, roma rotvec torch.randn(2, 3, 3) q roma.rotvec_to_unitquat(rotvec) # 转四元数 R roma.unitquat_to_rotmat(q) # 转旋转矩阵 euler roma.unitquat_to_euler(xyz, q, degreesTrue) # 转欧拉角度 核心功能二从任意输出回归合法旋转Procrustes / 6D 表示做姿态回归时网络输出往往不是合法旋转。RoMa 在 roma/mappings.py 中提供了三种从欧氏空间到旋转空间的可微映射函数输入形状说明special_procrustes...x3x3将任意 3×3 矩阵投影到最近旋转矩阵推荐special_gramschmidt...x3x26D 旋转表示转换Zhou et al. 的流行方案symmatrixvec_to_unitquat...x1010 维对称矩阵向量 → 四元数对偶# 把网络输出的任意 3x3 矩阵修正为合法旋转矩阵 R roma.special_procrustes(torch.randn(4, 3, 3))procrustes还支持前向模式微分torch.func.jvp/jacfwd/vmap方便做高阶导数研究。相关数值精度讨论可见test/test_procrustes_derivatives.py。 核心功能三旋转空间度量与 SLERP 插值roma/utils.py 内置了旋转空间的常用工具距离度量rotmat_geodesic_distance测地距离比朴素实现精度高得多小角度下也不产生 NaN 梯度、rotvec_geodesic_distance、unitquat_geodesic_distance、rotmat_cosine_angle四元数运算quat_product、quat_conjugation、quat_normalize、quat_action旋转作用到向量组合与求逆rotmat_composition、rotvec_inverse等SLERP 球面插值unitquat_slerp、rotvec_slerp最短路径、rotmat_slerp还有 GPU 加速版unitquat_slerp_fast随机采样random_rotmat、random_unitquat、random_rotvec便于数据增强与测试。# 两个旋转向量之间按最短路径做 5 步球面插值 steps torch.linspace(0, 1.0, 5) rotvecs roma.rotvec_slerp(rotvec0, rotvec1, steps)完整示例见 examples/snippets/rotvec_slerp.py 与 examples/snippets/metrics.py。 核心功能四刚体变换与点云配准roma/transforms.py 提供了面向应用的变换类Rigid旋转矩阵 平移向量的刚体变换支持组合、.inverse()求逆、.to_homogeneous()导出 4×4 齐次矩阵RigidUnitQuat用四元数参数化的版本可直接与Rigid互转Orthogonal/ScalingOrthogonal/Scale等中间变换类按需组合。配合 roma/utils.py 中的rigid_points_registration与rigid_vectors_registration可以一键对齐两组点云经典 ICP 预处理、Sim(3) 对齐# 用 Procrustes 对齐两组点 T, s roma.rigid_vectors_registration(x, y, compute_scalingTrue)示例参考 examples/snippets/rigid_registration.py 与 examples/snippets/transforms.py。 项目结构速览roma/ # 核心库源码 mappings.py # 表示互转 Procrustes/6D 回归 euler.py # 欧拉角映射 utils.py # 度量、四元数运算、SLERP、配准 transforms.py # Rigid / RigidUnitQuat 等变换类 internal.py # 批量维度等内部工具 examples/ # 各功能的最小示例 snippets/ # 按主题拆分的代码片段 test/ # 单元测试test_mappings.py、test_euler.py 等 docsource/ # Sphinx 文档源码官方 API 文档由 Sphinx 生成构建脚本为 build_doc.shexamples/下还有mapping_benchmark.py转换效率基准与geodesic_distance_comparison.py距离实现精度对比等进阶示例。✅ 总结RoMa 适合谁3D 视觉 / 姿态估计从业者网络直接回归旋转Procrustes 一步洗出合法旋转矩阵机器人 / 控制工程师四元数运算、变换组合求逆、点云配全都备齐研究生与学习者API 简洁、批次维度自由、数值处理严谨是 PyTorch 生态里最省心的 3D 旋转工具箱。一句话装好 RoMa四元数、旋转矩阵、旋转向量、欧拉角从此随便换反向传播一路畅通。【免费下载链接】romaRoMa: A lightweight library to deal with 3D rotations in PyTorch.项目地址: https://gitcode.com/gh_mirrors/roma1/roma创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考