pchandler.geometry.coordinates

Cartesian coordinate classes with numerical-precision shift management.

Defines AbstractCoordinates and Abstract3dCoordinates base classes, CartesianCoordinates (the main user-facing 3D coordinate container), plus the rhv2xyz / xyz2rhv spherical/Cartesian conversion helpers.

Functions

`rhv2xyz`(spher[, scan_origin])	Convert spherical coordinates (RHV) to Cartesian coordinates (XYZ).
`xyz2rhv`(xyz[, scan_origin])	Convert Cartesian coordinates (XYZ) to spherical coordinates (RHV).

Classes

`Abstract2dCoordinates`	Abstract base for 2D coordinate classes exposing `row` and `col`.
`Abstract3dCoordinates`	Abstract coordinates with support for a transformation to custom coordinate system and a scan center parameter.
`Abstract3dKw`	Optional keyword arguments accepted by `Abstract3dCoordinates`.
`AbstractCoordinates`	Abstract base for all coordinate classes; carries a UUID4 identity.
`CartesianCoordinates`	Cartesian Coordinate class with support for numerical optimizations and helper access methods.
`CartesianKw`	Optional keyword arguments accepted by `CartesianCoordinates`.
`CartesianKwFull`	Full keyword surface for `CartesianCoordinates` (includes `arr`).

class pchandler.geometry.coordinates.CartesianCoordinates

Bases: Abstract3dCoordinates

Cartesian Coordinate class with support for numerical optimizations and helper access methods.

Parameters:

arr (Array_Nx3_T) – Raw coordinate data
unshifted_bbox (MinMaxPoints | None) – Bounding box of the original input coordinates (before optimization shift)
numerical_optimization_shift (OptimizedShift | None) – Optimization shift applied to the point cloud.
socs_origin (Vector_3_T | None) – Scan center coordinate in the current coordinate system.

arr: Array_Nx3_T: Contains the raw numpy ndarray data

unshifted_bbox: MinMaxPoints | None

numerical_optimization_shift: OptimizedShift | None

__init__(xyz: TypeAliasForwardRef('GSEGUtils.base_types.Array_Nx3_T') | Self, **kwargs: Unpack[CartesianKw])

__init__(**kwargs: Unpack[CartesianKwFull])

Build a CartesianCoordinates, auto-computing a numerical-precision shift.

On construction the object attempts to apply a numerical-precision shift so the coordinates fit in float32 without loss. The user can pass numerical_optimization_shift=None to force the coordinates to keep the input precision and original coordinate system.

Parameters:

xyz (Array_Nx3_T | Self, optional) – XYZ coordinates as an (N, 3) array, or another CartesianCoordinates instance to copy from. May also be supplied via the arr= keyword.
**kwargs – Optional fields: socs_origin, project_transformation, numerical_optimization_shift, unshifted_bbox, _shift_applied_by.

compute_unshifted_bbox(overwrite=False)

Compute the bounding box of the point cloud’s original (unshifted) coordinates.

Parameters:: overwrite (bool, default=False) – Recompute the bounding box even if one is already cached.

reduce(index)

Reduce the coordinates to the point set selected by index (in place).

Supports both numpy basic and advanced indexing.

Parameters:: index (IndexLike) – Index or boolean mask selecting the rows to keep.

sample(index)

Sample a copy of the coordinates using index.

Parameters:: index (IndexLike) – Index or boolean mask selecting the rows to keep.
Returns:: New CartesianCoordinates carrying the sampled rows.
Return type:: CartesianCoordinates

update_shift(delta_shift)

Apply delta_shift to the coordinates and adjust the dtype accordingly.

The dtype of the updated vectors is float32 when a numerical-optimization shift is registered, and float64 otherwise.

Parameters:: delta_shift (Vector_3_T) – The shift vector to be added.

model_dump(**kwargs)

Dump the model to a dict, preserving the private _shift_applied_by attribute.

Parameters:: **kwargs (Any) – Passed through to pydantic.BaseModel.model_dump().
Returns:: Model state including _shift_applied_by.
Return type:: dict[str, Any]

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

Produce a deep or shallow copy of the model.

Updates the model also if this parameter is parsed.

Parameters:

array (Array_Nx3_Float_T | Self) – A new object will be created with all other parameters and have it’s coordinates update with this array.
deep (bool) – Flag to indicate if a deep copy should be made.
update (dict[str, Any] | None) – Dictionary of parameters to update.
link_to_same_NOS (bool) – Flag if the object should be tied to the same optimal shift object. Thus attached to the same coordinate system.
kwargs (dict[str, Any])

Return type:

CartesianCoordinates

classmethod merge(*cart_coords, **kwargs)

Merge multiple cartesian coordinate sets into one.

Attempts will be made to automatically resolve the numerical shift applied to each point cloud, if applied.

Parameters:

