erl_geometry

erl_geometry is a C++ library for geometry processing.

Available Functionalities

• Axis Aligned Bounding Box (Aabb): Axis Aligned Bounding Box ( Aabb), derived from Eigen::AlignedBox.
• KdTree: create kd-tree from Eigen matrix.
• Occupancy Maps
  • Occupancy Map: base class for occupancy mapping.
  • LogOdd: implementation of log odd.
  • Log Odd Map: occupancy grid map based on log odd.
  • Log Odd Map 2D: 2D occupancy grid map based on log odd.
  • Bayesian Hilbert Map: probabilistic occupancy mapping using Hilbert space embeddings.
  • Bayesian Hilbert Map Torch: PyTorch-based implementation of Bayesian Hilbert Map.
• Occupancy Quadtree: developed based on Octomap
  • Occupancy Quadtree: implementation of occupancy quadtree.
  • Colored Occupancy Quadtree: occupancy quadtree with color information.
  • PyObject Occupancy Quadtree: occupancy quadtree that supports tagging Python object to quadtree nodes.
  • Abstract Quadtree: abstract class for quadtree.
  • Quadtree Implementation: implementation of quadtree, unlike incremental quadtree, this one always inserts nodes to the deepest level.
  • Abstract Occupancy Quadtree: abstract class for occupancy quadtree.
  • QuadtreeKey: key for quadtree node to achieve fast lookup.
  • Abstract Quadtree Node: abstract class for quadtree node.
  • Quadtree Data Node: template implementation of quadtree node with data type T.
  • Occupancy Quadtree Node: implementation of quadtree node with occupancy data.
  • Colored Occupancy Quadtree Node: occupancy quadtree node with color data.
  • PyObject Occupancy Quadtree Node: occupancy quadtree node that supports tagging Python object.
  • Abstract Quadtree Drawer: abstract class for quadtree drawer.
  • Occupancy Quadtree Drawer: visualization of occupancy quadtree.
  • Occupancy ND Tree Batch Ray Caster: batch ray casting for N-dimensional occupancy trees.
• Occupancy Octree: developed based on Octomap
  • Occupancy Octree: implementation of occupancy octree.
  • Colored Occupancy Octree: occupancy octree with color information.
  • PyObject Occupancy Octree: occupancy octree that supports tagging Python object to octree nodes.
  • Abstract Octree: abstract class for octree.
  • Octree Implementation: implementation of octree, unlike incremental quadtree, this one always inserts nodes to the deepest level.
  • Abstract Occupancy Octree: abstract class for occupancy octree.
  • OctreeKey: key for octree node to achieve fast lookup.
  • Abstract Octree Node: abstract class for octree node.
  • Octree Data Node: template implementation of octree node with data type T.
  • Occupancy Octree Node: implementation of octree node with occupancy data.
  • Colored Occupancy Octree Node: occupancy octree node with color data.
  • PyObject Occupancy Octree Node: occupancy octree node that supports tagging Python object.
  • Abstract Octree Drawer: abstract class for octree drawer.
  • Occupancy Octree Drawer: visualization of occupancy octree.
• Collision Detection
  • Winding Number: check if a point is in a polygon.
• Geometric Primitives
  • Primitives 2D: 2D geometric primitives including lines, segments, rays, rectangles, and ellipses.
  • Primitives 3D: 3D geometric primitives including planes, triangles, boxes, and ellipsoids.
  • Intersection: compute intersections between geometric primitives.
• Signed Distance Functions (SDF)
  • Mesh SDF: compute signed distance function from triangle mesh.
  • SDF Utilities: utility functions for SDF computation.
• Surface Extraction
  • Marching Squares: extract surface from 2D scalar field.
  • Marching Cubes: extract surface from 3D scalar field using marching cubes algorithm.
• Polygon Triangulation
  • EarCut: triangulate a polygon even with holes.
  • Convert Polygon to Triangle Mesh: triangulate a polygon.
• Ray Casting
  • Bresenham 2D: 2D ray tracing.
  • Ray Marching: 2D ray marching with SDF.
  • Also available in Quadtree and Octree.
• Camera Models and Sensors
  • Camera Intrinsic: camera intrinsic parameters and projection models.
  • Camera Base 3D: base class for 3D camera models.
  • Range Sensor 3D: 3D range sensor simulation.
  • Range Sensor Frame 3D: data structure for 3D range sensor measurements.
