Geometry utilities

The genesis.utils.geom module provides geometry helpers for rotations, quaternions, and rigid transforms, also exposed at the top level as gs.<name>. They accept NumPy arrays or PyTorch tensors and operate on single values or batches.

They follow the project conventions: quaternions are (w, x, y, z) scalar-first (Hamilton), Euler angles are degrees in extrinsic x-y-z order, and the world frame is right-handed and Z-up. See Conventions.

Rotation conversions

genesis.utils.geom.euler_to_quat(euler_xyz)

genesis.utils.geom.euler_to_R(euler_xyz)

genesis.utils.geom.xyz_to_quat(xyz, rpy=False, degrees=False)

genesis.utils.geom.quat_to_xyz(quat, rpy=False, degrees=False)

genesis.utils.geom.quat_to_R(quat, *, out=None)

genesis.utils.geom.R_to_quat(R, *, out=None)

genesis.utils.geom.R_to_xyz(R, rpy=False, degrees=False)

genesis.utils.geom.axis_angle_to_quat(angle, axis)

genesis.utils.geom.axis_angle_to_R(axis: ndarray, theta: ndarray) → ndarray

genesis.utils.geom.quat_to_rotvec(quat: ndarray, out: ndarray | None = None) → ndarray

Compute the angle-axis representation of a single or a batch of quaternions (qw, qx, qy, qz).

Parameters:

• quat – N-dimensional array whose last dimension gathers the 4 quaternion coordinates (qw, qx, qy, qz).

• out – Pre-allocated array into which to store the result. If not provided, a new array is freshly-allocated and returned, which is slower.

genesis.utils.geom.rotvec_to_quat(rotvec: ndarray, out: ndarray | None = None) → ndarray

Compute the quaternion representation (qw, qx, qy, qz) of a single or a batch of angle-axis vectors.

Parameters:

• rotvec – N-dimensional array whose last dimension gathers the 3 angle-axis components angle * (ax, ay, az).

• out – Pre-allocated array into which to store the result. If not provided, a new array is freshly-allocated and returned, which is slower.

Quaternion operations

genesis.utils.geom.inv_quat(quat)

genesis.utils.geom.transform_quat_by_quat(v, u)

This method transforms quat_v by quat_u.

This is equivalent to quatmul(quat_u, quat_v) or R_u @ R_v

genesis.utils.geom.transform_by_quat(v, quat)

This method transforms quat_v by quat_u.

This is equivalent to quatmul(quat_u, quat_v) or R_u @ R_v

genesis.utils.geom.inv_transform_by_quat(pos, quat)

genesis.utils.geom.slerp(q0, q1, t)

Perform spherical linear interpolation between two quaternions.

Parameters:

• q0 (numpy.array | torch.Tensor) – The start quaternion (w, x, y, z), can be batched.

• q1 (numpy.array | torch.Tensor) – The end quaternion (w, x, y, z), can be batched.

• t (numpy.array | torch.Tensor) – The interpolation parameter between 0 and 1.

Returns:

The interpolated quaternion (w, x, y, z).

Return type:

numpy.array | torch.Tensor

genesis.utils.geom.identity_quat()

genesis.utils.geom.random_quaternion(batch_size)

Rigid transforms

genesis.utils.geom.transform_by_trans_quat(pos, trans, quat)

genesis.utils.geom.inv_transform_by_trans_quat(pos, trans, quat)

genesis.utils.geom.trans_quat_to_T(trans=None, quat=None, *, out=None)

genesis.utils.geom.T_to_trans_quat(T)

genesis.utils.geom.trans_R_to_T(trans=None, R=None, *, out=None)

genesis.utils.geom.transform_by_T(pos, T)

Transforms 3D points by a 4x4 transformation matrix or a batch of matrices, supporting both NumPy arrays and PyTorch tensors.

Parameters:

• pos (np.ndarray | torch.Tensor) – A numpy array or torch tensor of 3D points. Can be a single point (3,), a batch of points (B, 3), or a batched batch of points (B, N, 3).

