nanomanifold

Fast, batched and differentiable SO(3)/SE(3) transforms for any backend (NumPy, PyTorch, JAX, ...)

Works directly on arrays, defined as:

• SO(3): unit quat quaternions with explicit convention="wxyz" or convention="xyzw", shape (..., 4)
• SE(3): concatenated [quat, translation], shape (..., 7)

import numpy as np
from nanomanifold import SO3, SE3

# Rotations stored as quaternion arrays, default convention="wxyz"
q = SO3.from_axis_angle(np.array([0, 0, 1]), np.pi/4)  # 45° around Z
points = np.array([[1, 0, 0], [0, 1, 0]])
rotated = SO3.rotate_points(q, points)

# Rigid transforms stored as 7D arrays [quat, translation]
T = SE3.from_rt(q, np.array([1, 0, 0]))  # rotation + translation
transformed = SE3.transform_points(T, points)

Installation

pip install nanomanifold

Quick Start

Rotations (SO3)

from nanomanifold import SO3

# Create rotations
q1 = SO3.from_axis_angle([1, 0, 0], np.pi/2)    # 90° around X
q2 = SO3.from_euler([0, 0, np.pi/4])            # 45° around Z
q3 = SO3.from_rotmat(rotation_matrix)

# Compose and interpolate
q_combined = SO3.multiply(q1, q2)
q_halfway = SO3.slerp(q1, q2, t=0.5)

# Apply to points
points = np.array([[1, 0, 0], [0, 1, 0]])
rotated = SO3.rotate_points(q_combined, points)

Rigid Transforms (SE3)

from nanomanifold import SE3

# Create transforms
T1 = SE3.from_rt(q1, [1, 2, 3])               # rotation + translation
T2 = SE3.from_matrix(transformation_matrix)

# Compose and interpolate
T_combined = SE3.multiply(T1, T2)
T_inverse = SE3.inverse(T_combined)
T_halfway = SE3.slerp(T1, T2, t=0.5)

# Apply to points
transformed = SE3.transform_points(T_combined, points)

API Reference

All functions are available via nanomanifold.SO3 and nanomanifold.SE3. Shapes follow the Array API convention and accept arbitrarily batched inputs.

SO3 (3D Rotations)

Supported SO3 parametrizations:

SE3 (Rigid Transforms)

Pairwise Conversions (SO3.conversions)

Convert directly between any two rotation representations without going through quaternions manually. Pairwise functions follow the naming pattern from_{source}_to_{target}.

Representations: axis_angle, euler, hinge, matrix, rotmat, quat, sixd. Quaternion conventions use lowercase convention="wxyz" or convention="xyzw". Hinge conversions take axes as a required second argument.

For runtime-selected conversions, use SO3.convert. src="matrix" treats the input as a generic 3x3 matrix and projects it to rotmat before converting. dst="matrix" is equivalent to dst="rotmat". Use src_kwargs and dst_kwargs for representation-specific options:

matrix = SO3.convert(axis_angle, src="axis_angle", dst="matrix")
rotmat = SO3.convert(matrix, src="matrix", dst="rotmat")
quat_from_matrix = SO3.convert(matrix, src="matrix", dst="quat")
quat_alt = SO3.convert(
    euler,
    src="euler",
    dst="quat",
    src_kwargs={"convention": "XYZ"},
    dst_kwargs={"convention": "xyzw"},
)
quat = SO3.convert(
    quat_alt,
    src="quat",
    dst="quat",
    src_kwargs={"convention": "xyzw"},
    dst_kwargs={"convention": "wxyz"},
)
euler = SO3.convert(rotmat, src="rotmat", dst="euler", dst_kwargs={"convention": "ZYX"})
angles = SO3.convert(rotmat, src="rotmat", dst="hinge", dst_kwargs={"axes": axes})

For constrained one-axis rotations, use SO3.from_hinge and SO3.to_hinge. The hinge helpers map (...,1) scalar coefficients to axis-angle vectors with angles * axes. to_hinge projects the principal axis-angle vector back onto axes; for unit axes this is the signed principal rotation angle.

Backend-Explicit Mode

By default, nanomanifold auto-detects the array backend from the input array type. Every function also accepts an optional xp keyword argument to specify the backend explicitly. This is required for torch.compile(fullgraph=True), since Dynamo cannot trace the dynamic dispatch:

import torch
from nanomanifold import SO3, SE3

@torch.compile(fullgraph=True)
def forward(q1, q2, T1, T2):
    q_mid = SO3.slerp(q1, q2, torch.tensor([0.5]), xp=torch)
    T_mid = SE3.slerp(T1, T2, torch.tensor([0.5]), xp=torch)
    return q_mid, T_mid