• 2D Point Cloud Processing
  • Surface 2D: data structure to store 2D surface consisting of points and normals.
  • Space 2D: algorithm to compute SDF, SDDF and normals.
  • LiDAR 2D: generate 2D LiDAR scan with a given space.
  • LiDAR Frame 2D: data structure to store 2D LiDAR scan and sample from it.
• 3D Point Cloud Processing
  • LiDAR 3D: generate 3D LiDAR scan with a given scene.
  • LiDAR Frame 3D: data structure to store 3D LiDAR scan and sample from it.
  • Depth Camera 3D: generate 3D depth image with a given scene.
  • Depth Frame 3D: data structure to store a depth image and sample from it.
  • RGBD Camera 3D: generate 3D RGBD image with a given scene.
  • RGBD Frame 3D: data structure to store a RGBD image and sample from it.
• Visualization and Rendering
  • Open3D Helper: helper functions for Open3D integration.
  • Open3D Visualizer Wrapper: wrapper for Open3D visualization.
• Motion and Trajectory
  • Trajectory: data structures and utilities for 2D/3D trajectories and SE(2)/SE(3) poses.
• Datasets
  • HouseExpoMap: load 2D map or 3D mesh from HouseExpo dataset.
  • HouseExpoMapLidar2D: generate 2D LiDAR scan sequence from a HouseExpo map.
  • GazeboRoom2D: generate 2D LiDAR scan sequence from a Gazebo room.
  • CityStreetMaps: load 2D map from CityStreet dataset.
  • UcsdFah2D: a real 2D LiDAR scan sequence collected from FAH building in UCSD.
  • CowAndLady: a real 3D RGBD sequence provided by ETH Zurich ASL.
  • NewerCollege: a real 3D LiDAR dataset by Oxford Robotics Institute.
• Others
  • Compute Intersections: utility functions for geometric computations.
  • Euler Angle: Euler angle conversions and utilities.
  • Compute ConvexHull: convex hull computation algorithms.
  • Hidden Point Removal: remove hidden points from 3D point clouds.
  • ND Tree Setting: configuration settings for N-dimensional trees.
  • Occupancy ND Tree Setting: configuration settings for occupancy N-dimensional trees.

Getting Started

Prerequisites

• CMake 3.24 or higher
• A C++17 compatible compiler

Create Workspace

mkdir -p <your_workspace>/src && \
vcs import --input https://raw.githubusercontent.com/ExistentialRobotics/erl_geometry/refs/heads/main/erl_geometry.repos <your_workspace>/src

Dependencies

• erl_cmake_tools
• erl_common
• erl_covariance

# Ubuntu 20.04
wget -qO - https://raw.githubusercontent.com/ExistentialRobotics/erl_common/refs/heads/main/scripts/setup_ubuntu_20.04.bash | bash
wget -qO - https://raw.githubusercontent.com/ExistentialRobotics/erl_geometry/refs/heads/main/scripts/setup_ubuntu_20.04.bash | bash
# Ubuntu 22.04, 24.04
wget -qO - https://raw.githubusercontent.com/ExistentialRobotics/erl_common/refs/heads/main/scripts/setup_ubuntu_22.04_24.04.bash | bash
wget -qO - https://raw.githubusercontent.com/ExistentialRobotics/erl_geometry/refs/heads/main/scripts/setup_ubuntu_22.04_24.04.bash | bash

Docker Option

The easiest way to get started is to use the provided Docker files, which contains all dependencies.

Use as a standard CMake package

cd <your_workspace>
touch CMakeLists.txt

Add the following lines to your CMakeLists.txt:

cmake_minimum_required(VERSION 3.24)
project(<your_project_name>)
add_subdirectory(src/erl_cmake_tools)
add_subdirectory(src/erl_common)
add_subdirectory(src/erl_covariance)
add_subdirectory(src/erl_geometry)

Then run the following commands:

mkdir -p build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j`nproc`

Use as a ROS Package

cd <your_workspace>
source /opt/ros/<distro>/setup.bash
# for ROS1
catkin build erl_geometry
source devel/setup.bash
# for ROS2
colcon build --packages-up-to erl_geometry
source install/setup.bash

See also 🚪erl_geometry_ros for additional ROS tools.

Install As Python Package

• Make sure you have installed all dependencies.
• Make sure you have the correct Python environment activated, pipenv is recommended.

cd <your_workspace>
for package in erl_cmake_tools erl_common erl_covariance erl_geometry; do
    cd src/$package
    pip install . --verbose --no-build-isolation
    cd ../..
done