pchandler.filters

Public API for pchandler.filters.

Re-exports key filter classes (cartesian, spherical, downsample, outlier, scalar-field, GPU) via the lazy __getattr__ mechanism so heavy or optional dependencies (e.g. cudf / cuspatial) are not imported at package-import time.

class pchandler.filters.BoxFilter

Bases: PointCloudFilter

Filter points by a 3D axis-aligned bounding box.

__init__(minimum, maximum)

Filter points based on a 3D bounding box.

Parameters:

minimum (Vector_3_T) – Lower corner of the bounding box.
maximum (Vector_3_T) – Upper corner of the bounding box.

property extents: bool'>)]

Compute the extents of the bounding box per axis.

Returns:: maximum - minimum per axis.
Return type:: Vector_3_T

mask(pcd, mode='local')

Create a boolean mask for points within a 3D bounding box.

Parameters:

pcd (PointCloudData)
mode (Literal["local", "global"], default="local") – Defines the coordinate frame of reference for the bounding box.

Return type:

Vector_Bool_T

class pchandler.filters.PolygonFilter

Bases: PointCloudFilter

Filter points by a polygon projected on a specified plane.

__init__(polygon, plane='xy')

Filter points based on a polygon projected on a specified plane.

Parameters:

polygon (ValidatedPolygonT) – Polygon defining the filter region.
plane (PlaneStrings, default="xy") – Plane on which the polygon is projected.

mask(pcd, mode='local')

Create a boolean mask from the points inside the projected polygon.

Parameters:

pcd (PointCloudData)
mode (Literal["local", "global"], default="local") – Defines the coordinate frame of reference for the bounding box.

Return type:

Vector_Bool_T

class pchandler.filters.SphereFilter

Bases: PointCloudFilter

Filter points by a sphere with a defined center and radius.

__init__(sphere_center, radius)

Filter points based on a sphere with a defined center and radius.

Parameters:

sphere_center (Vector_3_T) – Center of the sphere.
radius (PositiveFloat) – Radius of the sphere.

mask(pcd, mode='local')

Create a boolean mask for points within the sphere.

Parameters:

pcd (PointCloudData)
mode (Literal["local", "global"], default="local") – Defines the coordinate frame of reference for the bounding box.

Return type:

Vector_Bool_T

class pchandler.filters.GenericFieldFilter

Bases: PointCloudFilter

Generic filter that evaluates a callable on a named field.

__init__(field_label, filter_func)

Build a generic filter that operates on a single named field.

Parameters:

field_label (str) – A label or name for the field.
filter_func (Callable[[NDArray], Vector_Bool_T]) – A callable function used to perform filtering logic. Must return a boolean mask.

mask(pcd)

Create a boolean mask from the defined field and function.

Parameters:: pcd (PointCloudData) – Point cloud to be evaluated.
Returns:: Boolean mask returned by filter_func evaluated on the named field.
Return type:: Vector_Bool_T

class pchandler.filters.PointCloudFilter

Bases: ABC

Abstract base class for PointCloudData filters.

extract(pcd)

Return a new point cloud built from the points selected by the mask.

The existing point cloud is reduced to only the points defined by the negated mask.

Parameters:: pcd (PointCloudData) – Source point cloud (mutated: keeps only the negated-mask points).
Returns:: New point cloud carrying the selected points.
Return type:: PointCloudData

abstractmethod mask(pcd)

Compute and return a boolean mask for the provided point cloud.

Parameters:: pcd (PointCloudData) – Point cloud to be evaluated.
Returns:: Boolean mask, True for points kept by the filter.
Return type:: Vector_Bool_T

reduce(pcd)

Reduce the point cloud in place to the points selected by the mask.

Parameters:: pcd (PointCloudData) – Point cloud mutated in place.

sample(pcd)

Return a copy of the point cloud sampled using the boolean mask.

Parameters:: pcd (PointCloudData) – Source point cloud (not mutated).
Returns:: New point cloud carrying the sampled points.
Return type:: PointCloudData

