Tesseract 0.28.4
Loading...
Searching...
No Matches
tesseract::geometry::SignedDistanceField Class Reference

A volumetric signed distance field geometry. More...

#include <signed_distance_field.h>

Inheritance diagram for tesseract::geometry::SignedDistanceField:

Public Types

using Ptr = std::shared_ptr<SignedDistanceField>
using ConstPtr = std::shared_ptr<const SignedDistanceField>
Public Types inherited from tesseract::geometry::Geometry
using Ptr = std::shared_ptr<Geometry>
using ConstPtr = std::shared_ptr<const Geometry>

Public Member Functions

 SignedDistanceField (const Eigen::AlignedBox3d &domain, const Eigen::Vector3i &dimensions, std::vector< double > distances, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Construct from a dense grid of signed distances sampled on a regular lattice.
 SignedDistanceField (const Eigen::AlignedBox3d &domain, const Eigen::Vector3i &dimensions, BatchedSignedDistanceFunction sampler, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Construct a lazily-evaluated field backed by a distance function.
 SignedDistanceField (std::vector< std::uint8_t > nvdb, double band_clamp, const Eigen::Vector3d &scale=Eigen::Vector3d(1, 1, 1))
 Construct a sparse field from one NanoVDB grid, kept in its stored sparse form.
 SignedDistanceField (std::vector< SignedDistanceField::ConstPtr > levels)
 Stack sparse fields of one surface as levels by resolution: a fallback, not a union.
const Eigen::AlignedBox3d & getDomain () const
 Get the axis-aligned domain spanned by the sample grid (local frame).
const Eigen::Vector3i & getDimensions () const
 Get the number of samples along each axis.
const std::vector< double > & getDistances () const
 Get the sampled signed distances (row-major: index = i + nx*(j + ny*k)).
const Eigen::Vector3d & getScale () const
 Get the local scaling applied to the field.
double getDistance (const Eigen::Vector3d &point) const
 Get the signed distance at a point in the field's local frame.
Eigen::Vector3d getGradient (const Eigen::Vector3d &point) const
 Get the gradient of the signed distance at a point in the field's local frame.
double getDistanceAndGradient (const Eigen::Vector3d &point, Eigen::Vector3d &gradient) const
 Distance and gradient in one call: the same answers as getDistance and getGradient, with one lookup instead of two in a sparse field.
bool isDiscretized () const
 Whether the dense grid has been materialized (true for grid-backed and discretized fields).
bool isSparse () const
 Whether this is a sparse field: one NanoVDB grid, or levels of them (getLevels).
void setInterpolation (SignedDistanceFieldInterpolation interpolation)
 Choose how getDistance and getGradient read between samples (grid-backed and sparse fields; a function-backed field is always evaluated exactly). Sets both; follow with setGradientInterpolation to read the direction differently.
SignedDistanceFieldInterpolation getInterpolation () const
 How the distance is read (setInterpolation).
void setGradientInterpolation (SignedDistanceFieldInterpolation interpolation)
 Read the gradient with a different method from the distance.
SignedDistanceFieldInterpolation getGradientInterpolation () const
 How the gradient is read (defaults to the distance's method).
const std::vector< std::uint8_t > & getNVDB () const
 A sparse field's grid, as its bare, uncompressed grid buffer (what the field reads in place); empty for a dense, function-backed or multi-level field (a multi-level field's grids are its levels').
double getBandClamp () const
 A sparse field's band clamp (see the sparse constructor); 0 for a dense, function-backed or multi-level field.
const std::vector< SignedDistanceField::ConstPtr > & getLevels () const
 A multi-level field's levels, finest first (see the multi-level constructor); empty otherwise.
void discretize () const
 Materialize the dense sample grid from the sampler (no-op if already discretized or grid-backed).
Geometry::Ptr clone () const override final
 Create a copy of this shape.
bool operator== (const SignedDistanceField &rhs) const
bool operator!= (const SignedDistanceField &rhs) const
Public Member Functions inherited from tesseract::geometry::Geometry
 Geometry (GeometryType type=GeometryType::UNINITIALIZED)
 Geometry (const Geometry &)=default
Geometry & operator= (const Geometry &)=default
 Geometry (Geometry &&)=default
Geometry & operator= (Geometry &&)=default
GeometryType getType () const
 Get the geometry type.
void setUUID (const boost::uuids::uuid &uuid)
 Set the geometry UUID.
const boost::uuids::uuid & getUUID () const
 Get the geometry UUID.
bool operator== (const Geometry &rhs) const
bool operator!= (const Geometry &rhs) const

Friends

template<class Archive>
friend void::tesseract::geometry::serialize (Archive &ar, SignedDistanceField &obj)

Detailed Description

A volumetric signed distance field geometry.

Stores the field in a backend-neutral form: the signed distance to a surface (negative inside) sampled on a regular axis-aligned grid over a local-frame domain. This is the canonical, engine-agnostic representation; collision backends query it in place through getDistance and getGradient rather than copying it into a native form. Hold a distance function with createSignedDistanceField (discretized on demand), sample it onto a grid up front with createDiscreteSignedDistanceField, construct it directly from sampled data, or load a standard OpenVDB field with readSignedDistanceFieldVDB.

Note
A function-backed field calls its function at every collision query. For an expensive function (e.g. distance to a mesh), sample it up front with createDiscreteSignedDistanceField.
This is the signed-distance-field geometry; use it when the field is your native representation (sensor-fused / analytic) or you need volumetric discrete collision.
Distinct from the Gazebo "SDF" Simulation Description Format.

A field can instead be SPARSE: one NanoVDB grid kept in its stored form (see the sparse constructor). Memory then follows the surface rather than a box around it, and no backend resamples it: queries read the grid directly through getDistance and getGradient. A sparse field has no dense grid, so getDistances throws.

Note
The Bullet and FCL discrete collision backends consume this geometry through the shared implicit collision solver. It is concave, so it is not supported by continuous/cast managers.

Constructor & Destructor Documentation

◆ SignedDistanceField() [1/4]

tesseract::geometry::SignedDistanceField::SignedDistanceField ( const Eigen::AlignedBox3d & domain,
const Eigen::Vector3i & dimensions,
std::vector< double > distances,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Construct from a dense grid of signed distances sampled on a regular lattice.

Parameters
domainThe axis-aligned domain (local frame) spanned by the sample grid
dimensionsThe number of samples along each axis (>= 2 on every axis)
distancesThe sampled signed distances, row-major: index = i + nx*(j + ny*k), with size == dimensions.prod(). Sample (i,j,k) sits at domain.min() + (i,j,k)/(dimensions-1) * (domain.max() - domain.min())
scaleFinite, strictly positive local scaling applied to the field

◆ SignedDistanceField() [2/4]

tesseract::geometry::SignedDistanceField::SignedDistanceField ( const Eigen::AlignedBox3d & domain,
const Eigen::Vector3i & dimensions,
BatchedSignedDistanceFunction sampler,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Construct a lazily-evaluated field backed by a distance function.

No grid is sampled up front: sampler is the field's source of truth, so queries and each collision backend evaluate it directly (exact, no resampling). The dense grid is materialized (via discretize) only when concrete data is required — serialization or equality comparison.

Note
A lazy field cannot be serialized or compared until discretized. discretize is invoked automatically at those boundaries; call it yourself to pin the snapshot at a defined time or to run a costly/thread-unsafe sampler on your own thread. sampler must be thread-safe.
Parameters
domainThe axis-aligned domain (local frame) to sample over when discretizing
dimensionsThe number of samples along each axis to discretize (>= 2 on every axis)
samplerThe batched signed distance function (negative inside) in the field's local frame
scaleFinite, strictly positive local scaling applied to the field

◆ SignedDistanceField() [3/4]

tesseract::geometry::SignedDistanceField::SignedDistanceField ( std::vector< std::uint8_t > nvdb,
double band_clamp,
const Eigen::Vector3d & scale = Eigen::Vector3d(1, 1, 1) )

Construct a sparse field from one NanoVDB grid, kept in its stored sparse form.

A query at a point reads the voxels around it. What an inactive voxel holds depends on the grid's class. In a level set (NanoVDB grid class LevelSet) inactive voxels and tiles hold the background, positive outside and negative inside, so they are read like active ones. In any other grid an inactive voxel holds no distance, so the grid answers only where every voxel the read uses is active (eight for trilinear).

Where the grid cannot answer, and wherever it answers at or past band_clamp outside the surface, it knows only that the surface is at least that far away: the distance is +infinity, with a zero gradient. The field has no answer there; collision checks measure from where it does, and another geometry on the same link, or on another link, still answers. A read at or past the clamp inside the surface is returned as read: a contact, at least that deep.

The domain is the grid's active voxel bounds. Values are read with the field's interpolation (trilinear unless setInterpolation says otherwise), and getGradient returns the interpolant's own gradient.

Parameters
nvdbOne FloatGrid with an axis-aligned, uniformly scaled transform: a NanoVDB file holding exactly that grid, as written by NanoVDB / fVDB (any codec the reader supports), or the bare grid buffer. Voxel values are signed distances in the grid's own units, negative inside. To use one grid of a file holding several, see readSparseSignedDistanceFieldNVDB.
band_clampThe distance at which the grid's values saturate (a narrow band's clamp), in grid units; for a level set usually its background. 0 means the values never saturate.
scaleFinite, strictly positive local scaling applied to the field (e.g. 1e-3 for a grid stored in millimetres and used in metres)
Exceptions
std::runtime_errorif nvdb is not a single uniform, axis-aligned NanoVDB FloatGrid of the supported major version, is a fog volume, has nodes outside its buffer, or has no active voxels, or if band_clamp is negative or not finite

◆ SignedDistanceField() [4/4]

tesseract::geometry::SignedDistanceField::SignedDistanceField ( std::vector< SignedDistanceField::ConstPtr > levels)
explicit

Stack sparse fields of one surface as levels by resolution: a fallback, not a union.

The levels are ordered finest first: level 0 is the finest, as in OpenVDB's tools::MultiResGrid. A query at a point asks each level in turn and the first that can answer does. A level other than the last also declines a read at or past its band clamp, inside or outside the surface, which says only "at least this far", so a coarser level with real range answers instead. The last level answers as it would alone (see the sparse constructor). Typical use: a fine grid cropped around a region of interest over a coarse grid of the whole object, so accuracy is paid for only where it is needed.

The domain is the union of the levels' domains, and the field reads every level with its own interpolation settings (setInterpolation), not the levels'.

Warning
Every level must describe the same surface, in the same frame, at a different resolution. The field answers from the first level that can, not from the nearest surface across levels, so a level holding a different object would be hidden wherever an earlier level has data. Give separate objects separate fields; several fields on a link combine as any geometries do.
Parameters
levelsSparse single-grid fields (see the sparse constructor), finest first, with equal scales
Exceptions
std::runtime_errorif levels is empty, a level is null, not a sparse single-grid field, or has a different scale from the first, or a level has a smaller voxel size than the level before it

Member Function Documentation

◆ getDistances()

const std::vector< double > & tesseract::geometry::SignedDistanceField::getDistances ( ) const

Get the sampled signed distances (row-major: index = i + nx*(j + ny*k)).

Note
Triggers discretize on a lazy field (materializes the grid from its sampler).
Exceptions
std::runtime_erroron a sparse field, which has no dense grid

◆ getDistance()

double tesseract::geometry::SignedDistanceField::getDistance ( const Eigen::Vector3d & point) const

Get the signed distance at a point in the field's local frame.

A function-backed field evaluates its sampler directly (exact); a grid-backed field interpolates the samples (see setInterpolation), with the point clamped to the domain. A sparse field answers from its grid (see the sparse constructor), and +infinity where the grid knows only that the surface is at least its band clamp away.

◆ getGradient()

Eigen::Vector3d tesseract::geometry::SignedDistanceField::getGradient ( const Eigen::Vector3d & point) const

Get the gradient of the signed distance at a point in the field's local frame.

Grid-backed and sparse fields return the exact gradient of their interpolant (see setInterpolation); a function-backed field takes central differences of its sampler. Not normalized. Zero where a sparse field has no data. The local scale does not change the direction.

◆ setInterpolation()

void tesseract::geometry::SignedDistanceField::setInterpolation ( SignedDistanceFieldInterpolation interpolation)

Choose how getDistance and getGradient read between samples (grid-backed and sparse fields; a function-backed field is always evaluated exactly). Sets both; follow with setGradientInterpolation to read the direction differently.

Near the edge of a sparse grid's active voxels, a wider stencil (tricubic) needs more active neighbours, so it answers in a slightly smaller region.

◆ setGradientInterpolation()

void tesseract::geometry::SignedDistanceField::setGradientInterpolation ( SignedDistanceFieldInterpolation interpolation)

Read the gradient with a different method from the distance.

For example trilinear distance (it never overshoots the samples) with a tricubic gradient (continuous across cell faces, for gradient-based optimisers). The gradient is then no longer exactly the derivative of the reported distance. In a sparse field, where this method cannot read (a wider stencil reaching past the active voxels), the gradient falls back to the distance's method there.

◆ discretize()

void tesseract::geometry::SignedDistanceField::discretize ( ) const

Materialize the dense sample grid from the sampler (no-op if already discretized or grid-backed).

Thread-safe and idempotent. A lazy field must be discretized before it can be serialized or compared; this happens automatically at those boundaries but may be called explicitly.

◆ clone()

Geometry::Ptr tesseract::geometry::SignedDistanceField::clone ( ) const
finaloverridevirtual

Create a copy of this shape.

Implements tesseract::geometry::Geometry.