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 of AzimuthConvention.

  • If value is an AzimuthConvention 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:
  • plane (float) – Plane cut orientation [rad].

  • theta (ndarray) – List of zenith angle values with (N,) shape [rad].

  • phi (ndarray) – List of azimuth angle values with (N,) shape [rad].

  • raise_exc (bool, optional) – If True, raise if not all directions are snapped to the specified hemisphere plane cut.

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 or str, optional, default: AzimuthConvention.EAST_RIGHT) – Source azimuth angle convention. If a string is passed, it will be converted to a AzimuthConvention.

  • flip (bool, optional, default: False) – If True, 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 or str, optional, default: AzimuthConvention.EAST_RIGHT) – Source azimuth angle convention. If a string is passed, it will be converted to a AzimuthConvention.

  • flip (bool) – If True, 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 or str, optional, default: AzimuthConvention.EAST_RIGHT) – Target azimuth angle convention. If a string is passed, it will be converted to a AzimuthConvention.

  • normalize (bool, optional, default: True) – If True, 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) – If True, 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 or str, optional, default: AzimuthConvention.EAST_RIGHT) – Source azimuth angle convention. If a string is passed, it will be converted to a AzimuthConvention.

  • to_convention (AzimuthConvention or str, optional, default: AzimuthConvention.EAST_RIGHT) – Target azimuth angle convention. If a string is passed, it will be converted to a AzimuthConvention.

  • normalize (bool, optional, default: True) – If True, normalize returned angle values within the [0, 2π[ interval.

  • inplace (bool, optional, default: False) – If True, 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.