eradiate.frame
eradiate.frame
#
Frame and angle manipulation utilities.
- class eradiate.frame.AzimuthConvention(value)[source]#
An enumeration of azimuth convention names associated with the corresponding (origin offset, orientation) pair with respect to the East right convention. The origin offset is expressed in radian and the orientation is the angle value multiplier (±1).
- classmethod register(name, value)[source]#
Register a new angular convention.
- Parameters
name (
str
) – Name of the registered convention. Should be uppercase, without whitespace.value (
tuple
) – An (offset, orientation) 2-tuple. The offset is the angular offset of the registered convention in radian. The offset is an integer equal to 1 (right-hand/counter-clockwise convention) or -1 (left-hand/clockwise convention).
- EAST_LEFT = (0.0, -1)#
East left
- EAST_RIGHT = (0.0, 1)#
East right
- NORTH_LEFT = (1.5707963267948966, -1)#
North left
- NORTH_RIGHT = (1.5707963267948966, 1)#
North right
- SOUTH_LEFT = (4.71238898038469, -1)#
South left
- SOUTH_RIGHT = (4.71238898038469, 1)#
South right
- WEST_LEFT = (3.141592653589793, -1)#
West left
- WEST_RIGHT = (3.141592653589793, 1)#
West right
- eradiate.frame.angles_in_hplane(plane, theta, phi, raise_exc=True)[source]#
Check that a set of (zenith, azimuth) pairs belong to a given hemisphere plane cut.
- Parameters
- Returns
in_plane_positive
,in_plane_negative
– Masks indicating indexes of directions contained in the positive (resp. negative) half-plane.- Raises
ValueError – If not all directions are snapped to the specified hemisphere plane cut.
- eradiate.frame.angles_to_direction(angles, azimuth_convention=AzimuthConvention.EAST_RIGHT, flip=False)[source]#
Convert a zenith and azimuth angle pair to a direction unit vector.
- Parameters
angles (array-like) – A sequence of (zenith, azimuth) pairs, where zenith = 0 corresponds to +z direction [rad].
azimuth_convention (
AzimuthConvention
orstr
, optional, default:AzimuthConvention.EAST_RIGHT
) – Source azimuth angle convention. If a string is passed, it will be converted to aAzimuthConvention
.flip (
bool
, optional, default:False
) – IfTrue
, flip returned directions (useful in practice to get direction vectors pointing towards the local frame origin).
- Returns
ndarray
– Directions corresponding to the angular parameters [unitless].
- eradiate.frame.cos_angle_to_direction(cos_theta, phi, azimuth_convention=AzimuthConvention.EAST_RIGHT, flip=False)[source]#
Convert a zenith cosine and azimuth angle pair to a direction.
- Parameters
cos_theta (array-like) – Zenith angle cosine [dimensionless]. Convention: 1 corresponds to zenith, -1 corresponds to nadir.
phi (array-like) – Azimuth angle [radian]. Convention: \(2 \pi\) corresponds to the X axis.
azimuth_convention (
AzimuthConvention
orstr
, optional, default:AzimuthConvention.EAST_RIGHT
) – Source azimuth angle convention. If a string is passed, it will be converted to aAzimuthConvention
.flip (
bool
) – IfTrue
, flip the returned direction (points towards the nadir with cos_theta equal to 1).
- Returns
ndarray
– Directions corresponding to the angular parameters [unitless].
- eradiate.frame.direction_to_angles(v, azimuth_convention=AzimuthConvention.EAST_RIGHT)[source]#
Convert a cartesian unit vector to a zenith-azimuth pair.
- Parameters
v (array-like) – A sequence of 3-vectors (shape (N, 3)) [unitless].
azimuth_convention (
AzimuthConvention
orstr
, optional, default:AzimuthConvention.EAST_RIGHT
) – Target azimuth angle convention. If a string is passed, it will be converted to aAzimuthConvention
.
- Returns
quantity
– A sequence of 2-vectors containing zenith and azimuth angles, where zenith = 0 corresponds to +z direction (shape (N, 2)).
- eradiate.frame.spherical_to_cartesian(r, theta, phi, origin=array([0., 0., 0.]))[source]#
Convert spherical coordinates to cartesian coordinates
- Parameters
r (
float
) – Radial distance coordinate.theta (
float
) – Zenith angle coordinate [radian]. Convention: 0 corresponds to zenith, \(\pi\) corresponds to nadir.phi (
float
) – Azimuth angle coordinate [radian]. Convention: \(2 \pi\) corresponds to the X axis.origin (array-like) – Shifts the center point of the coordinate system.
- Returns
ndarray
– Cartesian coordinates x, y, z as a (3,) array.
- eradiate.frame.transform_azimuth(angles, from_convention=AzimuthConvention.EAST_RIGHT, to_convention=AzimuthConvention.EAST_RIGHT, normalize=True, inplace=False)[source]#
Convert azimuth values expressed with a given convention to another. The East right convention is used as a pivot.
- Parameters
angles (array-like) – A sequence of azimuth values [rad].
from_convention (
AzimuthConvention
orstr
, optional, default:AzimuthConvention.EAST_RIGHT
) – Source azimuth angle convention. If a string is passed, it will be converted to aAzimuthConvention
.to_convention (
AzimuthConvention
orstr
, optional, default:AzimuthConvention.EAST_RIGHT
) – Target azimuth angle convention. If a string is passed, it will be converted to aAzimuthConvention
.normalize (
bool
, optional, default:True
) – IfTrue
, normalise returned angle values within the [0, 2π] interval.inplace (
bool
, optional, default:False
) – IfTrue
, perform the conversion in-place. This will mutate the angles array; otherwise, this function operates on a copy.
- Returns
ndarray
– Azimuth angle values converted to the East right convention [rad].
Warning
This function does not apply unit conversion automatically: angle values must be supplied in radians and are returned as plain Numpy arrays.