get_cone_rotations#

get_cone_rotations(cone_angle, cone_sampling, axis_angle=None, axis_sampling=None, reference=(0, 0, 1), n_symmetry=None, **kwargs)[source]#

Generate rotations describing the possible placements of a vector in a cone.

Parameters:

cone_anglefloat: Half-angle of the cone in degrees. Defines the maximum angular deviation from the reference direction. Must be in range (0, 180].
cone_samplingfloat: Angular spacing between sample points on the cone surface in degrees.
axis_anglefloat, optional: Total rotation angle around the reference direction in degrees. Defaults to 360.0 for complete in-plane rotation.
axis_samplingfloat, optional: Angular spacing for in-plane rotations along the reference in degrees. If None, uses the value of cone_sampling.
referenceTuple[float], optional: The central direction of the cone as a 3D vector (x, y, z). Rotations will map this direction onto the cone surface. Defaults to z unit vector.
n_symmetryint, optional: Symmetry order of the object around the reference direction. The axis_angle is divided by this value. For example, use n_symmetry=2 for C2 symmetry. Default is 1 (no symmetry).

Returns:

NDArray: Array of rotation matrices with shape (n, 3, 3).

Notes

The total number of rotations is approximately:: N ≈ (2π(1 - cos(cone_angle)) / cone_sampling²) × (axis_angle / axis_sampling)

Examples

Sample orientations within 30° of the z-axis with full in-plane rotation:

>>> rotations = get_cone_rotations(
...     cone_angle=30.0,
...     cone_sampling=10.0,
...     reference=(0, 0, 1)
... )

Limited search with 2-fold symmetry around x-axis:

>>> rotations = get_cone_rotations(
...     cone_angle=45.0,
...     cone_sampling=15.0,
...     axis_angle=180.0,
...     reference=(1, 0, 0),
...     n_symmetry=2
... )