pchandler.geometry

Public API for pchandler.geometry.

Re-exports key classes and functions from the submodules (coordinates, transforms, splitter, util, spherical) via the lazy __getattr__ mechanism.

class pchandler.geometry.OptimizedShiftManager

Bases: object

Manager for optimized shifts.

This class allows registration, retrieval, and management of shifts while maintaining a global configuration for numerical precision.

Parameters:: FLOAT32_DECIMAL_PRECISION (int) – Default decimal precision for floating point calculations.

FLOAT32_DECIMAL_PRECISION: int = 7

exception ShiftNotFeasibleError

Bases: Exception

Raised when no feasible shift exists for the requested coordinate set.

exception ShiftUUIDAlreadyTaken

Bases: Exception

Raised when registering a UUID that is already known to the manager.

exception ShiftUUIDNotFound

Bases: Exception

Raised when retrieving an unknown UUID from the manager.

__init__(minimum_decimal_places=3)

Initialize the manager singleton.

Parameters:: minimum_decimal_places (int, optional) – The minimum number of decimal places to be used. Default is 3.

property all_shifts: list[OptimizedShift]

Return all currently-registered optimized shifts.

Returns:: All shifts currently held by the manager (weak-ref values only).
Return type:: list[OptimizedShift]

get_by_uuid(u)

Retrieve an OptimizedShift by its UUID.

Parameters:: u (UUID) – UUID of the shift to retrieve.
Returns:: The matching shift, or None if no shift is registered for u.
Return type:: OptimizedShift | None

is_shift_needed(values)

Check whether values exceed the maximum number representable in float32.

Parameters:: values (Array_Nx3_T) – Candidate coordinates to evaluate.
Returns:: True if at least one component would lose precision without a shift.
Return type:: bool

is_shift_possible(values)

Check whether the range of values is within the representable limit.

Parameters:: values (Array_Nx3_T) – Candidate coordinates to evaluate.
Returns:: True if a finite shift can bring all values inside the float32 representable range.
Return type:: bool

property maximum_number_representable: float

Return the maximum number representable with the configured float precision.

Returns:: 10 ** (FLOAT32_DECIMAL_PRECISION - minimum_decimal_places).
Return type:: float

property minimum_decimal_places: int

Return the minimum number of decimal places supported by the manager.

Returns:: Configured minimum decimal places.
Return type:: int

register_coordinates_to_shift(coordinates, shift)

Register coordinates to an existing optimized shift.

Associates the given coordinates with an OptimizedShift. If the registration fails, this method attempts to use a fresh OptimizedShift before raising an error.

Parameters:

coordinates (CartesianCoordinates) – Coordinate set to register.
shift (OptimizedShift or uuid.UUID) – Existing shift (or its UUID) to attempt registration with.

Returns:

The shift the coordinates were ultimately registered to (may be a new shift if the input one could not absorb them).

Return type:

OptimizedShift

Raises:

OptimizedShiftManager.ShiftUUIDNotFound – UUID not found in the manager.
OptimizedShiftManager.ShiftNotFeasibleError – Shift not feasible for the given coordinates.

register_shift(shift)

Register a shift in the manager.

If a shift with the same UUID already exists but refers to a different object instance, a ShiftUUIDAlreadyTaken is raised.

Parameters:: shift (OptimizedShift) – Shift to register.
Raises:: OptimizedShiftManager.ShiftUUIDAlreadyTaken – Shift with the same UUID already exists in the manager.

update_uuid(old_uuid, new_uuid)

Replace a registered shift’s UUID with a new one.

An error is raised if the old UUID does not exist, or if the new UUID is already in use.

Parameters:

old_uuid (uuid.UUID) – The UUID of the existing shift to be updated.
new_uuid (uuid.UUID) – The new UUID to assign to the shift.

Raises:

OptimizedShiftManager.ShiftUUIDNotFound – If old_uuid is not registered.
OptimizedShiftManager.ShiftUUIDAlreadyTaken – If new_uuid is already registered.

class pchandler.geometry.OptimizedShift

Bases: object

A numerical-precision shift shared by one or more coordinate sets.

Holds the translation vector and weak references to the CartesianCoordinates instances linked to it.