• T (np.ndarray | torch.Tensor) – The 4x4 transformation matrix or a batch of B transformation matrices of shape (B, 4, 4). Must be of the same type as pos.

Return type:

The transformed points in a shape corresponding to the input dimensions.

genesis.utils.geom.inv_transform_by_T(pos, T)

genesis.utils.geom.pos_lookat_up_to_T(pos, lookat, up)

Vectors and sampling

genesis.utils.geom.normalize(x, eps: float = 1e-12)

genesis.utils.geom.spherical_to_cartesian(theta: Tensor, phi: Tensor) → tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Convert spherical coordinates to Cartesian coordinates.

Parameters:

• theta (torch.Tensor) – Horizontal angles in radians.

• phi (torch.Tensor) – Vertical angles in radians.

Returns:

vectors – Vectors in cartesian coordinates as tensor of shape (…, 3).

Return type:

torch.Tensor

genesis.utils.geom.generate_grid_points_on_plane(lo: tuple[float, float, float], hi: tuple[float, float, float], normal: tuple[float, float, float], nx: int, ny: int) → ndarray

Build an nx-by-ny grid of points on the plane defined by the bounds and normal.

Parameters:

• lo (array-like[float, float, float]) – Lower bound of the plane

• hi (array-like[float, float, float]) – Upper bound of the plane

• normal (array-like[float, float, float]) – Normal of the plane

• nx (int) – Number of grid points in x direction

• ny (int) – Number of grid points in y direction

Returns:

grid – Grid points on the plane

Return type:

np.ndarray, shape (ny, nx, 3)

genesis.utils.geom.generate_ring_points_on_sphere(radius: float, cap_axis: tuple[float, float, float], n_rings: int, arc_spacing: float, return_normals: bool = False) → ndarray | tuple[numpy.ndarray, numpy.ndarray]

Build n_rings concentric latitude rings on the upper spherical cap (pole at cap_axis).

Ring index 0 is the pole; ring n_rings - 1 is the equatorial plane of the cap. The number of samples on each ring is chosen from the ring circumference and arc_spacing.

Parameters:

• radius (float) – Radius of points on the sphere, used to determine the number of points on each ring.

• cap_axis ((float, float, float)) – Unit-ish axis from sphere center toward the dome pole (probes lie on the cap around this axis).

• n_rings (int) – Number of latitude rings, including the pole as a degenerate ring.

• arc_spacing (float) – Target arc length between neighboring probes along each ring.

• return_normals (bool) – Whether to return the normal vectors of the points.

Returns:

• points (np.ndarray, shape (N, 3)) – Points on the sphere surface.

• normals (np.ndarray, shape (N, 3), optional) – Normal vectors of the points. Only returned if return_normals is True.

class genesis.utils.geom.SpatialHasher(cell_size, grid_res, n_slots=None)

compute_reordered_idx(n, pos, active, reordered_idx)

Reordered element idx based on the given positions and active flags.

Parameters:

• n (int) – The number of elements in the positions and active arrays.

• pos – The array of positions.

• active – The array of active flags.

• reordered_idx – The array to store the computed reordered indices.

Returns:

None

for_all_neighbors(i_p, pos, task_range, ret: <quadrants.types.annotations.Template object at 0x730bd7cfc1a0>, task: <quadrants.types.annotations.Template object at 0x730bd8023a10>, i_b)

Iterates over all neighbors of a given position and performs a task on each neighbor. Elements are considered neighbors if they are within task_range.

Parameters:

• i_p (int) – Index of the querying particle.

• pos – Template for the positions of all particles.

• task – Template for the task to be performed on each neighbor of the querying particle.

• task_range – Range within which the task should be performed.

• ret – Template for the return value of the task.

Returns:

None

See also

• Conventions: coordinate frame, rotation, and quaternion conventions.

• Tensor utilities: converting between NumPy, PyTorch, and Genesis tensors.