pchandler.geometry.util

Geometry utilities: outline polygons and min/max bounding-box helpers.

Functions

Compute the outline of the point cloud as a polygon in a specific 2D projection.

Classes

Countains the minimum and maximum points of a set of coordinates to represent it's bounding box.

pchandler.geometry.util.get_outline_polygon(pcd, plane, alpha_value=10.0, nb_points=-1, seed=None)

Compute the outline of the point cloud as a polygon in a specific 2D projection.

Parameters:

pcd (PointCloudData) – The point cloud data used to define the outline.
plane (str) – The plane of projection (‘xy’, ‘xz’, or ‘yz’).
alpha_value (float, default=10.0) – The alpha value for the alpha shape algorithm, controlling the detail of the outline.
nb_points (int, default=-1) – The number of points to use for the computation. If -1 (the default), the function auto-caps the projection at _DEFAULT_OUTLINE_MAX_POINTS = 100_000 points (see Notes). Pass a positive value to fix the sample size explicitly, or nb_points=len(pcd) to restore the pre-Phase-4 “use all points” behaviour.
seed (int or None, default=None) – Seed for the internal numpy.random.Generator used by both the sampling permutation and the dimensionality-stabilising jitter. None (the default) resolves to seed 0 — i.e. the function is deterministic by default (see Notes). Pass an explicit integer to produce a different (but still deterministic) outline.

Returns:

A Shapely Polygon representing the outline of the point cloud.

Return type:

Polygon

Raises:

ValueError – If the specified plane is invalid.
NotImplementedError – If the outline computation results in an unsupported geometry type.

Notes

Phase 4 PERF-02 introduced two intentional behavioural changes to this function (Phase 4 D-23 + D-24):

Deterministic by default (D-23). Before Phase 4 the trim permutation and the dimensionality-stabilising jitter used numpy’s global RNG, so repeated calls on the same point cloud produced different polygons across runs. Both call sites now use rng = numpy.random.default_rng(seed if seed is not None else 0); seed=None is the deterministic path. Callers that want repeatable results across configurations can pass seed explicitly.
Auto-cap at 100 000 points (D-24). Before Phase 4, passing nb_points=-1 (the default) caused the function to feed all projected points to alphashape.alphashape, whose runtime scales super-linearly with the input size (15 s at 100 k points on a typical dev host; minutes at 1 M points). The default now auto-trims the projection to _DEFAULT_OUTLINE_MAX_POINTS (100 000) via the seeded permutation, giving bounded runtime regardless of input size. Callers that previously relied on nb_points=-1 consuming all points must now pass nb_points=len(pcd) explicitly to restore that behaviour. This change has no deprecation cycle — the new default IS the documented behaviour going forward.

class pchandler.geometry.util.MinMaxPoints

Bases: NamedTuple

Countains the minimum and maximum points of a set of coordinates to represent it’s bounding box.

Parameters:

classmethod from_points(points, already_applied_shift_vec=None)

Create an instance from a given set of points.

Parameters:

points (Array_Nx3_T) – Input (N, 3) array of points.
already_applied_shift_vec (Vector_3_T, optional) – If provided, a vector that represents a shift already applied to the points; it is added back when computing the min/max.

Returns:

An instance of the class initialized with the calculated minimum and maximum points based on the given points and the shift vector.

Return type:

Self

classmethod from_minmax_points(minmax_points)

Create an instance from a set of MinMaxPoints or Array_Nx3_T objects.

Parameters:: minmax_points (Iterable[Self | Array_Nx3_T]) – Collection of point sets, either as point clouds or MinMaxPoints objects.
Return type:: Self

property central_point: GSEGUtils.base_types.Vector_3_T

Return the center point of the bounding box.

property extents: GSEGUtils.base_types.Vector_3_T

Return the per-axis extents of the bounding box.

static __new__(_cls, minimum, maximum)

Create new instance of MinMaxPoints(minimum, maximum)