All public methods on this class take Unshifted (world-frame, caller’s original frame) coordinate arrays. Internal _-prefixed helpers may take Shifted coordinates (after subtracting self._shift), and name the convention in their parameter annotation. Unshifted / Shifted are typing.NewType() aliases over npt.NDArray[np.float64]; the tag is a static-check signal only. Runtime shape/dtype validation is delegated to numpydantic on the _shift field and to validate_variables on public-method inputs.

Parameters:

shift_vec (Vector_3_T, optional) – A vector representing the shift. Defaults to (0, 0, 0).
minimum_decimal_places (int, optional) – Per-instance precision floor. When None (default), falls back to OptimizedShiftManager.minimum_decimal_places. Settable post-init via the validating setter on the same property.

__init__(shift_vec=None, *, minimum_decimal_places=None)

Initialize an OptimizedShift.

Parameters:

shift_vec (Vector_3_T, optional) – A vector representing the shift. If not provided, defaults to (0, 0, 0).
minimum_decimal_places (int, optional) – Per-instance precision floor. When None (default), falls back to OptimizedShiftManager.minimum_decimal_places. Settable post-init via the validating setter on the same property.

check_addibility(unshifted_pts)

Check whether unshifted_pts can be absorbed into this shift.

Parameters:: unshifted_pts (Unshifted) – Candidate points in their original, world-frame (un-shifted) frame.
Returns:: True if a feasible shift can absorb the points.
Return type:: bool

property maximum_number_representable: float

Maximum number representable in float32 given this instance’s threshold.

Returns:: 10 ** (FLOAT32_DECIMAL_PRECISION - self.minimum_decimal_places).
Return type:: float

property minimum_decimal_places: int

Per-instance precision threshold; falls through to the manager default when unset.

Returns:: This shift’s configured minimum decimal places, or the OptimizedShiftManager default if not overridden.
Return type:: int

reattach_member(coordinate_set)

Reattach a coordinate set to this shift without changing the other members.

unshifted_pts should be the original float64 points before shifting.

Parameters:: coordinate_set (CartesianCoordinates) – Coordinate set to reattach.

register(coordinate_set)

Register a CartesianCoordinates instance against this shift.

Tries to add coordinate_set to this shift. If the coordinates fit without modification, they are added directly; otherwise the method attempts to expand the shift via _expand_and_add(). If even that fails, a ShiftNotFeasibleError is raised.

Parameters:: coordinate_set (CartesianCoordinates) – The CartesianCoordinates object to register.
Raises:: OptimizedShiftManager.ShiftNotFeasibleError – If the coordinates cannot fit into this shift and cannot be made to fit by expansion.

unregister(coordinate_set)

Remove a coordinate set from this shift.

Parameters:: coordinate_set (CartesianCoordinates) – Coordinate set to unregister; no-op if not currently registered.

Notes

WR-05 (Phase 3 code review): we deliberately do NOT use weakref.WeakSet.discard() / remove() / __contains__() here because internally those call set.discard(weakref.ref(item)), and set lookups confirm bucket membership via __eq__. CartesianCoordinates inherits its __eq__ from numpy.ndarray (via numpydantic / GSEGUtils.base_arrays.BaseArray), which returns an array rather than a scalar — every public WeakSet method that touches __eq__ therefore raises ValueError (“truth value of an array with more than one element is ambiguous”).

The identity-based manual loop below is the workaround: iterate the underlying set[weakref.ref] and match referents via is (object identity), bypassing __eq__ entirely. The type: ignore annotates the documented CPython attribute access; __contains__ on OptimizedShift itself is also identity-based for the same reason (see __contains__()).

property uuid: UUID

Return the shift’s UUID.

Returns:: The shift’s stable UUID.
Return type:: uuid.UUID

property value: GSEGUtils.base_types.Vector_3_T

Return the current 3D shift vector.

Returns:: The translation vector applied by this shift.
Return type:: Vector_3_T

Modules

`coordinates`	Cartesian coordinate classes with numerical-precision shift management.
`optimal_shift`	Numerical-precision shift management for Cartesian coordinates.
`spherical`	Spherical-geometry classes and helpers (Angle units, field-of-view tiles).
`splitter`	Multiprocessing-based point-cloud splitters keyed on FoV trees.
`transforms`	Transforms module for pchandler.geometry.
`util`	Geometry utilities: outline polygons and min/max bounding-box helpers.