GridSample

class GridSample(grid_size=0.05, hash_type='fnv', mode='train', return_inverse=False, return_grid_coord=False, return_min_coord=False, return_displacement=False, project_displacement=False, sum_keys=None, min_keys=None)

Bases: object

Voxel-downsample a point cloud onto a hash grid.

Floors coord / grid_size to integer voxel indices, hashes them, and deduplicates points per voxel. In mode="train" it keeps one random point per occupied voxel and subsamples every per-point key in index_valid_keys via index_operator, returning a single dict. In mode="test" it instead returns a list of fragment dicts that together cover all points (one point per voxel per fragment), each carrying an index key. Optionally aggregates selected keys per voxel (sum or min) and emits integer grid_coord for sparse convolutions. Requires coord (asserted). Registered as GridSample – use this string as the type in a transform=[...] config list.

Parameters:

• grid_size (float | Sequence[float]) – voxel edge length in (normalized) coordinate units; smaller keeps more points. Defaults to 0.05.

• hash_type (str) – voxel hash, "fnv" (FNV64-1A) or otherwise the ravel/raster hash. Defaults to "fnv".

• mode (str) – "train" (one random point per voxel, single dict) or "test" (list of covering fragments). Defaults to "train".

• return_inverse (bool) – if True, store an inverse array mapping each original point to its voxel. Defaults to False.

• return_grid_coord (bool) – if True, store integer grid_coord and append it to index_valid_keys. Defaults to False.

• return_min_coord (bool) – if True, store the per-sample min_coord (grid origin, shape [1, 3]). Defaults to False.

• return_displacement (bool) – if True, store each point’s displacement from its voxel center in [-0.5, 0.5]. Defaults to False.

• project_displacement (bool) – if True, project the displacement onto the point normal to a scalar (requires normal). Defaults to False.

• sum_keys (Sequence[str], optional) – keys summed over the points in each voxel (e.g. pooling energy). None means none. Defaults to None.

• min_keys (Sequence[str], optional) – keys reduced by per-voxel minimum. None means none. Defaults to None.

Note

Only keys in index_valid_keys are downsampled together; any point-aligned array missing from that list keeps its original length and silently desynchronizes from coord. grid_size is in the same frame as coord – after NormalizeCoord it is in normalized units. mode="test" returns a list of dicts, not a single dict, so it is normally the terminal geometric step of a test pipeline.

Example

>>> import numpy as np
>>> from pimm.datasets.transform import GridSample
>>> np.random.seed(0)
>>> # 1000 points landing on a 5x5x5 integer lattice -> many coincide per voxel
>>> coord = np.floor(np.random.rand(1000, 3) * 5).astype("f4")
>>> data = {"coord": coord.copy(), "energy": np.random.rand(1000, 1).astype("f4")}
>>> out = GridSample(grid_size=1.0, mode="train", return_grid_coord=True)(data)
>>> len(out["coord"])  # one point kept per occupied voxel: 1000 -> 5**3 voxels
125
>>> out["grid_coord"].shape, out["grid_coord"].dtype  # integer voxel indices added
((125, 3), dtype('int64'))

static fnv_hash_vec(arr)

FNV64-1A

static ravel_hash_vec(arr)

Ravel the coordinates after subtracting the min coordinates.