![]() |
Tesseract 0.28.4
|
A volumetric signed distance field geometry. More...
#include <signed_distance_field.h>

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) |
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.
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.
| 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.
| domain | The axis-aligned domain (local frame) spanned by the sample grid |
| dimensions | The number of samples along each axis (>= 2 on every axis) |
| distances | The 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()) |
| scale | Finite, strictly positive local scaling applied to the field |
| 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.
sampler on your own thread. sampler must be thread-safe.| domain | The axis-aligned domain (local frame) to sample over when discretizing |
| dimensions | The number of samples along each axis to discretize (>= 2 on every axis) |
| sampler | The batched signed distance function (negative inside) in the field's local frame |
| scale | Finite, strictly positive local scaling applied to the field |
| 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.
| nvdb | One 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_clamp | The 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. |
| scale | Finite, strictly positive local scaling applied to the field (e.g. 1e-3 for a grid stored in millimetres and used in metres) |
| std::runtime_error | if 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 |
|
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'.
| levels | Sparse single-grid fields (see the sparse constructor), finest first, with equal scales |
| std::runtime_error | if 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 |
| const std::vector< double > & tesseract::geometry::SignedDistanceField::getDistances | ( | ) | const |
Get the sampled signed distances (row-major: index = i + nx*(j + ny*k)).
| std::runtime_error | on a sparse field, which has no dense grid |
| 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.
| 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.
| 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.
| 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.
| 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.
|
finaloverridevirtual |
Create a copy of this shape.
Implements tesseract::geometry::Geometry.