pchandler.scalar_fields

Public API for ScalarField and ScalarFieldManager classes.

class pchandler.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.ScalarFieldTriplet

Bases: ArrayNx3, AbstractScalarField

Scalar field triplet ((N, 3)) used as the base for RGB and Normal fields.

Parameters:

arr (Array_Nx3_T) – Underlying (N, 3) array.

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

Initialise a ScalarFieldTriplet from an (N, 3) array.

classmethod initialize(size, value=None, name='', origin_dtype=None)

Build a triplet of length size, optionally pre-filled with value.

Parameters:

  • size (int) – Number of rows to allocate.

  • value (Array_Nx3_Uint8_T, optional) – Pre-existing values to seed the triplet with; zeros if omitted.

  • name (str, optional) – Field name; default is empty.

  • origin_dtype (SfOrigDtT, optional) – Original DtypeState to attach to the resulting field — preserved across ScalarFieldManager._set_rgb() per-channel sets so that round-trips through PLY / LAS write the field back in its source dtype (DEBT-04).

class pchandler.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.

__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])

as_normalised_float32()

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

Return type:

Array_Nx3_Float32_T

property b: GSEGUtils.base_types.Vector_Uint8_T

Return the blue 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 g: GSEGUtils.base_types.Vector_Uint8_T

Return the green 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 r: GSEGUtils.base_types.Vector_Uint8_T

Return the red component of the RGB values.

Return type:

Vector_Uint8_T

property red: GSEGUtils.base_types.Vector_Uint8_T

Return the red component of the RGB values.

Return type:

Vector_Uint8_T

arr: Array_Nx3_Uint8_T

Contains the raw numpy ndarray data

name: str
class pchandler.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.

__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])

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

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.

arr: Array_Nx3_Float32_T

Contains the raw numpy ndarray data

name: str
class pchandler.scalar_fields.ScalarFieldManager

Bases: object

Manages scalar fields associated with a point cloud.

Contains mechanisms for adding, changing and removing scalar fields as well as validating lengths with respect to a parent point cloud object.

Parameters:
__init__(fields=None, *, parent=None)

Initialise the scalar field manager.

Ensures all fields passed are converted to ScalarField (or the appropriate RGBFields / NormalFields) objects. If a parent point cloud is provided, it is stored as a weakref and scalar-field lengths will be validated against it.

Parameters:
add_field(sf_field)

Add a new scalar field to the manager (keyed by sf_field.name).

Parameters:

sf_field (SF_T) – Scalar field to add.

as_struct_array()

Return the scalar fields packed into a single numpy structured array.

create_field(name, data)

Create a scalar field from a name and an array, then add it to the manager.

Supports Array_Nx3_T for the creation of RGB or Normals fields.

Parameters:

  • name (str) – Name of the new field.

  • data (VectorT | Array_Nx3_T) – Field data.

extract(mask)

Return a new manager carrying the selected rows; also reduces self to the complement.

Parameters:

mask (IndexLike) – The mask corresponds to indexing the rows or points in the parent point cloud.

Returns:

New manager containing the rows selected by mask.

Return type:

ScalarFieldManager

property intensity: ScalarField | None

Get the intensity field, or None if not set.

Returns:

Intensity field, or None.

Return type:

ScalarField | None

items()

Return the scalar field names and values stored in the manager.

Return type:

ItemsView[str, SF_T]

keys()

Return the scalar field names stored in the manager.

Return type:

KeysView[str]

classmethod merge(scalar_field_managers)

Merge a list of scalar-field managers, keeping only the fields they all share.

Parameters:

scalar_field_managers (Iterable[ScalarFieldManager]) – Managers to merge.

Returns:

New manager containing every commonly-named scalar field concatenated along axis 0.

Return type:

ScalarFieldManager

Raises:

ValueError – If scalar_field_managers is empty.

property normals: NormalFields | None

Get the normals fields.

Return type:

NormalFields | None

property num_points: int

Return the number of points in the parent point cloud, or -1 if no parent is set.

Returns:

Parent point count, or -1.

Return type:

int

property parent: PointCloudData | None

Return the parent point cloud object.

Return type:

PointCloudData | None

reduce(mask)

Reduce every scalar field in place to the rows selected by mask.

Parameters:

mask (IndexLike) – The mask corresponds to indexing the rows or points in the parent point cloud.

property reflectance: ScalarField | None

Get the reflectance field.

Return type:

ScalarField | None

remove_field(field_name)

Remove a scalar field from the manager by name.

Parameters:

field_name (LowerStr) – Name of the field to remove.

property rgb: RGBFields | None

Get the RGB fields.

Return type:

RGBFields | None

sample(mask)

Sample the scalar fields based on a mask.

Parameters:

mask (IndexLike) – The mask corresponds to indexing the rows or points in the parent point cloud.

Return type:

ScalarFieldManager

property shape: tuple[int, int]

Return the shape of the scalar field manager.

The shape will be in the form (num_points, num_fields).

Return type:

tuple[int, int]

validate_lengths()

Check that every scalar field’s length matches the parent point cloud’s point count.

Raises:

ValueError – If any scalar field’s length differs from the parent point count.

values()

Return the scalar field values stored in the manager.

Return type:

ValuesView[SF_T]

fields: dict[str, SF_T]

Modules

scalar_field_manager

ScalarFieldManager: container for the per-point scalar fields of a PointCloudData.

scalar_fields

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