rotation

Rotation conversion utilities shared across NumPy and Torch pipelines.

All functions accept either :class:numpy.ndarray or :class:torch.Tensor and return the same type. SCIPY_ARRAY_API=1 enables scipy to operate natively on torch tensors, avoiding device transfers for batched workloads.

References

so3_primer — reference implementation of rotation-representation RL * to_rotation — rotations.rotations.RotType.from_array, rotations.envs.actions.*_rotation * rotation_to_values — rotations.rotations.RotType.as_array * scale_rotation — rotations.rotations.quat_scale, rotations.rotations.jax_rot_pow * project_rotmat — rotations.rotations.rot_mat_svd * sanitize_rotation — implicit in rotations.envs.actions.*_rotation (clip + project) * compose_rel_rotation — rotations.envs.actions.rel_*_rotation * clamp_rotation_delta — rotations.envs.rot.rotation_dynamics

函数：

名称	描述
to_rotation	Convert a state dict or representation array/tensor to Rotation.
rotation_to_values	Convert a scipy :class:Rotation to an array/tensor.
scale_rotation	Scale a rotation by raising it to scale while preserving quat sign.
project_rotmat	SVD-project a (..., 9) or (..., 3, 3) vector onto SO(3).
sanitize_rotation	Ensure values is a valid element of the representation key.
clamp_rotation_delta	Clamp the angle of the delta R_cur.inv() * R_abs to ≤ step_len * π.
compose_rel_rotation	Compose delta rotations in target with current state rotation.

to_rotation

to_rotation(values, key: str | None = None) -> Rotation

Convert a state dict or representation array/tensor to Rotation.

When key is None, values is treated as a state dict and the first available attitude key (in priority order att_rotmat, att_quat, att_rotvec, att_euler) is used. Rotation matrices are sanitised via :func:project_rotmat before conversion.

参数：

名称	类型	描述	默认
values		State dict when key is None; otherwise an array in the representation given by key.	必需
key	str | None	One of att_euler, att_quat, att_rotmat, att_rotvec. When None, resolve the first available attitude key from values.	None

返回：

类型	描述
Rotation	Scipy Rotation.

rotation_to_values

rotation_to_values(rot: Rotation, key: str)

Convert a scipy :class:Rotation to an array/tensor.

参数：

名称	类型	描述	默认
rot	Rotation	Scipy Rotation.	必需
key	str	Output representation (att_euler, att_quat, att_rotmat, att_rotvec).	必需

返回：

类型	描述
	Array or tensor in the representation given by key.

scale_rotation

scale_rotation(rot: Rotation, scale: float) -> Rotation

Scale a rotation by raising it to scale while preserving quat sign.

Used in the rel_scale path to shrink a delta rotation proportionally to the control time step. For euler and rotvec representations, pre-scale the raw deltas before calling :func:to_rotation instead.

References

so3_primer.rotations.rotations.jax_rot_pow / so3_primer.rotations.rotations.quat_scale

参数：

名称	类型	描述	默认
rot	Rotation	Rotation delta to scale.	必需
scale	float	Scaling factor (typically step_len ∈ (0, 1]).	必需

返回：

类型	描述
Rotation	Fractional rotation rot ** scale with consistent sign.

project_rotmat

project_rotmat(x)

SVD-project a (..., 9) or (..., 3, 3) vector onto SO(3).

Uses the least-squares orthogonal Procrustes projection with a determinant correction (det=+1). Works with both numpy and torch tensors.

References

so3_primer.rotations.rotations.rot_mat_svd

sanitize_rotation

sanitize_rotation(values, key: str)

Ensure values is a valid element of the representation key.

• att_rotmat: SVD-project to SO(3) via :func:project_rotmat.
• att_euler, att_rotvec: identity (always valid).
• att_quat: identity — the policy projection layer guarantees unit-norm and (for quat_plus) w ≥ 0. Distribution-sampled noise is exploration, not a correctness issue; scipy Rotation.from_quat handles normalisation downstream.

References

Implicit in so3_primer.rotations.envs.actions (per-representation clip + project).

返回：

类型	描述
	Sanitised array/tensor.

clamp_rotation_delta

clamp_rotation_delta(R_cur: Rotation, R_abs: Rotation, step_len: float) -> Rotation

Clamp the angle of the delta R_cur.inv() * R_abs to ≤ step_len * π.

Used in the rel_scale path to prevent the commanded rotation from exceeding the physical limits of one control step.

Uses the rotation-vector form to avoid Rotation.__pow__ with batched scales (which scipy does not support).

References

so3_primer.rotations.envs.rot.rotation_dynamics

参数：

名称	类型	描述	默认
R_cur	Rotation	Current rotation.	必需
R_abs	Rotation	Desired absolute rotation.	必需
step_len	float	Control time step in seconds.	必需

返回：

类型	描述
Rotation	Clamped absolute rotation.

compose_rel_rotation

compose_rel_rotation(state: dict, target: dict, control_mask: dict, *, step_len: float | None = None) -> None

Compose delta rotations in target with current state rotation.

Iterates over state to resolve the current rotation, then composes each delta in target whose key appears in control_mask as R_cur * R_delta.

When step_len is provided (rel_scale path):

• For att_quat / att_rotmat: the delta is scaled via :func:scale_rotation after conversion.
• For att_euler / att_rotvec: the raw delta values are pre-scaled by step_len before conversion (additive scaling).
• After composition, the total delta is clamped to ≤ step_len * π via :func:clamp_rotation_delta.

References

so3_primer.rotations.envs.actions.rel_*_rotation and so3_primer.benchmarks.*.utils.*.build_action_fn

The result replaces the values in target in-place.