2.5. Directions

The Directions class provides helper functions for selecting directions to compute the ECT along.

class ect.directions.Sampling(*values)[source]

UNIFORM = 'uniform'

RANDOM = 'random'

CUSTOM = 'custom'

class ect.directions.Directions(num_dirs=360, sampling=Sampling.UNIFORM, dim=2, endpoint=False, seed=None)[source]

Manages direction vectors for ECT calculations. Supports uniform, random, or custom sampling of directions.

Examples:

# Uniform sampling in 2D (default)
dirs = Directions.uniform(num_dirs=8)

# Uniform sampling in 3D
dirs = Directions.uniform(num_dirs=10, dim=3)

# Random sampling in 2D
dirs = Directions.random(num_dirs=10, seed=42)

# Custom angles (2D only)
dirs = Directions.from_angles([0, np.pi/4, np.pi/2])

# Custom vectors in any dimension
dirs = Directions.from_vectors([(1,0,0), (0,1,0), (0,0,1)])

__init__(num_dirs=360, sampling=Sampling.UNIFORM, dim=2, endpoint=False, seed=None)[source]

Initialize a Directions instance for ECT calculations.

Parameters:

num_dirs (int) – Number of direction vectors to generate (default: 360).
sampling (Sampling) – Sampling strategy (UNIFORM, RANDOM, or CUSTOM).
dim (int) – Dimension of the space (default: 2).
endpoint (bool) – Whether to include the endpoint for 2D angles (default: False).
seed (Optional[int]) – Random seed for reproducibility (default: None).

Notes

For 2D, directions are represented as angles; for higher dimensions, as unit vectors.
Use factory methods uniform(), random(), from_angles(), or from_vectors() for convenience.

classmethod uniform(num_dirs=360, dim=2, endpoint=False, seed=None)[source]

Factory method for uniform sampling.

Parameters:

num_dirs – Number of direction vectors.
dim – Dimension of the space (default 2).
endpoint – Whether to include the endpoint (for 2D angles).
seed – Optional random seed.

classmethod random(num_dirs=360, dim=2, seed=None)[source]

Factory method for random sampling.

Parameters:

num_dirs – Number of direction vectors.
dim – Dimension of the space.
seed – optional random seed.

classmethod from_angles(angles)[source]

Create a Directions instance for custom angles in 2D.

Parameters:: angles (Sequence[float]) – List or array of angles (in radians) for each direction.
Returns:: Instance with direction angles set and corresponding unit vectors available via vectors.
Return type:: Directions

Notes

Only valid for 2D directions; for higher dimensions use from_vectors().
Angles are stored in thetas and unit vectors are computed as needed.

classmethod from_vectors(vectors)[source]

Create a Directions instance from custom direction vectors in any dimension.

Parameters:: vectors (Sequence[tuple]) – List or array of direction vectors (each must be nonzero).
Returns:: Instance with normalized direction vectors and associated angles (if 2D).
Return type:: Directions
Raises:: ValueError – If any vector has zero magnitude.

Notes

Vectors are normalized to unit length.
For 2D, angles are computed from the vectors and available via thetas.

property thetas

Get the angles (in radians) for 2D direction vectors.

Returns:: Array of angles corresponding to each direction vector (2D only).
Return type:: np.ndarray
Raises:: ValueError – If called for directions in dimension greater than 2.

Notes

For 2D, angles are computed from the direction vectors if not already set.
For higher dimensions, use vectors for direction data.

property vectors

Get the unit direction vectors for all directions.

Returns:: Array of shape (num_dirs, dim) containing unit vectors for each direction.
Return type:: np.ndarray
Raises:: ValueError – If vectors are not available for dimensions >2 and were not generated during initialization.

Notes

For 2D, vectors are computed from thetas if not already set.
For higher dimensions, vectors are generated during initialization or via from_vectors().