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).
- static convert(value)[source]#
Attempt conversion of a value to an
AzimuthConvention
instance. The conversion protocol is as follows:If
value
is a string, it is converted to upper case and passed to the indexing operator ofAzimuthConvention
.If
value
is anAzimuthConvention
instance, it is returned without change.Otherwise, the method raises an exception.
- Parameters:
value – Value to attempt conversion of.
- Returns:
Converted value
- Raises:
TypeError – If no conversion protocol exists for
value
.
- 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, normalize=True)[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
.normalize (
bool
, optional, default:True
) – IfTrue
, normalize azimuth values within the [0, 2π[ interval.
- Returns:
quantity
– A sequence of 2-vectors containing zenith and azimuth angles, where zenith = 0 corresponds to +z direction (shape (N, 2)).
- eradiate.frame.normalize_azimuth(angles, inplace=False)[source]#
Normalize azimuth values to the [0, 2π[ interval.
- Parameters:
angles (array-like) – A sequence of azimuth values [rad].
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 normalized to the [0, 2π[ interval [rad].
Warning
This function does not apply unit conversion automatically: angle values must be supplied in radians and are returned as plain Numpy arrays.
- eradiate.frame.spherical_to_cartesian(r, theta, phi, origin=(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
, normalize 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.