cart_coords (CartesianCoordinates)
kwargs (dict[str, Any])

Return type:

CartesianCoordinates

Notes

Behaviour when input PCDs have mixed numerical_optimization_shift:

If the first PCD’s NOS passes check_addibility(combined_bbox), link the merged PCD to that NOS. (Most common; INFO log “Linking…”.)
Else if a fresh OptimizedShift() would be feasible for the combined bbox under the manager’s precision floor, mint one and link. INFO log “Creating new numerical optimization shift instance.”
Else, set numerical_optimization_shift = None on the merged PCD (degrade to float64 frame). INFO log “Unable to create new…”.

Phase 3 mint-new-UUID on cross-process unpickle (D-18) means downstream merge across pickle boundaries may surface different OptimizedShift instances on the destination than were pickled on the source; world-frame is preserved either way (see DESIGN-DECISIONS.md §”Pickle & state”).

property numerically_optimized: bool: Flag if the coordinates are numerically optimized.

property x: GSEGUtils.base_types.Vector_Float_T: Return the X component of the coordinates.

property y: GSEGUtils.base_types.Vector_Float_T: Return the Y component of the coordinates.

property z: GSEGUtils.base_types.Vector_Float_T: Return the Z component of the coordinates.

property xyz: GSEGUtils.base_types.Array_Nx3_Float_T: Return the XYZ coordinates as a numpy array.

property yxz: GSEGUtils.base_types.Array_Nx3_Float_T: Return the coordinates in YXZ column order.

property spher: GSEGUtils.base_types.Array_Nx3_Float_T

Return the coordinates in spherical RHV form relative to socs_origin.

When socs_origin is undefined, (0, 0, 0) is treated as the origin.

Returns:: Spherical coordinates as (N, 3) [range, horizontal, vertical].
Return type:: Array_Nx3_Float_T

property r: GSEGUtils.base_types.Vector_Float_T

Returns radial component of the spherical coordinates.

Return type:: Vector_Float_T

property hz: GSEGUtils.base_types.Vector_Float_T

Return the horizontal angles of the spherical coordinates.

Return type:: Vector_Float_T

property v: GSEGUtils.base_types.Vector_Float_T

Return the vertical angles of the spherical coordinates.

Return type:: Vector_Float_T

property rhv: GSEGUtils.base_types.Array_Nx3_Float_T

Returns the coordinates as spherical coordinates.

Return type:: Array_Nx3_Float_T

property fov: FoV

Returns the field of view of the point cloud.

Return type:: FoV

rotate(rotation)

Rotate the current coordinates in place by a 3x3 rotation matrix.

Parameters:: rotation (Array_3x3_T) – 3x3 rotation matrix.

translate(translation)

Translate the current coordinates in place.

Parameters:: translation (Vector_3_T) – Translation vector added to each coordinate.

scale(scale)

Scale the current coordinates in place (component-wise).

Parameters:: scale (Vector_3_T) – Per-axis scale vector multiplied onto the coordinates.

transform(affine)

Transform the current coordinates in place using a 4x4 affine matrix.

Parameters:: affine (Array_4x4_T) – 4x4 affine transformation matrix.

classmethod from_spherical(spher)

Build an instance from spherical coordinates in RHV format.

Parameters:: spher (Array_Nx3_T) – Spherical coordinates as (N, 3) [range, horizontal, vertical].
Returns:: New CartesianCoordinates built from the converted XYZ.
Return type:: Self

class pchandler.geometry.coordinates.AbstractCoordinates

Bases: FixedLengthArray, ABC

Abstract base for all coordinate classes; carries a UUID4 identity.

id: UUID4

class pchandler.geometry.coordinates.Abstract2dCoordinates

Bases: ArrayNx2, AbstractCoordinates, ABC

Abstract base for 2D coordinate classes exposing row and col.

abstract property row: ndarray[tuple[Any, ...], dtype[Any]]: Return the row component of the 2D coordinates.

abstract property col: ndarray[tuple[Any, ...], dtype[Any]]: Return the column component of the 2D coordinates.

class pchandler.geometry.coordinates.Abstract3dCoordinates

Bases: ArrayNx3, AbstractCoordinates, ABC

Abstract coordinates with support for a transformation to custom coordinate system and a scan center parameter.

Parameters:

project_transformation (Array_4x4_T | None) – Affine transformation array representing transform from scan coordinates to project coordinates.
socs_origin (Vector_3_T | None) – Scan center coordinate in the current coordinate system.

project_transformation: Array_4x4_T | None

socs_origin: Vector_3_T | None

abstract property xyz: ndarray[tuple[Any, ...], dtype[floating]]: Return the Cartesian coordinates as (N, 3) XYZ.

abstract property spher: ndarray[tuple[Any, ...], dtype[floating]]: Return the spherical coordinates as (N, 3) RHV.