Class Representation

Nested Relationships

Nested Types

Class Documentation

class Representation

3D spatial representation backed by coarse and fine voxel grids.

Coarse cells group nearby fine voxels for fast neighborhood retrieval. Fine voxels hold point-to-cell assignments and visibility metadata used by mapping and visualization routines.

Public Types

using shared_ptr = std::shared_ptr<Representation>

Shared pointer type.

Public Functions

Representation(const double voxelHalfSizeUnscaled_, const double coarseHalfSizeUnscaled_, const double scale_ = 10000.0)

Constructor.

Parameters:

  • voxelHalfSizeUnscaled_ – Fine-voxel half-size in world units.

  • coarseHalfSizeUnscaled_ – Coarse-cell half-size in world units.

  • scale_ – Conversion scale from world units to internal units.

~Representation() = default

Destructor.

inline size_t size_closest_cells() const

Returns the number of currently ordered cells.

Returns:

Number of entries in orderedCellIds.

inline size_t get_number_cells()

Returns the number of cells currently in the representation.

Returns:

Number of cells in the representation {numberQueryCells, numberClosestCells, totalNumberCells}.

bool exists(const cell_id_t &cellId_) const

Checks whether a cell exists.

Parameters:

cellId_ – Cell identifier checked for existence.

Returns:

true if the cell exists.

cell_id_t::vector get_cells(const array3D_t &pointUnscaled_)

Get coarse cells (ids) for sorting, given a point.

Parameters:

pointUnscaled_ – Query point in world coordinates (camera location).

Returns:

Cell ids associated with the coarse bucket around the query.

cell_id_t get_cell_id(const array3D_t &pointUnscaled_)

Get cell id for a given point in the world.

Parameters:

pointUnscaled_ – Query point in world coordinates.

Returns:

Cell id of the voxel containing the query point.

cell_id_t get_cell_id(const point_id_t &pointId_) const

Gets the cell that currently contains a point id.

Parameters:

pointId_ – Point identifier mapped to a voxel cell.

Returns:

Cell identifier containing the point.

inline array3D_t::pair get_cell_corners(const cell_id_t &cellId_) const

Get the corners of a given cell.

Parameters:

cellId_ – Cell identifier whose corners are requested.

Returns:

Pair containing minimum and maximum cell corners.

inline array3D_t get_center(const cell_id_t &cellId_) const

Gets the center of a given cell.

Parameters:

cellId_ – Cell identifier whose center is requested.

Returns:

Cell center in world coordinates.

output_t<point_id_t::set> get_points(const cell_id_t &cellId_)

Gets all point ids contained in a cell.

Parameters:

cellId_ – Cell identifier whose points are requested.

Returns:

Set of point ids, or a failure code.

fail_t insert(const cell_id_t &cellId_, const point_id_t &pointId_)

Inserts a point into the representation.

Parameters:

  • cellId_ – Destination cell receiving the point id.

  • pointId_ – Point identifier inserted into cellId_.

Returns:

Success or failure status of the insertion.

fail_t remove(const cell_id_t &cellId_, const point_id_t &pointId_)

Removes a point from the representation.

Parameters:

  • cellId_ – Source cell from which the point id is removed.

  • pointId_ – Point identifier removed from cellId_.

Returns:

Success or failure status of the removal.

fail_t remove(const point_id_t &pointId_)

Removes a point from the representation by point id only.

Parameters:

pointId_ – Point identifier removed from its currently mapped cell.

Returns:

Success or failure state.

output_t<bool> contains(const cell_id_t &cellId_, const array3D_t &point_) const

Checks if a point is contained in a given cell.

Parameters:

  • cellId_ – Cell identifier used for the containment test.

  • point_ – Query point coordinates in world units.

Returns:

true if point_ lies inside cellId_.

fail_t switch_cell(const cell_id_t &oldCellId_, const cell_id_t &newCellId_, const point_id_t &pointId_)

Moves a point from one cell to another.

Parameters:

  • oldCellId_ – Cell currently holding pointId_.

  • newCellId_ – Destination cell receiving pointId_.

  • pointId_ – Point identifier moved between cells.

Returns:

Success or failure state.

array3D_t::pair get_corners(const cell_id_t &cellId_) const

Gets the corners of a cell.

Parameters:

cellId_ – Cell identifier whose corners are requested.

Returns:

Pair (minCorner, maxCorner) in world coordinates.

void highlight(const cell_id_t &cellId_)

Marks a cell as highlighted.

Parameters:

cellId_ – Cell identifier marked as highlighted.

void unhighlight(const cell_id_t &cellId_)

Clears highlight state for a cell.

Parameters:

cellId_ – Cell identifier marked as not highlighted.

