VDBFusion: Flexible and Efficient TSDF Integration

This is a small utility library that implements the VDBFusion algorithm, similar to TSDF-based reconstruction pipelines but using a different data-structure (VDB).

Installation

Take a seat and relax, you only need to:

pip install vdbfusion

If you plan to use our C++ API then you should build this project from source. More details in the Installation instructions.

The ROS-1 C++ wrapper for this library is available at https://github.com/PRBonn/vdbfusion_ros

Usage

The code shown below is not intended to be copy pasted but rather be a spiritual guide for developers. If you really want to give this library a try you should consider checking the standalone Python, Notebooks, and C++ examples.

Data loading

NOTE: This step is not mandatory. Our API only expects points and poses but this is the easiest way to deal with 3D data.

Python

C++

class Dataset:
    def __init__(self, *args, **kwargs):
        # Initialize your dataset here ..

    def __len__(self) -> int:
        return len(self.n_scans)

    def __getitem__(self, idx: int):
        # Returns a PointCloud(np.array(N, 3))
        # and sensor origin(Eigen::Vector3d)
        # in the global coordinate frame.
        return points, origin

class Dataset {
  // Initialize your dataset here ..
  Dataset(...);

  // Return length of the dataset
  std::size_t size() const { return n_scans_; }

  // Returns a Cloud(std::vector<Eigen::Vector3d>)
  // and the sensor origin(Eigen::Vector3d) in the
  // global coordinate frame.
  std::tuple<Cloud, Point> operator[](int idx) const;
};

TSDF Fusion pipeline

Python

C++

import vdbfusion

vdb_volume = vdbfusion.VDBVolume(voxel_size,
                                 sdf_trunc,
                                 space_carving
dataset = Dataset(...)

for scan, origin in dataset:
    vdb_volume.integrate(scan, origin)

#include "vdbfusion/VDBVolume.h"

vdb_fusion::VDBVolume vdb_volume(voxel_size,
                                 sdf_trunc,
                                 space_carving);
const auto dataset = Dataset(...);

for (const auto& [scan, origin] : iterable(dataset)) {
  vdb_volume.Integrate(scan, origin);
}

Visualization

For visualization you can use any 3D library you like. For this example we are going to be using Open3D. If you are using the Python API make sure to pip install open3d before trying this snippet.

Python

C++

import open3d as o3d

# Extract triangle mesh (numpy arrays)
vert, tri = vdb_volume.extract_triangle_mesh()

# Visualize the results
mesh = o3d.geometry.TriangleMesh(
    o3d.utility.Vector3dVector(vert),
    o3d.utility.Vector3iVector(tri),
)

mesh.compute_vertex_normals()
o3d.visualization.draw_geometries([mesh])

#include <open3d/Open3D.h>

// Extract triangle mesh (Eigen).
auto [verts, tris] = vdb_volume.ExtractTriangleMesh();

// Visualize the results
auto mesh = o3d::geometry::TriangleMesh(
    verts,
    tris,
)

mesh.ComputeVertexNormals()
o3d::visualization::DrawGeometries({&mesh})

LICENSE

The LICENSE can be found at the root of this repository. It only applies to the code of VDBFusion but not to its 3rdparty dependencies. Please make sure to check the licenses in there before using any form of this code.

Credits

I would like to thank the Open3D and OpenVDB authors and contributors for making their implementations open source which inspired, helped and guided the implementation of the VDBFusion library.

Citation

If you use this library for any academic work, please cite the original paper.

@article{vizzo2022sensors,
  author         = {Vizzo, Ignacio and Guadagnino, Tiziano and Behley, Jens and Stachniss, Cyrill},
  title          = {VDBFusion: Flexible and Efficient TSDF Integration of Range Sensor Data},
  journal        = {Sensors},
  volume         = {22},
  year           = {2022},
  number         = {3},
  article-number = {1296},
  url            = {https://www.mdpi.com/1424-8220/22/3/1296},
  issn           = {1424-8220},
  doi            = {10.3390/s22031296}
}