class pchandler.filters.AngleBinDownsample

Bases: object

Downsample a point cloud using spherical-angle binning in horizontal/vertical space.

__init__(angle_bin_size, weighting_method='linear')

Build a spherical-angle-bin downsampler (2D over horizontal × vertical).

Parameters:

angle_bin_size (PositiveFloat) – Edge length of each angular bin (same units as the spherical coordinates being binned).
weighting_method (WeightingMethods, default="linear") – Per-point weighting strategy. One of "nearest", "constant", "linear".

sample(pcd)

Return a downsampled copy of the point cloud built from angle-bin centroids.

Parameters:: pcd (PointCloudData) – Source point cloud.
Returns:: New point cloud with one point per occupied angular bin.
Return type:: PointCloudData

class pchandler.filters.RandomDownsampleFilter

Bases: PointCloudFilter

Downsample a point cloud by uniformly random sampling a fixed ratio of points.

__init__(size, seed=None)

Downsample the point cloud by randomly sampling a fixed ratio of points.

Parameters:

size (PositiveFloat) – Fraction of points to keep, in the open interval (0.0, 1.0).
seed (int | None, optional) – Optional seed for the per-instance random generator. None (default) preserves the prior nondeterministic behaviour for no-arg callers without mutating the global numpy RNG state (TEST-07, Phase 8 D-11).

mask(pcd)

Create a mask based on a uniformly random sample of points.

Parameters:: pcd (PointCloudData) – Point cloud to be sampled.
Returns:: Boolean mask, True for sampled points.
Return type:: Vector_Bool_T

class pchandler.filters.VoxelDownsample

Bases: object

Downsample a point cloud onto a regular 3D voxel grid.

__init__(voxel_size, weighting_method='linear')

Build a voxel-grid downsampler.

Voxel centroids represent the downsampled point cloud.

Parameters:

voxel_size (PositiveFloat) – Edge length of each cubic voxel cell.
weighting_method (WeightingMethods, default="linear") – Per-point weighting strategy. One of "nearest", "constant", "linear".

sample(pcd)

Return a downsampled copy of the point cloud built from voxel centroids.

Parameters:: pcd (PointCloudData) – Source point cloud.
Returns:: New point cloud with one point per occupied voxel.
Return type:: PointCloudData

class pchandler.filters.CartesianOutlierFilter

Bases: BaseOutlierFilter

Outlier filter for point clouds in cartesian coordinates.

mask(pcd)

Create a boolean mask of inliers using cartesian-coordinate statistics.

Parameters:: pcd (PointCloudData) – Source point cloud.
Returns:: Boolean mask, True for inliers.
Return type:: Vector_Bool_T

class pchandler.filters.SphericalOutlierFilter

Bases: BaseOutlierFilter

Outlier filter for point clouds in spherical coordinates.

mask(pcd)

Create a boolean mask of inliers using spherical-coordinate statistics.

Parameters:: pcd (PointCloudData) – Source point cloud.
Returns:: Boolean mask, True for inliers.
Return type:: Vector_Bool_T

class pchandler.filters.ScalarFieldFilter

Bases: PointCloudFilter

Filter points by an absolute value range over a named scalar field.

__init__(field_label, lower_bound=-np.inf, upper_bound=np.inf)

Filter points based on a value range for a particular scalar field.

Parameters:

field_label (str) – Name of the scalar field to evaluate.
lower_bound (float, default=-np.inf) – Lower (inclusive) bound on the scalar value.
upper_bound (float, default=np.inf) – Upper (inclusive) bound on the scalar value.

mask(pcd)

Create a boolean mask for the values within the specified scalar field range.

Parameters:: pcd (PointCloudData)
Return type:: Vector_Bool_T

class pchandler.filters.ScalarFieldPercentileFilter

Bases: PointCloudFilter

Filter points by a percentile range over a named scalar field.