inline bool is_highlighted(const cell_id_t &cellId_) const

Checks whether a cell is highlighted.

Parameters:

cellId_ – Cell identifier queried for highlight state.

Returns:

true when the cell is highlighted.

inline size_t get_point_count(const cell_id_t &cellId_) const

Returns the number of points stored in a cell.

Parameters:

cellId_ – Cell identifier queried for point count.

Returns:

Point count for the cell.

void sort_cells(const pose_t &cameraToWorldTransformation_, const intrinsics_t &intrinsics_)

Sorts cells according to camera visibility heuristics.

Parameters:

  • cameraToWorldTransformation_ – Camera-to-world pose used to rank cells by distance and visibility.

  • intrinsics_ – Camera intrinsics used for image-visibility checks.

inline output_t<cell_id_t> get_closes_cell_x(size_t item_)

Returns one cell id from the ordered-cell buffer.

Parameters:

item_ – Zero-based index into the ordered-cell buffer.

Returns:

Cell identifier at the requested position.

Public Static Functions

static inline Representation::shared_ptr make_shared(double voxelHalfSize_, double coarseHalfSize_)

Creates a shared representation instance.

Parameters:

  • voxelHalfSize_ – Half-size of fine voxels in world units.

  • coarseHalfSize_ – Half-size of coarse cells in world units.

Returns:

Shared pointer to a new Representation.

static inline Representation::shared_ptr make_shared(double voxelHalfSize_, double coarseHalfSize_, double scale_)

Creates a shared representation instance with explicit scale.

Parameters:

  • voxelHalfSize_ – Half-size of fine voxels in world units.

  • coarseHalfSize_ – Half-size of coarse cells in world units.

  • scale_ – Conversion scale from world units to internal units.

Returns:

Shared pointer to a new Representation.

Private Functions

inline array3D_t __get_center(const cell_id_t &cellId_) const

Computes a cell center from its corners.

Parameters:

cellId_ – Cell identifier whose center is computed.

Returns:

Cell center in world coordinates.

inline bool __is_cell_empty(const cell_id_t &cellId_) const

Checks whether a cell contains no points.

Parameters:

cellId_ – Cell identifier checked for emptiness.

Returns:

true if the cell has zero points.

array3D_t::pair __get_cell_corners(const cell_id_t &cellId_) const

Retrieves cell corners in world coordinates.

Parameters:

cellId_ – Cell identifier whose corners are requested.

Returns:

Pair (minCorner, maxCorner).

fail_t __sanity_exists(const cell_id_t &cellId_) const

Validates that a cell id exists.

Parameters:

cellId_ – Cell identifier checked for existence.

Returns:

fail_t::NO_FAIL when valid, otherwise an error code.

fail_t __sanity_not_exists(const cell_id_t &cellId_) const

Validates that a cell id does not exist.

Parameters:

cellId_ – Cell identifier checked for non-existence.

Returns:

fail_t::NO_FAIL when valid, otherwise an error code.

fail_t __sanity_exists(const point_id_t &pointId_) const

Validates that a point id exists.

Parameters:

pointId_ – Point identifier checked for existence.

Returns:

fail_t::NO_FAIL when valid, otherwise an error code.

fail_t __sanity_not_exists(const point_id_t &pointId_) const

Validates that a point id does not exist.

Parameters:

pointId_ – Point identifier checked for non-existence.

Returns:

fail_t::NO_FAIL when valid, otherwise an error code.

bool __coarse_exists(const array3Int_t &coarseCenter_) const

Checks whether a coarse cell entry exists.

Parameters:

coarseCenter_ – Coarse-cell center in internal integer units.

Returns:

true if the coarse entry exists.

array3Int_t __compute_coarse_center(const array3D_t &point_) const

Computes coarse-cell center for a world point.

Parameters:

point_ – Query point in scaled internal coordinates.

Returns:

Coarse-cell center.

array3Int_t __compute_voxel_center(const array3D_t &point_) const

Computes voxel center for a world point.

Parameters:

point_ – Query point in scaled internal coordinates.

Returns:

Voxel center.

pair_t<cell_id_t, Voxel::shared_ptr> __create_voxel(const array3Int_t &voxelCenter_)

Creates a new voxel and assigns it a new cell id.

Parameters:

voxelCenter_ – Center of the voxel in internal integer units.

Returns:

Pair (cellId, voxelPointer) for the created voxel.

void __print_coarse_cells_histogram()

Prints a terminal histogram of fine-cell entries per coarse cell.

Each line shows coarse center coordinates, a star bar, and count.

inline array3D_t __scale(const array3D_t &point_) const

Scale the point from world units to internal representation (*100).

Parameters:

point_ – Point in world units.

Returns:

