pchandler.scalar_fields.scalar_fields

Per-point typed scalar-field classes (RGB, normals, intensity, segmentation, generic).

Classes

`AbstractScalarField`	Abstract scalar field with validation and conversion back to the original dtype.
`DtypeState`	Contains the original dtype and limits of an array used to create a ScalarField array.
`NormalFields`	Normal-vector field represented by a scalar field triplet of float32 unit vectors.
`NormalisedInt16ScalarField`	Scalar field whose values are normalised into `int16` at validation time.
`RGBFields`	RGB / Color field, represented by a scalar field triplet of uint8 values.
`ScalarField`	Generic scalar field backed by a 1D vector.
`ScalarFieldBoolean`	Scalar field constrained to boolean arrays.
`ScalarFieldFloat32`	Scalar field constrained to `float32` dtype.
`ScalarFieldTriplet`	Scalar field triplet (`(N, 3)`) used as the base for RGB and Normal fields.
`ScalarFieldUint8`	Scalar field constrained to `uint8` dtype.
`SegmentationMap`	Segmentation-map scalar field (uint8 or uint16) keyed by point-cloud segment.

class pchandler.scalar_fields.scalar_fields.ScalarField

Bases: BaseVector, AbstractScalarField

Generic scalar field backed by a 1D vector.

__init__(arr, name=None, origin_dtype=None)

Initialise a ScalarField from a 1D vector.

Parameters:

arr (VectorT | Array_Nx3_T | Self) – Underlying 1D values.
name (SfNameT, optional) – Field name; inferred from arr or class default if omitted.
origin_dtype (SfOrigDtT, optional) – Original DtypeState; auto-generated if omitted.

class pchandler.scalar_fields.scalar_fields.RGBFields

Bases: ScalarFieldTriplet

RGB / Color field, represented by a scalar field triplet of uint8 values.

Parameters:: arr (Array_Nx3_Uint8_T) – Underlying (N, 3) uint8 array.

arr: Array_Nx3_Uint8_T: Contains the raw numpy ndarray data

name: str

__init__(arr, **kwargs)

Initialise an RGB field.

Will convert any floating point values to uint8.

Parameters:

arr (Array_Nx3_Uint8_T | Array_Nx3_Float_T | Self)
kwargs (dict[str, Any])

property red: GSEGUtils.base_types.Vector_Uint8_T

Return the red component of the RGB values.

Return type:: Vector_Uint8_T

property r: GSEGUtils.base_types.Vector_Uint8_T

Return the red component of the RGB values.

Return type:: Vector_Uint8_T

property green: GSEGUtils.base_types.Vector_Uint8_T

Return the green component of the RGB values.

Return type:: Vector_Uint8_T

property g: GSEGUtils.base_types.Vector_Uint8_T

Return the green component of the RGB values.

Return type:: Vector_Uint8_T

property blue: GSEGUtils.base_types.Vector_Uint8_T

Return the blue component of the RGB values.

Return type:: Vector_Uint8_T

property b: GSEGUtils.base_types.Vector_Uint8_T

Return the blue component of the RGB values.

Return type:: Vector_Uint8_T

as_normalised_float32()

Return the RGB values as a normalized float32 array in the range of [0,1].

Return type:: Array_Nx3_Float32_T

origin_dtype: DtypeState

class pchandler.scalar_fields.scalar_fields.NormalFields

Bases: ScalarFieldTriplet

Normal-vector field represented by a scalar field triplet of float32 unit vectors.

Parameters:: arr (Array_Nx3_Float32_T) – Underlying (N, 3) float32 array.

arr: Array_Nx3_Float32_T: Contains the raw numpy ndarray data

name: str

__init__(arr, **kwargs)

Initialize a normal vector field.

Values will be normalized to unit vectors and converted to float32.

Parameters:

arr (Array_Nx3_Float_T | Self)
kwargs (Unpack[_ScalarKwargT])

property nx: GSEGUtils.base_types.Vector_Float32_T: Return the X component of the normal vector.

property ny: GSEGUtils.base_types.Vector_Float32_T: Return the Y component of the normal vector.

property nz: GSEGUtils.base_types.Vector_Float32_T: Return the Z component of the normal vector.

classmethod initialize(length, value=None)

Build a NormalFields of length length, optionally seeded with value.

Parameters:

length (int) – Number of rows to allocate.
value (Array_Nx3_Float32_T, optional) – Existing values to initialise the array with (defaults to unit vectors along +Z).

Returns:

New normals field of the requested length.

Return type:

NormalFields

origin_dtype: DtypeState

class pchandler.scalar_fields.scalar_fields.SegmentationMap

Bases: ScalarField

Segmentation-map scalar field (uint8 or uint16) keyed by point-cloud segment.