__init__(field_label, lower_percentile=0, upper_percentile=100)

Filter points based on percentile ranges for a given scalar field.

Parameters:

field_label (str) – Name of the scalar field to evaluate.
lower_percentile (PercentileT, default=0) – Lower percentile (0 ≤ lower_percentile < 100).
upper_percentile (PercentileT, default=100) – Upper percentile (lower_percentile ≤ upper_percentile < 100).

mask(pcd)

Create a boolean mask from the target percentile range.

Parameters:: pcd (PointCloudData) – Source point cloud.
Returns:: Boolean mask, True for points whose value falls inside the percentile range.
Return type:: Vector_Bool_T

class pchandler.filters.FoVFilter

Bases: PointCloudFilter

Filter points by a field-of-view (FoV) angular region.

__init__(fov)

Filter points based on a given field of view (FoV).

Parameters:: fov (FoV) – Field of view object defining the top, bottom, left, and right boundaries.

mask(pcd)

Create a boolean mask for a point cloud based on a given field of view (FoV).

Parameters:: pcd (PointCloudData)
Return type:: Vector_Bool_T

class pchandler.filters.RangeFilter

Bases: PointCloudFilter

Filter points by a minimum/maximum spherical-range threshold.

__init__(low=0.0, high=np.inf)

Filter points based on minimum and maximum range thresholds.

Parameters:

low (float, default=0.0) – Lower (inclusive) range threshold.
high (float, default=``np.inf``) – Upper (inclusive) range threshold.

mask(pcd)

Create a boolean mask for a point cloud based on given range limits.

Parameters:: pcd (PointCloudData)
Return type:: Vector_Bool_T

class pchandler.filters.SphericalPolygonFilter

Bases: PointCloudFilter

Filter points by a polygon defined in spherical (horizontal × vertical) coordinates.

__init__(polygon)

Filter points based on a polygon defined in spherical coordinates.

Parameters:: polygon (Polygon) – Polygon defining the filter region in (horizontal, vertical) spherical-angle coordinates.

mask(pcd)

Create a boolean mask for a point cloud based on a polygon defined in spherical coordinates.

Points inside the polygon are marked as True.

Parameters:: pcd (PointCloudData)
Return type:: Vector_Bool_T

class pchandler.filters.PolygonFilterGPU

Bases: PointCloudFilter

GPU-accelerated polygon filter projected on a specified plane.

__init__(polygon, plane='xy')

Filter points based on a polygon projected on a specified plane (GPU backend).

Parameters:

polygon (ValidatedPolygonT) – Polygon defining the filter region.
plane (PlaneStrings, default="xy") – Plane on which the polygon is projected.

mask(pcd)

Create a boolean mask from the points inside the projected polygon.

Parameters:: pcd (PointCloudData)
Return type:: Vector_Bool_T

class pchandler.filters.SphericalPolygonFilterGPU

Bases: PointCloudFilter

GPU-accelerated polygon filter defined in spherical-angle coordinates.

__init__(polygon)

Filter points based on a polygon defined in spherical-angle coordinates (GPU backend).

Parameters:: polygon (ValidatedPolygonT) – Polygon defining the filter region in (horizontal, vertical) spherical-angle coordinates.

mask(pcd)

Create a mask of points inside the spherical-angle polygon.

Parameters:: pcd (PointCloudData) – The input point cloud data containing points to be processed.
Returns:: Boolean mask, True for points inside the polygon.
Return type:: Vector_Bool_T

Modules

`cartesian_filters`	Cartesian coordinate-based filters.
`core`	Abstract filter base class plus a generic field-based filter.
`downsample`	Downsampling filters for point clouds (random, voxel-grid, angle-bin).
`gpu`	GPU-accelerated filters backed by cudf and cuspatial.
`outlier_filter`	Statistical outlier removal filters.
`scalar_field_filters`	Scalar-field-based filters.
`spherical_coordinate_filters`	Spherical-coordinate-based filters.