Tesseract 0.28.4
Loading...
Searching...
No Matches
signed_distance_field_utils.cpp File Reference

Utilities for discretizing and (de)serializing a SignedDistanceField grid. More...

#include <tesseract/common/macros.h>
#include <algorithm>
#include <array>
#include <cmath>
#include <cstdlib>
#include <cstring>
#include <limits>
#include <memory>
#include <stdexcept>
#include <string>
#include <tesseract/common/utils.h>
#include <tesseract/geometry/impl/signed_distance_field_utils.h>
#include <tinyvdb_io.h>
#include <tinyvdb_nanovdb.h>
#include <tinyvdb_sparse_tree.h>
#include <third_party/nanovdb/PNanoVDB.h>

Functions

SignedDistanceField::Ptr tesseract::geometry::createDiscreteSignedDistanceField (const SignedDistanceFunction &sdf, const Eigen::Vector3d &domain_min, const Eigen::Vector3d &domain_max, const Eigen::Vector3i &dimensions, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Discretize a SignedDistanceField by sampling a signed distance function on a dense grid.
SignedDistanceField::Ptr tesseract::geometry::createDiscreteSignedDistanceField (const BatchedSignedDistanceFunction &sdf, const Eigen::Vector3d &domain_min, const Eigen::Vector3d &domain_max, const Eigen::Vector3i &dimensions, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Batched overload — every grid sample position is handed to sdf in one call.
SignedDistanceField::Ptr tesseract::geometry::createSignedDistanceField (const SignedDistanceFunction &sdf, const Eigen::Vector3d &domain_min, const Eigen::Vector3d &domain_max, const Eigen::Vector3i &dimensions, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Create a lazily-evaluated SignedDistanceField backed by a distance function.
SignedDistanceField::Ptr tesseract::geometry::createSignedDistanceField (const BatchedSignedDistanceFunction &sdf, const Eigen::Vector3d &domain_min, const Eigen::Vector3d &domain_max, const Eigen::Vector3i &dimensions, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Batched overload — the sampler receives every grid sample position in one call.
std::vector< std::uint8_t > tesseract::geometry::writeSignedDistanceFieldVDB (const SignedDistanceField &sdf)
 Serialize a field as a standard OpenVDB FloatGrid.
SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldVDB (const std::uint8_t *data, std::size_t size, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Reconstruct a SignedDistanceField from a standard OpenVDB FloatGrid byte buffer.
SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldVDB (const std::vector< std::uint8_t > &data, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Reconstruct a SignedDistanceField from a standard OpenVDB FloatGrid byte vector.
std::vector< std::uint8_t > tesseract::geometry::writeSignedDistanceFieldNVDB (const SignedDistanceField &sdf)
 Serialize a field as a standard NanoVDB FloatGrid file.
SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldNVDB (const std::uint8_t *data, std::size_t size, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Reconstruct a dense SignedDistanceField from a NanoVDB FloatGrid byte buffer.
SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldNVDB (const std::vector< std::uint8_t > &data, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Reconstruct a SignedDistanceField from a NanoVDB FloatGrid byte vector.
std::vector< std::string > tesseract::geometry::getSignedDistanceFieldNVDBGridNames (const std::uint8_t *data, std::size_t size)
 The names of the grids in a NanoVDB file, in file order.
std::vector< std::string > tesseract::geometry::getSignedDistanceFieldNVDBGridNames (const std::vector< std::uint8_t > &data)
 Convenience overload of getSignedDistanceFieldNVDBGridNames for an owning byte vector.
SignedDistanceField::Ptr tesseract::geometry::readSparseSignedDistanceFieldNVDB (const std::uint8_t *data, std::size_t size, double band_clamp, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1), const std::string &grid_name="")
 Read one FloatGrid of a NanoVDB file as a sparse SignedDistanceField, kept in its stored sparse form (see the sparse SignedDistanceField constructor).
SignedDistanceField::Ptr tesseract::geometry::readSparseSignedDistanceFieldNVDB (const std::vector< std::uint8_t > &data, double band_clamp, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1), const std::string &grid_name="")
 Convenience overload of readSparseSignedDistanceFieldNVDB for an owning byte vector.
SignedDistanceField::Ptr tesseract::geometry::readSparseSignedDistanceFieldNVDB (const std::uint8_t *data, std::size_t size, double band_clamp, const Eigen::Vector3d &scale, std::size_t grid_index)
 Read the grid at grid_index (file order) of a NanoVDB file as a sparse field, for files whose grids are not named apart (a multi-level field's file, for one).
SignedDistanceField::Ptr tesseract::geometry::readSparseSignedDistanceFieldNVDB (const std::vector< std::uint8_t > &data, double band_clamp, const Eigen::Vector3d &scale, std::size_t grid_index)
 Convenience overload of the by-index readSparseSignedDistanceFieldNVDB for an owning byte vector.

Detailed Description

Utilities for discretizing and (de)serializing a SignedDistanceField grid.

Author
Joel Kang
Date
June 15, 2026
License
Software License Agreement (Apache License)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Function Documentation

◆ createDiscreteSignedDistanceField()

SignedDistanceField::Ptr tesseract::geometry::createDiscreteSignedDistanceField ( const SignedDistanceFunction & sdf,
const Eigen::Vector3d & domain_min,
const Eigen::Vector3d & domain_max,
const Eigen::Vector3i & dimensions,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Discretize a SignedDistanceField by sampling a signed distance function on a dense grid.

Evaluates sdf at dimensions.x() * dimensions.y() * dimensions.z() points on a regular axis-aligned lattice spanning [domain_min, domain_max] (inclusive of both corners) and stores them as the field's backend-neutral grid. sdf is not kept: queries and the collision backends interpolate the grid, so an expensive function is paid for once, here.

Parameters
sdfSigned distance function (negative inside, positive outside) in the field's local frame
domain_minMinimum corner of the sampled domain
domain_maxMaximum corner of the sampled domain (must exceed domain_min on every axis)
dimensionsNumber of samples along each axis (each must be >= 2)
scaleLocal scaling applied to the field
Returns
A grid-backed SignedDistanceField holding the sampled grid
Exceptions
std::runtime_erroron an invalid domain or dimensions

◆ createSignedDistanceField()

SignedDistanceField::Ptr tesseract::geometry::createSignedDistanceField ( const SignedDistanceFunction & sdf,
const Eigen::Vector3d & domain_min,
const Eigen::Vector3d & domain_max,
const Eigen::Vector3i & dimensions,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Create a lazily-evaluated SignedDistanceField backed by a distance function.

Unlike createDiscreteSignedDistanceField, the grid is not sampled up front: sdf remains the field's source of truth, so queries and each collision backend evaluate it directly (exact, no resampling). The dense grid is materialized only when concrete data is required (serialization or comparison). The field cannot be serialized or compared from multiple threads concurrently until discretized — call SignedDistanceField::discretize up front if needed. sdf must be thread-safe.

Parameters
dimensionsNumber of samples along each axis to discretize when materialized (each must be >= 2)

◆ writeSignedDistanceFieldVDB()

std::vector< std::uint8_t > tesseract::geometry::writeSignedDistanceFieldVDB ( const SignedDistanceField & sdf)

Serialize a field as a standard OpenVDB FloatGrid.

The grid transform maps lattice index (0, 0, 0) to the field domain minimum and uses the field sample spacing as its uniform voxel size. The local scale is not stored; it is carried alongside the field (e.g. as a URDF attribute) and supplied on load.

Exceptions
std::runtime_errorif the field has non-uniform voxel spacing or cannot be encoded, or is sparse (a sparse field has no single dense grid; use writeSignedDistanceFieldNVDB).

◆ readSignedDistanceFieldVDB() [1/2]

SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldVDB ( const std::uint8_t * data,
std::size_t size,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Reconstruct a SignedDistanceField from a standard OpenVDB FloatGrid byte buffer.

Exactly one FloatGrid with an axis-aligned, uniformly scaled transform is supported. Its active voxel bounding box defines the finite Tesseract field domain; inactive voxels within that domain use the grid background value.

Parameters
dataPointer to the serialized grid blob
sizeNumber of bytes in data
scaleLocal scaling applied to the field
Exceptions
std::runtime_errorif the VDB is malformed or uses an unsupported grid or transform

◆ readSignedDistanceFieldVDB() [2/2]

SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldVDB ( const std::vector< std::uint8_t > & data,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Reconstruct a SignedDistanceField from a standard OpenVDB FloatGrid byte vector.

Convenience overload for an owning byte vector. Use the pointer-and-size overload to read from other contiguous storage without a copy.

◆ writeSignedDistanceFieldNVDB()

std::vector< std::uint8_t > tesseract::geometry::writeSignedDistanceFieldNVDB ( const SignedDistanceField & sdf)

Serialize a field as a standard NanoVDB FloatGrid file.

The field's local scale is not stored and must be supplied separately when loading. A sparse field is written as its FloatGrid, as stored, and a multi-level field as its levels' grids in order. Band clamps are not stored either: pass them to readSparseSignedDistanceFieldNVDB to read the grids back as equal sparse fields.

Exceptions
std::runtime_errorif the field cannot be represented as a uniform FloatGrid.

◆ readSignedDistanceFieldNVDB() [1/2]

SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldNVDB ( const std::uint8_t * data,
std::size_t size,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Reconstruct a dense SignedDistanceField from a NanoVDB FloatGrid byte buffer.

Exactly one FloatGrid with an axis-aligned, uniformly scaled transform is supported, and its active bounds are read into a dense grid. To keep a file sparse, use readSparseSignedDistanceFieldNVDB.

Parameters
dataPointer to the serialized NanoVDB file
sizeNumber of bytes in data
scaleLocal scaling applied to the field
Exceptions
std::runtime_errorif the NanoVDB file is malformed or uses an unsupported grid or transform

◆ readSignedDistanceFieldNVDB() [2/2]

SignedDistanceField::Ptr tesseract::geometry::readSignedDistanceFieldNVDB ( const std::vector< std::uint8_t > & data,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Reconstruct a SignedDistanceField from a NanoVDB FloatGrid byte vector.

Convenience overload for an owning byte vector. Use the pointer-and-size overload to read from other contiguous storage without a copy.

◆ getSignedDistanceFieldNVDBGridNames()

std::vector< std::string > tesseract::geometry::getSignedDistanceFieldNVDBGridNames ( const std::uint8_t * data,
std::size_t size )

The names of the grids in a NanoVDB file, in file order.

A file can hold several grids: level sets of different objects, or anything else. Read one as a field with readSparseSignedDistanceFieldNVDB; how several relate is the caller's to say.

Exceptions
std::runtime_errorif the NanoVDB file is malformed

◆ readSparseSignedDistanceFieldNVDB() [1/2]

SignedDistanceField::Ptr tesseract::geometry::readSparseSignedDistanceFieldNVDB ( const std::uint8_t * data,
std::size_t size,
double band_clamp,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1),
const std::string & grid_name = "" )

Read one FloatGrid of a NanoVDB file as a sparse SignedDistanceField, kept in its stored sparse form (see the sparse SignedDistanceField constructor).

Parameters
dataPointer to the serialized NanoVDB file
sizeNumber of bytes in data
band_clampThe grid's band clamp, in grid units (0: the values never saturate)
scaleLocal scaling applied to the field
grid_nameThe grid to read; may be empty only when the file holds exactly one grid
Exceptions
std::runtime_errorif the file is malformed, grid_name is empty and the file holds more than one grid, no grid has that name (or more than one does), or the grid is not a valid sparse field

◆ readSparseSignedDistanceFieldNVDB() [2/2]

SignedDistanceField::Ptr tesseract::geometry::readSparseSignedDistanceFieldNVDB ( const std::uint8_t * data,
std::size_t size,
double band_clamp,
const Eigen::Vector3d & scale,
std::size_t grid_index )

Read the grid at grid_index (file order) of a NanoVDB file as a sparse field, for files whose grids are not named apart (a multi-level field's file, for one).

Exceptions
std::runtime_errorif the file is malformed, has no grid at grid_index, or the grid is not a valid sparse field