signed_distance_field_utils.cpp File Reference

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

#include <tesseract/common/macros.h>
#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>

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 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.

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. Each collision backend transcodes this grid into its own native form when the geometry is added to a contact manager.

Parameters

sdf	Signed distance function (negative inside, positive outside) in the field's local frame
domain_min	Minimum corner of the sampled domain
domain_max	Maximum corner of the sampled domain (must exceed domain_min on every axis)
dimensions	Number of samples along each axis (each must be >= 2)
scale	Local scaling applied to the field

Returns

A SignedDistanceField holding the sampled grid

Exceptions

std::runtime_error

on 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

dimensions

Number 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_error

if the field has non-uniform voxel spacing or cannot be encoded.

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

data	Pointer to the serialized grid blob
size	Number of bytes in data
scale	Local scaling applied to the field

Exceptions

std::runtime_error

if 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.

Exceptions

std::runtime_error

if 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 SignedDistanceField from a NanoVDB FloatGrid byte buffer.

Exactly one FloatGrid with an axis-aligned, uniformly scaled transform is supported.

Parameters

data	Pointer to the serialized NanoVDB file
size	Number of bytes in data
scale	Local scaling applied to the field

Exceptions

std::runtime_error

if 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.