csiro-robotics/ohm

An efficient, extensible occupancy map supporting probabilistic occupancy, normal distribution transforms in CPU and GPU.

Occupancy Homogeneous Map

The ohm library is a probabilistic voxel occupancy map supporting fast GPU based population and operations and normal distribution transform semantics. The ohm library defines an occupancy map consisting of regions or chunks of homogeneous voxels, arranged in contiguous memory blocks. This homogeneous voxel layout, rather than an octree layout, supports fast GPU based map population using OpenCL and CUDA.

Building

Prerequisites and Requirements

The ohm library supports both OpenCL and CUDA GPU processing. OpenCL development focuses on GCC and Visual Studio running on an Intel OpenCL GPU device. AMD and NVIDIA GPUs have been tested and should also function. The CUDA implementation has been built for compute 5.0 and 6.0. Other architectures may work, but must be specifically tested.

Building ohm requires:

• C++14 compatible compiler such as:
  • GCC 5.7
  • Visual Studio 15 2017
  • APPLE LLVM 9.1
• For OpenCL
  • An OpenCL 1.2 or 2.0 SDK. 1.2 must be used if running on NVIDIA hardware.
  • OpenCL 1.2 runtime. OpenCL 2.x also supported (command line selectable)
• For CUDA
  • CUDA 10

The following 3rd-party libraries are required to build ohm:

• Either an OpenCL SDK or the CUDA SDK
• ZLib for serialisation compression.
• CMake for project set up
• OpenGL Mathematics (GLM) for 3D data types.

Googletest is also used when building unit tests, however, this is downloaded as part of the build.

Additional, the following 3rd-party libraries may optionally be used:

Library	Feature Usage
3rd Eye Scene	For debug visualisation of map generation.
Doxygen	For generation of API documentation.
Eigen3	Used in small amounts in some tests and as a faster option for some geometry operations
Intel Threading Building Blocks	Multi-threaded CPU operations.
GLEW	For HeightmapImage in ohmheightmaputil
GLFW	For HeightmapImage in ohmheightmaputil
libpng	To convert heightmap to image using utils/ohmhm2img
PDAL	Load point various point cloud formats for ohmpop.

While efforts are made to ensure components remain optional, certain configurations may be incompatible.

Ubuntu apt Packages

On Ubuntu, the required packages may be installed using the following command:

sudo apt install cmake zlib1g-dev libglm-dev googletest

Setup of OpenCL requires mode detailed instructions (link).

For CUDA setup instructions, visit NVIDIA CUDA Zone.

Additional, recommended packages can be installed using:

sudo apt install libtbb-dev libpdal-dev doxygen

Optional packages for heightmap generation and image conversion:

sudo apt install libglew-dev libglfw3-dev libpng-dev libeigen3-dev

Build Instructions

1. Download source code.
2. Install pre-requisites.
3. Configure the project.
   • Create a build subdirectory and change into this subdirectory.
   • Execute cmake ..
     • For Visual Studio configuration, include the option -G Visual Studio 15 2017 Win64
   • Build the project
     • For Visual Studio, open the solution file and build.
     • For make based platforms, run make -j

Building with vcpkg

Ohm supports building with in vcpkg manifest mode. To build using vcpkg, first follow the vcpkg install instructions then build with the vcpkg toolchain enabled.

Building in manifest mode obviates the need to download the dependencies, except for the CUDA SDK on Windows. To build with vcpkg, adjust the cmake command line to enable vcpkg manifest mode when configuring the project;

# Run from the source directory
# Note we must run CMake from the source directory and use -B and -S to specify
# the build and source directories respectively. This allows vcpkg to find the
# vcpkg.json manifest file.
mkdir build
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=<vcpkg_path>/scripts/buildsystem/vcpkg.cmake -DVCPKG_MANIFEST_FEATURES=<features>
cmake --build build --target all --

It's recommended to add -G Ninja as this builds much faster than other build systems.

Or for a multi config generator such as Visual Studio or Ninja Multi-Config;

mkdir build
cmake -B build -S . -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=<vcpkg_path>/scripts/buildsystem/vcpkg.cmake -DVCPKG_MANIFEST_FEATURES=<features>
cmake --build build --config Release --target all --

The VCPKG_MANIFEST_FEATURES specifies the features to enable for ohm, where they differ from the default features. This is a semicolon separated list of features choosing from the items listed below. It is generally expected that either cuda or opencl are listed, or both.

Feature	Description
cuda	Build with CUDA GPU acceleration.
eigen *	Enable Eigen support (private)
heightmap *	Enable the heightmap library
heightmap-image	Enable heightmap to image conversion
opencl	Enable OpenCL acceleration.
pdal	Enable PDAL point cloud loader. **
threads *	Enable TBB threading (limited).
test	Build the ohm unit tests.

* This feature is enabled by default. ** Warning: enabling PDAL supports takes a long time for initial configuration while it builds the GDAL dependency. This can take on the order of several hours. Also note it may be necessary to set the LD_LIBRARY_PATH to include the directly where the pdal shared libraries are placed by vcpkg.

Notable Known Issues

• OpenCL compatibility with certain devices may vary.
• OpenCL performance on various devices may vary especially with memory transfer rates.
• Using the OpenCL 2.x SDK and selecting an NVIDIA GPU will result in runtime crashes.
• When installing, OHM_EMBED_GPU_CODE must be defined in order to run ohmocl; otherwise OpenCL source is not found.
• When building from VSCode on Windows and using the Ninja generation, nvcc may fail reporting "command too long". This appears to be caused by a long path name. Changing to an "unspecified" CMake Kit or launching VSCode with a shorter PATH variable may help.

Resolving OpenCL SDK With Multiple Options

There are some pitfalls in trying to resolve an appropriate OpenCL SDK when multiple SDK options are installed. Most notably selecting between the Intel SDK over the NVIDIA SDK can be problematic. The best way to ensure the correct option is selected is to ensure the desired SDK prefix path is set in the PATH environment variable as the before other SDK paths. The prefix path, is essentially the path containing the include and lib directories.

While this can be changed by explicitly changing OpenCL_INCLUDE_DIR and OpenCL_LIBRARY in the CMake cache (using ccmake or cmake-gui) this can still have issues with selecting a particular API version. This is because the available API versions are determined when the OpenCL header is first found and will not be updated if the paths are explicitly changed. To combat this, edit the CMakeCache.txt file and remove all OPENCL_VERSION_X_X entries.

Further documentation

• OHM Glossary
• Occupancy map usage
• OHM utilities
• GPU algorithm overview
• GPU technical details and performance tips
• Built in voxel layers

Citation

Please use the following citation if you use OHM in your research.

@ARTICLE{9849048,
  author={Stepanas, Kazys and Williams, Jason and Hernández, Emili and Ruetz, Fabio and Hines, Thomas},
  journal={IEEE Robotics and Automation Letters}, 
  title={OHM: GPU Based Occupancy Map Generation}, 
  year={2022},
  volume={},
  number={},
  pages={1-8},
  doi={10.1109/LRA.2022.3196145}}