Point converted to scaled internal coordinates.

inline double __scale(const double &value_) const

Scales a scalar from world units to internal units.

Parameters:

value_ – Scalar value in world units.

Returns:

Scaled scalar value.

inline array3D_t __descale(const array3Int_t &point_) const

Descale the point from internal representation to world units (/100).

Parameters:

point_ – Point in scaled internal coordinates.

Returns:

Point converted back to world units.

inline double __descale(const double &value_) const

Descales a scalar from internal units to world units.

Parameters:

value_ – Scalar value in scaled internal units.

Returns:

Descaled scalar value.

Private Members

int _coarseHalfSize

half the size of the coarse cell (in internal representation)

int _voxelHalfSize

half the size of the voxel cell (in internal representation)

double _scale

Scale to the internal representation.

mutable std::shared_mutex _mutex

Mutex for thread-safe access.

cell_id_t::vector _orderedCellIds

Ordered list of all the octree nodes.

hash_t<array3Int_t, cell_id_t::vector> _coarseRepresentation

Coarse mapping from coarse cell center to list of voxel centers.

hash_t<cell_id_t, Voxel::shared_ptr> _allCells

All cells by their id.

hash_t<array3Int_t, cell_id_t> _fineRepresentation

Fine representation mapping from voxel center to Voxel object.

hash_t<point_id_t, cell_id_t> _pointToCellMap

Mapping from point id to cell id.

class Voxel

Class that represents a 3D voxel (cell) in space.

Public Types

using shared_ptr = std::shared_ptr<Voxel>

Pointer types: shared pointer.

using weak_ptr = std::weak_ptr<Voxel>

Weak pointer type.

Public Functions

inline Voxel(const array3Int_t &cornerMin_, const array3Int_t &cornerMax_, const cell_id_t &cellId_)

Constructs a voxel from integer-space corners.

Parameters:

  • cornerMin_ – Minimum voxel corner in internal integer units.

  • cornerMax_ – Maximum voxel corner in internal integer units.

  • cellId_ – Unique cell identifier assigned to the voxel.

bool contains(const point_id_t &pointId_) const

Checks whether a point id is registered in this voxel.

Parameters:

pointId_ – Point identifier tested for membership in this voxel.

Returns:

true if the point id exists in the voxel set.

bool contains(const array3D_t &point_) const

Checks whether coordinates lie inside voxel bounds.

Parameters:

point_ – Query coordinates in internal units.

Returns:

true if the point is inside the voxel AABB.

array3Int_t::pair get_corners() const

Returns voxel integer corners.

Returns:

Pair (minCorner, maxCorner).

array3D_t get_center() const

Returns voxel center.

Returns:

Center coordinates.

fail_t insert(const point_id_t &pointId_)

Inserts a point id into the voxel.

Parameters:

pointId_ – Point identifier inserted into this voxel.

Returns:

Success or failure state.

fail_t remove(const point_id_t &pointId_)

Removes a point id from the voxel.

Parameters:

pointId_ – Point identifier removed from this voxel.

Returns:

Success or failure state.

inline cell_id_t get_id() const

Returns the cell identifier.

Returns:

Cell identifier.

inline point_id_t::set get_points()

Returns all point ids currently stored in the voxel.

Returns:

Copy of the point-id set.

inline void highlight()

Marks the voxel as visible.

inline void unhighlight()

Marks the voxel as not visible.

inline bool is_highlighted() const

Returns whether the voxel is visible.

Returns:

true if the voxel is highlighted.

inline size_t get_point_count() const

Returns the number of points in the voxel.

Returns:

Number of stored point ids.

Public Static Functions

static inline shared_ptr make_shared(const array3Int_t &cornerMin_, const array3Int_t &cornerMax_, const cell_id_t &cellId_)

Creates a shared voxel instance.

Parameters:

  • cornerMin_ – Minimum voxel corner in internal integer units.

  • cornerMax_ – Maximum voxel corner in internal integer units.

  • cellId_ – Unique cell identifier assigned to the voxel.

Returns:

Shared pointer to a new Voxel.

Private Functions

bool __contains(const point_id_t &pointId_) const

Internal point-id containment check without locking.

Parameters:

pointId_ – Point identifier tested for membership in _points.

Returns:

true if the point id exists in points.

Private Members

array3Int_t _cornerMin = {0, 0, 0}

Corners of the cell: Min.

array3Int_t _cornerMax = {0, 0, 0}

Corners of the cell: Max.

point_id_t::set _points

Points contained in the cell.

cell_id_t _cellId

cell id of the voxel

bool _isVisible = {false}

Whether the voxel is visible or not.

mutable std::shared_mutex _mutex

Mutex for thread-safe access.