GSEGUtils.base_arrays

See BaseArrays for background motivation.

Pydantic-validated numpy-array base classes.

Provides BaseArray and its subclasses (NumericMixins, FixedLengthArray, BaseVector, HomogeneousArray, ArrayNx2, ArrayNx3). Each class behaves like a NumPy array via the __array_interface__ protocol while gaining Pydantic-level field validation, dataclass-style declarations, and standard arithmetic / comparison dunders.

class GSEGUtils.base_arrays.BaseArray

Bases: ABC, BaseModel

Abstract Pydantic-validated wrapper around a NumPy array.

Subclasses inherit the strict validation config and the __array_interface__ proxy. Concrete subclasses constrain arr to a more specific shape / dtype via numpydantic.NDArray annotations and (optionally) override _coerce_array() to add extra coercion.

Subclassable array supporting all shapes and numeric/boolean dtypes.

Parameters:

arr (ArrayT) – Input array data

arr: ArrayT

Contains the raw numpy ndarray data

property T: Self

Return a transposed view of the array.

Return type:

Self

property shape: tuple[int, ...]

Return the shape of the array.

Return type:

tuple[int, …]

property dtype: dtype

Return the dtype of the array.

Return type:

dtype

property ndim: int

Return the number of dimensions in the array.

Return type:

int

property base: bool'>)] | None

Return the base array if this array is a view, otherwise None.

Return type:

ArrayT | None

property size: int

Return the number of elements in the array.

Return type:

int

view(dtype=None, _type=None)

Return a view of the underlying array.

Parameters:

  • dtype (numpy.dtype, optional) – Target dtype for the view; defaults to the current dtype.

  • _type (type, optional) – Sub-type of numpy.ndarray to construct; defaults to the current array type.

Return type:

ArrayT

min(**kwargs)

Return self.arr.min(**kwargs).

See numpy.min() for the supported keyword arguments.

Parameters:

**kwargs (dict[str, Any]) – Forwarded to numpy.ndarray.min().

Return type:

Any

max(**kwargs)

Return self.arr.max(**kwargs).

See numpy.max() for the supported keyword arguments.

Parameters:

**kwargs (dict[str, Any]) – Forwarded to numpy.ndarray.max().

Return type:

Any

copy(array=None, *, deep=True, update=None, **kwargs)

Return a copy of this object.

Supports deep / shallow copies and per-field overrides via update.

Parameters:

  • array (ArrayT | Self | None, optional) – If set, directly passed as the arr attribute in the new instance.

  • deep (bool, optional) – Whether to deep-copy non-arr fields. Default True.

  • update (dict[str, Any], optional) – Per-field overrides applied to the new instance.

  • **kwargs (dict[str, Any]) – Reserved for subclass overrides.

  • self (Self)

Return type:

Self

class GSEGUtils.base_arrays.NumericMixins

Bases: BaseArray

Adds Python arithmetic / in-place / logical dunders that delegate to self.arr.

Binary operators return a fresh wrapper of the same type via BaseArray.copy(); in-place operators mutate self.arr and return self.

Initialize a subclassable numeric/logical array wrapper.

Parameters:

arr (ArrayT) – Input array data.

class GSEGUtils.base_arrays.FixedLengthArray

Bases: NumericMixins

Row-oriented array wrapper with sample / reduce / extract helpers.

Suitable bases for per-row-typed data such as 3D coordinate sets, RGB triplets, or generic vectors-of-vectors.

Initialize a row-indexable array wrapper.

Parameters:

arr (ArrayT) – Input array data.

create_mask(selection)

Convert a NumPy index into a boolean per-row mask.

Parameters:

selection (IndexLike) – A slice, integer, integer array, or boolean array.

Returns:

Boolean mask of length len(self).

Return type:

Vector_Bool_T

Raises:

ValueError – If a boolean mask is provided with the wrong length.

sample(index)

Return a fresh wrapper containing only the rows selected by index.

Parameters:

index (IndexLike) – Anything accepted by create_mask().

Returns:

A deep copy holding only the selected rows.

Return type:

Self

reduce(index)

Mutate self.arr to keep only the rows selected by index.

Parameters:

index (IndexLike) – Anything accepted by create_mask().

Return type:

None

extract(index)

Split rows: return the selected rows and reduce self to the rest.

Parameters:

index (IndexLike) – Anything accepted by create_mask().

Returns:

A new wrapper holding the selected rows. self is mutated in-place to keep only the un-selected rows.

Return type:

Self

class GSEGUtils.base_arrays.BaseVector

Bases: FixedLengthArray

1-D variant of FixedLengthArray with a vector-shape contract on arr.

Initialize a shape-validated 1-D array wrapper.

Parameters:

arr (VectorT) – Input array data.

arr: VectorT

Contains the raw numpy ndarray data

class GSEGUtils.base_arrays.HomogeneousArray

Bases: FixedLengthArray

Row-array wrapper that exposes a homogeneous-coordinate view via H.

Initialize a homogeneous-coordinate-aware row array.

Parameters:

arr (ArrayT) – Input array data.

property H: bool'>)]

Return the homogeneous-coordinate form of self.arr.

Returns:

self.arr with an extra all-ones column appended on the right.

Return type:

ArrayT

class GSEGUtils.base_arrays.ArrayNx2

Bases: HomogeneousArray

Shape-validated Nx2 array.

Parameters:

arr (Array_Nx2_T) – Input array data.

Initialize an Nx2 shape-validated array.

arr: Array_Nx2_T

Contains the raw numpy ndarray data

class GSEGUtils.base_arrays.ArrayNx3

Bases: HomogeneousArray

Shape-validated Nx3 array.

Parameters:

arr (Array_Nx3_Float_T) – Input array data.

Initialize an Nx3 shape-validated array.

arr: Array_Nx3_Float_T

Contains the raw numpy ndarray data