GSEGUtils.util

Angle-conversion helpers and fast-path NumPy utilities.

Provides AngleUnit (rad / deg / gon enum), convert_angles() for pair-wise unit conversion, the underscore-prefixed in-place conversion aliases (scheduled for promotion to public names in Plan 01-04), and unique_rows_fast() (a faster alternative to numpy.unique(..., axis=0) for integer row de-duplication).

class GSEGUtils.util.AngleUnit

Bases: StrEnum

Enumerator for angular units.

  • AngleUnit.RAD = ‘rad’

  • AngleUnit.DEGREE = ‘deg’

  • AngleUnit.GON = ‘gon’

RAD = 'rad'
DEGREE = 'deg'
GON = 'gon'
static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

__new__(value)
GSEGUtils.util.convert_angles(values, source_unit, target_unit, out=None)

Convert an array of angles from one unit to another.

Parameters:

  • values (Array_Float_T) – Array of angles to convert.

  • source_unit (AngleUnit) – Unit of the input angles

  • target_unit (AngleUnit) – Unit to convert the angles to.

  • out (Optional[Array_Float_T], default=None) – Optional output array to store the results. If provided, it must be the same shape as values.

Return type:

Array_Float_T

Notes

  • If source_unit and target_unit are the same, the function returns a copy of the input values unless out is provided, in which case it writes the result to out.

  • Supported conversions: - Radians ↔ Degrees - Radians ↔ Gradians - Degrees ↔ Gradians

Examples

Convert an array of angles from degrees to radians

>>> import numpy as np
>>> from pchandler.util import convert_angles, AngleUnit
>>> angles_deg = np.array([0, 90, 180, 360])
>>> convert_angles(angles_deg, AngleUnit.DEGREE, AngleUnit.RAD)
array([0.        , 1.57079633, 3.14159265, 6.28318531])

Convert angles from radians to gradians

>>> angles_rad = np.array([0, np.pi/2, np.pi, 2*np.pi])
>>> convert_angles(angles_rad, AngleUnit.RAD, AngleUnit.GON)
array([ 0., 100., 200., 400.])
GSEGUtils.util.rad2deg(values, out=None)

Convert radians to degrees.

Parameters:

  • values (Array_Float_T or float) – Input angle(s) in radians.

  • out (Array_Float_T, optional) – Output array for in-place writes. Default = None.

Returns:

Converted angle(s) in degrees, or None when out is provided.

Return type:

Array_Float_T, float, or None

GSEGUtils.util.rad2gon(values, out=None)

Convert radians to gradians (gon).

Parameters:

  • values (Array_Float_T or float) – Input angle(s) in radians.

  • out (Array_Float_T, optional) – Output array for in-place writes. Default = None.

Returns:

Converted angle(s) in gradians, or None when out is provided.

Return type:

Array_Float_T, float, or None

GSEGUtils.util.deg2rad(values, out=None)

Convert degrees to radians.

Parameters:

  • values (Array_Float_T or float) – Input angle(s) in degrees.

  • out (Array_Float_T, optional) – Output array for in-place writes. Default = None.

Returns:

Converted angle(s) in radians, or None when out is provided.

Return type:

Array_Float_T, float, or None

GSEGUtils.util.deg2gon(values, out=None)

Convert degrees to gradians (gon).

Parameters:

  • values (Array_Float_T or float) – Input angle(s) in degrees.

  • out (Array_Float_T, optional) – Output array for in-place writes. Default = None.

Returns:

Converted angle(s) in gradians, or None when out is provided.

Return type:

Array_Float_T, float, or None

GSEGUtils.util.gon2rad(values, out=None)

Convert gradians (gon) to radians.

Parameters:

  • values (Array_Float_T or float) – Input angle(s) in gradians.

  • out (Array_Float_T, optional) – Output array for in-place writes. Default = None.

Returns:

Converted angle(s) in radians, or None when out is provided.

Return type:

Array_Float_T, float, or None

GSEGUtils.util.gon2deg(values, out=None)

Convert gradians (gon) to degrees.

Parameters:

  • values (Array_Float_T or float) – Input angle(s) in gradians.

  • out (Array_Float_T, optional) – Output array for in-place writes. Default = None.

Returns:

Converted angle(s) in degrees, or None when out is provided.

Return type:

Array_Float_T, float, or None

GSEGUtils.util.unique_rows_fast(bin_idx)

Determine unique rows in a 2-D integer array.

Returns (unique_rows, inverse_indices) exactly like numpy.unique() with axis=0, return_inverse=True but ~5–10× faster for large N.

Parameters:

bin_idx (Array_Int32_T)

Returns:

  • unique_rows (ArrayT,)

  • inverse_indices (Array_Int32_T)

Return type:

tuple[NDArray[Any, ((<class ‘numpy.int8’>, <class ‘numpy.int16’>, <class ‘numpy.int32’>, <class ‘numpy.int64’>, <class ‘numpy.int16’>, <class ‘numpy.uint8’>, <class ‘numpy.uint16’>, <class ‘numpy.uint32’>, <class ‘numpy.uint64’>, <class ‘numpy.uint16’>), (<class ‘numpy.float16’>, <class ‘numpy.float32’>, <class ‘numpy.float64’>, <class ‘numpy.float32’>, <class ‘numpy.float64’>), <class ‘numpy.bool’>)], NDArray[Any, int32]]