GSEGUtils.validators

Input-validation helpers for spherical / Cartesian arrays and unsigned-integer normalization.

Provides validators for spherical-coordinate arrays, axis/range checks for angle columns, transposition helpers for Nx2 / Nx3 arrays, slice-to-integer conversion, and normalize_uint* saturation routines.

GSEGUtils.validators.validate_spherical_angles(array)

Check spherical coordinates are valid.

Acceptable ranges:: Radius: [0, +∞] Hz Angle: [-π, +π] V Angle: [0, +π]

Raises errors if not valid. No conversion is done.

Parameters:: array (Array_Nx3_Float_T) – Nx3 array with rhv column order (Radius, Horizontal Angle, Vertical Angle)
Return type:: Array_Nx3_Float_T
Raises:: TypeError – Non numpy array

GSEGUtils.validators.validate_radius(array)

Check radii are non-negative.

Parameters:

array (Array_Float_T) – Input array is independent of the distance unit

Return type:

Array_Float_T

Raises:

TypeError – Non numpy array
ValueError – Negative values

GSEGUtils.validators.validate_azimuth_angles(array)

Check that azimuth angles lie in [0, 2π].

Parameters:

array (Array_Float_T) – Array of angles in radians

Return type:

Array_Float_T

Raises:

TypeError – Non numpy array
ValueError – Values outside range [0, 2π]

GSEGUtils.validators.validate_horizontal_angles(array)

Check that horizontal angles lie in [-π, +π].

Parameters:

array (Array_Float_T) – Array of angles in radians

Return type:

Array_Float_T

Raises:

TypeError – Non numpy array
ValueError – Values outside range [-π, +π]

GSEGUtils.validators.validate_zenith_angles(array)

Check that zenith angles lie in [0, +π].

Parameters:

array (Array_Float_T) – Array of angles in radians

Return type:

Array_Float_T

Raises:

TypeError – Non numpy array
ValueError – Values outside range [0, +π]

GSEGUtils.validators.validate_inclination_angles(array)

Check that inclination angles lie in [-π/2, +π/2].

Parameters:

array (Array_Float_T) – Array of angles in radians

Return type:

Array_Float_T

Raises:

TypeError – Non numpy array
ValueError – Values outside range [-π/2, +π/2]

GSEGUtils.validators.coerce_wrapped_azimuth_angles(array)

Coerces azimuth angles to be within the range [0, 2π).

Parameters:: array (Array_Float_T) – Array of azimuth angles in radians
Return type:: Array_Float_T

GSEGUtils.validators.coerce_wrapped_horizontal_angles(array)

Coerce horizontal angles to the half-open range [-π, π).

Parameters:: array (Array_Float_T) – Array of horizontal angles in radians
Return type:: Array_Float_T

GSEGUtils.validators.validate_transposed_2d_array(array, n)

Ensure an array is of MxN shape or NxM shape and transpose if necessary.

Parameters:

array (ArrayT) – Input array, either 1D or 2D.
n (int) – The expected number of columns for the 2D array.

Return type:

ArrayT

Raises:

ValueError – Unsupported shape

GSEGUtils.validators.convert_slice_to_integer_range(selection, length)

Convert a slice object to an array of integer indices.

Parameters:

selection (slice) – Slice object containing start, stop, and step
length (int) – The length of the target array associated array or sequence

Return type:

Array_Integer_T

GSEGUtils.validators.validate_in_range(value, target_min, target_max)

Validate that all values in value lie within [target_min, target_max].

Contract independent of any specific caller library. Inclusive bounds on both sides; the combined out-of-range case (both min < target_min AND max > target_max) raises a single combined-message ValueError distinct from the single-side branches. This is intentional, not a redundant branch.

Parameters:

value (ArrayT) – Input array. Coerced via np.asarray before reduction.
target_min (float) – Inclusive lower bound.
target_max (float) – Inclusive upper bound.

Raises:

ValueError – If any value lies outside [target_min, target_max]. Three branches: single-side-low, single-side-high, or combined dual-out-of-range.

Return type:

None

GSEGUtils.validators.normalize_min_max(array, lower, upper, target_dtype, v_min=None, v_max=None)

Normalize and scale the values in a numpy array to a specified range using min-max scaling.

The input array is initially normalized using v_min, v_max where array.min() and array.max() are the default if not set.

This is then scaled to the target range bounds of [lower, upper] and converted to the target data type.

Parameters:

array (ArrayT) – Input array
lower (float or int or np.number) – Target lower bound after normalization
upper (float or int or np.number) – Target upper bound after normalization
target_dtype (npt.DtypeLike) – Output data type
v_min (float or int, optional) – Minima value used for normalization. Defaults to array.min() if not provided.
v_max (float or int, optional) – Maxima value used for normalization. Defaults to array.max() if not provided.

Return type:

ArrayT

GSEGUtils.validators.linear_map_dtype(array, target_dtype, *, source_range=(0.0, 1.0))

Linearly map the array values to the target dtype.

This function maps the input array values based on the current datatype’s minimum and maximum supported values to those of the target datatype.

Float-input path: clip to source_range then linearly map to the target dtype’s numpy.iinfo() range (clip-and-saturate, Phase 4 D-12 / D-16). NaN / +Inf / -Inf input raises ValueError (D-14). Integer-input path: passes through normalize_min_max against the source dtype’s numpy.iinfo(); source_range is silently ignored when array.dtype.kind in ('u', 'i') (D-15).

Examples

np.int8 to np.uint16

>>> input = np.array([-50, 0, 127], dtype=np.int8)
>>> linear_map_dtype(input, np.uint16)
array([20046, 32896, 65535], dtype=uint16)

Parameters:

array (ArrayT) – Input array
target_dtype (npt.DtypeLike) – Target dtype (64-bit types not supported)
source_range (tuple[float, float], keyword-only, default (0.0, 1.0)) – Inclusive range of the float input that maps onto the target dtype’s full iinfo extent. Values outside the range are clipped before scaling (D-12). Silently ignored for integer input (D-15).

Return type:

ArrayT

Raises:

ValueError – Dtype is 64-bit (e.g., np.float64, np.int64, np.uint64); or the float input contains NaN / +Inf / -Inf (D-14); or source_range bounds are non-finite or not strictly increasing.
TypeError – Non-floating or integer object type passed

Notes

Phase 4 D-12 / D-16: the clip-and-saturate policy replaces the prior pass-through behaviour for unbounded floats. Callers that relied on the default [0, 1] source range continue to work unchanged; callers that fed signed-float input [-1, 1] must pass source_range=(-1.0, 1.0) explicitly.

GSEGUtils.validators.normalize_self(array)

Normalize an input array to the limits expected by its own dtype.

For floating point values, this is [0, 1] and for integer values, it is the min and max defined by np.iinfo.

Parameters:: array (ArrayT) – The input array to be normalized
Return type:: ArrayT

GSEGUtils.validators.normalize_uint8(array, *, source_range=(0.0, 1.0))

Normalize array into the uint8 range.

Float-input path: clip to source_range then linearly scale to [0, 255] (clip-and-saturate, Phase 4 D-12). NaN / +Inf / -Inf raises ValueError (D-14). Integer-input path: source_range is silently ignored (D-15).

Parameters:

array (ArrayT) – Input array (float or integer dtype).
source_range (tuple[float, float], keyword-only, default (0.0, 1.0)) – Inclusive interval of the float input that maps onto [0, 255]. See _normalize_base() for full semantics.

Return type:

Array_Uint8_T

GSEGUtils.validators.normalize_uint16(array, *, source_range=(0.0, 1.0))

Normalize array into the uint16 range.

Float-input path: clip to source_range then linearly scale to [0, 65535] (clip-and-saturate, Phase 4 D-12). NaN / +Inf / -Inf raises ValueError (D-14). Integer-input path: source_range is silently ignored (D-15).

Parameters:

array (ArrayT) – Input array (float or integer dtype).
source_range (tuple[float, float], keyword-only, default (0.0, 1.0)) – Inclusive interval of the float input that maps onto [0, 65535]. See _normalize_base() for full semantics.

Return type:

Array_Uint16_T

GSEGUtils.validators.normalize_int8(array)

Normalize array into the int8 range.

Parameters:: array (ArrayT)
Return type:: Array_Int8_T

GSEGUtils.validators.normalize_int16(array)

Normalize array into the int16 range.

Parameters:: array (ArrayT)
Return type:: Array_Int16_T

GSEGUtils.validators.normalize_int32(array)

Normalize array into the int32 range.

Parameters:: array (ArrayT)
Return type:: Array_Int32_T

GSEGUtils.validators.normalize_int64(array)

Normalize array into the int64 range.

Parameters:: array (ArrayT)
Return type:: Array_Int64_T