Parameters:: arr (Vector_Uint8_T | Vector_Uint16_T) – Per-point segment index.

arr: Vector_Uint8_T | Vector_Uint16_T: Contains the raw numpy ndarray data

__init__(arr, **kwargs)

Initialise a SegmentationMap from a uint8/uint16 vector.

classmethod initialize(name, pt_cloud_sizes)

Initialize a segmentation map scalar field based on the number of points in each point cloud.

Parameters:

name (LowerStr)
pt_cloud_sizes (list[int])

Return type:

SegmentationMap

class pchandler.scalar_fields.scalar_fields.ScalarFieldUint8

Bases: ScalarField

Scalar field constrained to uint8 dtype.

arr: Vector_Uint8_T: Contains the raw numpy ndarray data

__init__(arr, **kwargs)

Initialise a ScalarFieldUint8 from a uint8 vector.

Parameters:

arr (Vector_Uint8_T | Self) – Underlying uint8 vector.
**kwargs (Unpack[_ScalarKwargT]) – Optional name and origin_dtype.

class pchandler.scalar_fields.scalar_fields.ScalarFieldBoolean

Bases: ScalarField

Scalar field constrained to boolean arrays.

arr: Vector_Bool_T: Contains the raw numpy ndarray data

__init__(arr, **kwargs)

Initialise a ScalarFieldBoolean from a boolean vector.

Parameters:

arr (Vector_Bool_T | Self) – Underlying boolean vector.
**kwargs (Unpack[_ScalarKwargT]) – Optional name and origin_dtype.

class pchandler.scalar_fields.scalar_fields.ScalarFieldFloat32

Bases: ScalarField

Scalar field constrained to float32 dtype.

arr: Vector_Float32_T: Contains the raw numpy ndarray data

__init__(arr, **kwargs)

Initialise a ScalarFieldFloat32 from a float32 vector.

Parameters:

arr (Vector_Float32_T | Self) – Underlying float32 vector.
**kwargs (Unpack[_ScalarKwargT]) – Optional name and origin_dtype.

class pchandler.scalar_fields.scalar_fields.NormalisedInt16ScalarField

Bases: ScalarField

Scalar field whose values are normalised into int16 at validation time.

arr: Annotated[Vector_Int16_T, BeforeValidator(normalize_int16)]: Contains the raw numpy ndarray data

__init__(arr, **kwargs)

Initialise a NormalisedInt16ScalarField from any numeric vector.

Parameters:

arr (VectorT | Self) – Underlying values (will be normalised to int16).
**kwargs (Unpack[_ScalarKwargT]) – Optional name and origin_dtype.

to_uint8()

Return a converted copy of the scalar field with the dtype set to uint8.

Returns:: New uint8 scalar field carrying the same name and origin dtype.
Return type:: ScalarFieldUint8

class pchandler.scalar_fields.scalar_fields.AbstractScalarField

Bases: FixedLengthArray

Abstract scalar field with validation and conversion back to the original dtype.

Parameters:

arr (VectorT | Array_Nx3_T) – Underlying array of values.
name (SfNameT) – Field name (lower-cased).
origin_dtype (SfOrigDtT) – Original DtypeState captured at construction.

name: LowerStr

origin_dtype: DtypeState

__init__(arr, name=None, origin_dtype=None)

Initialise a scalar field.

Parameters:

arr (VectorT | Array_Nx3_T | Self)
name (SfNameT, optional)
origin_dtype (SfOrigDtT, optional)

get_original_data()

Return the original data stored in the scalar field.

Performs the inverse normalization from the DtypeState stored with the scalar field.

Return type:: Array_Nx3_T | BaseVector

class pchandler.scalar_fields.scalar_fields.DtypeState

Bases: NamedTuple

Contains the original dtype and limits of an array used to create a ScalarField array.

Parameters:

dtype (np.dtype)
lower (npt.NDArray[np.number] | float | int)
upper (npt.NDArray[np.number] | float | int)

dtype: type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None: Alias for field number 0

lower: ndarray[tuple[Any, ...], dtype[number]] | float | int: Alias for field number 1

upper: ndarray[tuple[Any, ...], dtype[number]] | float | int: Alias for field number 2

classmethod generate(array)

Build a DtypeState from an array’s dtype and min/max range.

Parameters:: array (ArrayT | ArrayNx3 | BaseVector) – Source array.
Returns:: New state instance.
Return type:: DtypeState
Raises:: TypeError – If array does not expose a dtype attribute.

static validate(obj)

Ensure that the lower value is strictly less than the upper value.

Parameters:: obj (DtypeState) – State to validate; no-op if obj is None.
Raises:: ValueError – If obj.lower >= obj.upper.

static __new__(_cls, dtype, lower, upper)

Create new instance of DtypeState(dtype, lower, upper)