{"id":8603,"library":"roma","title":"RoMa: 3D Rotations in PyTorch","description":"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..","status":"active","version":"1.5.6","language":"en","source_language":"en","source_url":"https://github.com/naver/roma","tags":["pytorch","3d-rotations","quaternions","rotation-matrices","deep-learning","computer-vision","geometric-deep-learning"],"install":[{"cmd":"pip install roma","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Core deep learning framework dependency for tensor operations and automatic differentiation.","package":"torch"},{"reason":"Optional 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.","package":"torch-batch-svd","optional":true}],"imports":[{"symbol":"roma","correct":"import roma"},{"symbol":"roma.utils","correct":"import roma.utils"}],"quickstart":{"code":"import torch\nimport roma\n\n# Example: Convert a batch of rotation vectors to unit quaternions and then to rotation matrices\nbatch_shape = (2, 3) # Example: 2 batches of 3 rotations each\n\n# Generate random rotation vectors (3D tensor)\nrotvec = torch.randn(batch_shape + (3,))\nprint(f\"Rotation vector shape: {rotvec.shape}\")\n\n# Convert rotation vectors to unit quaternions (XYZW convention)\nq = roma.rotvec_to_unitquat(rotvec)\nprint(f\"Unit quaternion shape: {q.shape}\")\n\n# Convert unit quaternions to rotation matrices (3x3 tensor)\nR = roma.unitquat_to_rotmat(q)\nprint(f\"Rotation matrix shape: {R.shape}\")\n\n# Direct conversion from rotation vector to rotation matrix\nR_direct = roma.rotvec_to_rotmat(rotvec)\nprint(f\"Direct Rotation matrix shape: {R_direct.shape}\")\nassert torch.allclose(R, R_direct, atol=1e-6)\n\n# Example: Special Procrustes orthonormalization\n# Projects an arbitrary 3x3 matrix onto the closest rotation matrix\nrandom_matrix = torch.randn(batch_shape + (3, 3))\nR_procrustes = roma.special_procrustes(random_matrix)\nprint(f\"Procrustes orthonormalized matrix shape: {R_procrustes.shape}\")","lang":"python","description":"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."},"warnings":[{"fix":"Prefer `roma.rotvec_to_unitquat`, `roma.unitquat_to_rotmat`, or `roma.rotvec_to_rotmat` for internal computations and transformations.","message":"Euler 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.","severity":"gotcha","affected_versions":"All versions"},{"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()`.","message":"Some 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"<1.8"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install roma` to install the library.","cause":"The 'roma' package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'roma'"},{"fix":"Install the recommended dependency: `pip install torch-batch-svd`. Alternatively, upgrade your PyTorch installation to version 1.8 or newer, which includes similar optimizations natively.","cause":"Using `roma.special_procrustes` on a CUDA-enabled GPU with an older PyTorch version (<1.8) without the optional `torch-batch-svd` dependency, leading to a performance warning/error (though it might still run slowly).","error":"RuntimeError: `special_procrustes` on CUDA GPUs with PyTorch < 1.8 requires `torch-batch-svd` for speed-up. Please install it using `pip install torch-batch-svd`."}]}