Template Struct VoxelHashMap

Struct Documentation

template<typename VoxelIndex = Eigen::Vector3i, typename PointType = Eigen::Vector3d, typename VoxelBucketType = DefaultVoxelBucket<PointType>, typename InsertionStrategy = impl::first_n_point>
struct VoxelHashMap

Spatial hash map for organizing 3D points into voxels.

Template-based voxel hash map supporting optional per-voxel metadata (e.g., observation counts, timestamps). Uses efficient robin_map for fast O(1) average-case lookups and insertions.

Template Parameters:

  • VoxelIndex – Type for voxel coordinates, e.g., Eigen::Vector3i

  • PointType – Type for 3D points, e.g., Eigen::Vector3d or Eigen::VectorXd

  • VoxelBucketType – Per-voxel bucket type; DefaultVoxelBucket<PointType> (default) for minimal memory footprint, or use a custom bucket type with other metadata such as observation counts and timestamps. Custom bucket types are supported as long as they expose a points_type.

Public Types

using VoxelBucket = VoxelBucketType

Bucket type alias – the type stored at each occupied voxel.

using point_type = PointType

Point type alias for template consistency.

Public Functions

VoxelHashMap(double voxel_size, double max_distance = 100.0, std::size_t max_points_per_voxel = 20, std::size_t min_pts_threshold = 1, std::size_t num_attributes = 0)

Constructor for the voxel hash map.

Parameters:

  • voxel_size[in] Size of each voxel in coordinate units.

  • max_distance[in] Maximum distance to retain points from a reference.

  • max_points_per_voxel[in] Maximum number of points allowed per voxel.

  • min_pts_threshold[in] Minimum number of points required in a voxel to be considered valid.

  • num_attributes[in] Number of additional attributes for dynamic-size points.

inline bool empty() const

Check if the hash map is empty.

Returns:

True if no voxels are present, false otherwise.

inline void clear()

Clear all voxels from the map.

void update(const std::vector<PointType> &points, const PointType &position)

Insert points and trim voxels that are far from position.

Parameters:

  • points[in] Vector of points to insert.

  • position[in] Reference position for distance trimming.

void add_points(const std::vector<PointType> &points)

Insert points into the map.

Parameters:

points[in] Vector of points to insert.

template<typename PT = PointType, typename std::enable_if<impl::is_eigen_vector<PT>::value, int>::type = 0>
inline void add_points(const Eigen::Ref<const ArrayXXdR> &points)

Insert points from an Eigen matrix into the map.

Only participates in overload resolution when PointType is a plain Eigen vector (e.g., Vector3d, VectorXd). Not available for structured point types such as IndexedPoint; use add_point() or add_points(vector) for those.

Parameters:

points[in] Row-major matrix where each row is a point.

void remove_voxels_far_from_location(const PointType &origin)

Remove voxels far from a specified location.

Parameters:

origin[in] Location to measure distance from.

ArrayXXdR extract_voxels_far_from_location(const PointType &origin)

Extract voxels far from a specified location.

Parameters:

origin[in] Location to measure distance from.

Returns:

Matrix of points from extracted voxels.

std::vector<PointType> pointcloud_vector() const

Get a complete pointcloud as a vector.

Returns:

Vector containing all points from all voxels.

ArrayXXdR pointcloud() const

Get a complete pointcloud as an Eigen matrix.

Returns:

Matrix where each column is a point (3 rows + attributes).

std::tuple<PointType, double> get_closest_neighbor(const PointType &query, double max_distance_sq = std::numeric_limits<double>::max()) const

Find the closest point in the map to a query point.

Parameters:

  • query[in] The query point.

  • max_distance_sq[in] Maximum squared distance to search.

Returns:

Tuple of (closest_point, squared_distance). If no point is found within max_distance_sq, squared_distance will be >= max_distance_sq.

const VoxelBucketType &get_voxel_bucket(const PointType &point) const

Return the bucket for the voxel containing point, or a default (zero-initialized) bucket if no such voxel exists.

Parameters:

point[in] The query point.

Returns:

Const reference to the voxel bucket, or a default bucket.

inline Eigen::Index point_cols() const

Returns the row width of a serialized point.

Returns:

the row width of a serialized.

void add_point(const PointType &point)

Insert a single point into the map.

Parameters:

point[in] The point to insert.

inline std::size_t max_points_per_voxel() const

Return the maximum number of points allowed per voxel.

Returns:

Maximum points per voxel as set at construction.

inline std::size_t min_pts_threshold() const

Return the minimum number of raw insertions required for a voxel to appear in the output.

Returns:

Minimum points threshold as set at construction.

Public Members

InsertionStrategy strategy_

Per-map insertion strategy instance (holds any mutable state such as RNG).

Public Static Functions

static inline VoxelIndex point_to_voxel(const PointType &point, const double inv_voxel_size)

Convert a point to its voxel index.

Voxelization is based on the spatial (3-D position) part only; any extra attributes or index fields (as in IndexedPoint) are ignored.

Parameters:

  • point[in] The query point.

  • inv_voxel_size[in] Inverse of voxel size (1.0 / voxel_size).

Returns:

Voxel index containing the point.