Registry / ai-ml / roma
library1.5.6pypypiunverified

RoMa (Rotation Manipulation) is a lightweight Python library designed to simplify the handling of 3D rotations within PyTorch. It provides differentiable mappings between various 3D rotation representations (e.g., rotation vectors, quaternions, rotation matrices, Euler angles), mappings from Euclidean to rotation space, and a suite of utilities for rotation-related operations. It aims to be an easy-to-use and efficient toolbox for machine learning and gradient-based optimization applications. The current version is 1.5.6, with development actively maintained by NAVER Corp..

pip install roma
INSTALL
IMPORT
SIG · ROMA
R
roma
ai-mlpythonv1.5.6
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.5.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

roma
import roma
import roma

This quickstart demonstrates how to initialize `roma` and perform fundamental conversions between different 3D rotation representations: rotation vectors, unit quaternions, and rotation matrices. It also shows the use of `special_procrustes` to orthonormalize an arbitrary matrix into a valid rotation matrix.

import torch import roma # Example: Convert a batch of rotation vectors to unit quaternions and then to rotation matrices batch_shape = (2, 3) # Example: 2 batches of 3 rotations each # Generate random rotation vectors (3D tensor) rotvec = torch.randn(batch_shape + (3,)) print(f"Rotation vector shape: {rotvec.shape}") # Convert rotation vectors to unit quaternions (XYZW convention) q = roma.rotvec_to_unitquat(rotvec) print(f"Unit quaternion shape: {q.shape}") # Convert unit quaternions to rotation matrices (3x3 tensor) R = roma.unitquat_to_rotmat(q) print(f"Rotation matrix shape: {R.shape}") # Direct conversion from rotation vector to rotation matrix R_direct = roma.rotvec_to_rotmat(rotvec) print(f"Direct Rotation matrix shape: {R_direct.shape}") assert torch.allclose(R, R_direct, atol=1e-6) # Example: Special Procrustes orthonormalization # Projects an arbitrary 3x3 matrix onto the closest rotation matrix random_matrix = torch.randn(batch_shape + (3, 3)) R_procrustes = roma.special_procrustes(random_matrix) print(f"Procrustes orthonormalized matrix shape: {R_procrustes.shape}")
Debug
Known issues
gotchaEuler angles are prone to gimbal lock and numerical instability. While supported for convenience (e.g., user input/output), it's highly recommended to use quaternions or rotation matrices for actual computations to avoid these issues.
fix
Prefer `roma.rotvec_to_unitquat`, `roma.unitquat_to_rotmat`, or `roma.rotvec_to_rotmat` for internal computations and transformations.
affects: All versions
gotchaSome utility functions, such as `roma.utils.rotmat_inverse()`, may return a transposed 'view' of the input tensor. Performing in-place operations on these views can lead to unexpected side effects or alter the original tensor. Always clone the output if subsequent in-place modifications are intended.
fix
If modifying the output of `rotmat_inverse` or similar functions, ensure to call `.clone()` on the result, e.g., `R_inv = roma.utils.rotmat_inverse(R).clone()`.
affects: All versions
gotchaFor PyTorch versions below 1.8, `roma.special_procrustes()` on CUDA GPUs can be significantly slower if `torch-batch-svd` is not installed. This is a performance regression rather than a functional breaking change, but can severely impact efficiency.
fix
Install `torch-batch-svd` via `pip install torch-batch-svd` if using PyTorch < 1.8 and needing fast `special_procrustes` on GPU, or upgrade PyTorch to version 1.8 or newer.
affects: <1.8
Upgrade
Version history
1.5.6latest on PyPI · released Feb 11, 2026
Audit
Dependencies
torchrequiredCore deep learning framework dependency for tensor operations and automatic differentiation.
torch-batch-svdoptionalOptional dependency for significant speed-up with `special_procrustes` on CUDA GPUs when using PyTorch versions older than 1.8. Not needed for PyTorch >= 1.8.
Agent activity
44 hits · last 30 days
node
38
OpenAI (training)
1
Resources
roma — pip install roma · libregistry