voxel_grid_downsample — 3D preprocess op

• Data kinds: points → points

• Call: import fullseye as fs; fs.ledger.voxel_grid_downsample(points, voxel_size: 'float') (to call the implementation directly, import pcl_filter; pcl_filter.voxel_grid_downsample(points, voxel_size: 'float'); from the registry, ops3d.get("voxel_grid_downsample"))

Usage

Thin a point set on a lattice of edge voxel_size, collapsing each cell to one centroid point (deterministic).

Divides space into cubic cells of side voxel_size and represents the points falling into the same cell by their centroid, 1 point. A standard technique to even out density variations and bound the downstream (ICP, features) cost via the point count. The output order is fixed to the lexicographic order of the voxel coordinates (the same input always gives the same output = deterministic).

Parameters

points : array_like, shape (N, 3)

Input point cloud.

voxel_size : float

Side length of a cell (> 0). Larger thins more strongly.

Returns

ndarray, shape (M, 3)

Centroid of each occupied cell (M <= N). All lie inside the axis-aligned bounding box of the input.

Notes

voxel_size <= 0 raises ValueError. Empty input returns an empty (0,3) (graceful). A centroid is the mean of the points in its cell, so it always lies inside the convex hull of the input points (hence inside the bbox).

Background guides (the physics and conventions behind this op)

• depth_sensors — Depth sensors — ranging principles, real-device figures, how dropouts appear

References (sample data, literature)

• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).

• Operator provenance and references — the sources of the research/methods this op family came from.

Runnable examples (verified samples that actually call this op)

• pointcloud_downsampling — py -3.11 examples_3d/pointcloud_downsampling.py

Ops the type connects to (they accept points as input)

points_to_voxel · gaussians_to_voxel · estimate_point_normals · to_points · match_points_ncc · match_pca · moment_axes · icp_point2point_3d

Same category (preprocess)

statistical_outlier_removal · radius_outlier_removal · mls_smooth · volume_downsample

*Provenance: pcl_filter.py — 3D operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*

© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.