Geometry utilities#

Genesis World ships a library of geometry helpers for rotations, quaternions, and rigid transforms. They are exposed both at the top level as gs.<name> and under genesis.utils.geom, and they accept NumPy arrays or PyTorch tensors, operating on single values or batches. Use them to build poses, convert between rotation representations, and transform points between frames.

All of them follow the project conventions: quaternions are (w, x, y, z) scalar-first (Hamilton), euler_to_quat and euler_to_R take degrees in extrinsic x-y-z order, and the world frame is right-handed and Z-up. See Conventions for the full set.

import genesis as gs

gs.init()

# Euler (degrees, extrinsic x-y-z) to quaternion (w, x, y, z)
quat = gs.euler_to_quat((0, 0, 90))

# Rotate a point by a quaternion
p_world = gs.transform_by_quat((1.0, 0.0, 0.0), quat)

# Apply a full rigid transform: rotate then translate
p_world = gs.transform_by_trans_quat((1.0, 0.0, 0.0), trans=(0, 0, 1), quat=quat)

Rotation conversions#

Rotations can be expressed as Euler angles, quaternions, 3×3 matrices, rotation vectors, or 4×4 homogeneous transforms. These convert between them.

Function	Converts
`euler_to_quat(euler_xyz)`	Euler degrees (extrinsic x-y-z) to quaternion
`euler_to_R(euler_xyz)`	Euler degrees to 3×3 rotation matrix
`xyz_to_quat(xyz, rpy=False, degrees=False)`	Euler angles to quaternion, with unit and order options
`quat_to_xyz(quat, rpy=False, degrees=False)`	Quaternion to Euler angles
`quat_to_R(quat)` / `R_to_quat(R)`	Quaternion ↔ rotation matrix
`R_to_xyz(R, rpy=False, degrees=False)`	Rotation matrix to Euler angles
`axis_angle_to_quat(angle, axis)` / `axis_angle_to_R(axis, theta)`	Axis-angle to quaternion or matrix
`quat_to_rotvec(quat)` / `rotvec_to_quat(rotvec)`	Quaternion ↔ rotation vector (axis × angle)

Note

Argument order differs between axis_angle_to_quat(angle, axis) (angle first) and axis_angle_to_R(axis, theta) (axis first).

Quaternion operations#

Function	Result
`inv_quat(quat)`	Inverse (conjugate for unit quaternions)
`transform_quat_by_quat(v, u)`	Quaternion product, composing rotation `v` by `u`
`transform_by_quat(v, quat)`	Rotate vector `v` by `quat`
`inv_transform_by_quat(pos, quat)`	Rotate `pos` by the inverse of `quat`
`slerp(q0, q1, t)`	Spherical linear interpolation at fraction `t`
`identity_quat()`	The identity quaternion `(1, 0, 0, 0)`

Rigid transforms#

A rigid transform is a rotation plus a translation, stored either as a (trans, quat) pair or as a 4×4 homogeneous matrix T.

Function	Result
`transform_by_trans_quat(pos, trans, quat)`	Rotate `pos` by `quat`, then add `trans`
`inv_transform_by_trans_quat(pos, trans, quat)`	Inverse of the above
`trans_quat_to_T(trans, quat)` / `T_to_trans_quat(T)`	`(trans, quat)` ↔ 4×4 matrix
`trans_R_to_T(trans, R)`	Build a 4×4 matrix from translation and rotation matrix
`transform_by_T(pos, T)` / `inv_transform_by_T(pos, T)`	Apply `T` (or its inverse) to `pos`
`pos_lookat_up_to_T(pos, lookat, up)`	Camera extrinsics: eye, target, up to a 4×4 matrix

Vectors#

Function	Result
`normalize(x, eps=1e-12)`	Scale a vector or batch to unit length
`spherical_to_cartesian(theta, phi)`	Spherical angles to a unit `(x, y, z)` direction

Example: orienting an entity#

import genesis as gs

gs.init()
scene = gs.Scene()
box = scene.add_entity(gs.morphs.Box(pos=(0, 0, 0.5), size=(1.0, 1.0, 1.0)))
scene.build()

# Rotate 45 degrees about the world Z axis.
box.set_quat(gs.euler_to_quat((0, 0, 45)))