Signed distance function for a pure triangle mesh using SoA-grouped primitives in a compact (linearized) BVH. More...

#include <EBGeometry_MeshDistanceFunctions.hpp>

Inheritance diagram for EBGeometry::TriMeshSDF< T, K, W >:

Collaboration diagram for EBGeometry::TriMeshSDF< T, K, W >:

Classes
struct	Layout
	The object's arrays as offsets into its pool, with no location (see PoolHandle). More...

Public Types
using	Mesh = EBGeometry::DCEL::MeshT< T >
	Alias for DCEL mesh type.

using	Tri = typename EBGeometry::Triangle< T >
	Alias for the flat triangle type the BVH is built from.

using	TriAoSoA = TriangleAoSoA< T, W >
	Alias for the face-id-carrying SoA triangle group type (the BVH leaf primitive).

using	Root = typename EBGeometry::BVH::PackedBVH< T, TriAoSoA, K >
	Alias for which BVH root node.

Public Member Functions
	TriMeshSDF ()=delete
	Default disallowed constructor.

	TriMeshSDF (const Layout &a_layout, const PoolLocation &a_location) noexcept
	Rebuild a handle from a stored layout and the location of the pool that holds it.

Layout	layout () const noexcept
	The object's arrays without its location, for storing it inside another pool-resident object.

	TriMeshSDF (const Mesh &a_mesh, Pool &a_pool, const BVH::Construction a_construction, const size_t a_maxLeafGroups)
	Full constructor. Extracts flat triangles from a DCEL mesh, then builds the BVH.

	TriMeshSDF (const std::vector< Tri > &a_triangles, Pool &a_pool, const BVH::Construction a_construction, const size_t a_maxLeafGroups)
	Full constructor. Takes the input triangles and creates the BVH.

	TriMeshSDF (const Mesh &a_mesh, Pool &a_pool, const BVH::Construction a_construction, const BVH::ConstructionOptions &a_options)
	Full constructor from a DCEL mesh, with leaf-size settings.

	TriMeshSDF (const std::vector< Tri > &a_triangles, Pool &a_pool, const BVH::Construction a_construction, const BVH::ConstructionOptions &a_options)
	Full constructor from a triangle soup, with leaf-size settings.

T	signedDistance (const Vec3T< T > &a_point) const noexcept
	Compute the signed distance from a_point to the triangle mesh.

ClosestFace< T >	getClosestFace (const Vec3T< T > &a_point) const noexcept
	Find the face closest to a_point, and the signed distance to it.

Root	getRoot () const noexcept
	Get the PackedBVH storing SoA triangle groups.

EBGeometry::BoundingVolumes::AABBT< T >	computeBoundingVolume () const noexcept
	Compute the AABB enclosing the entire triangle mesh.

TriMeshSDF	rebasedView (const Pool &a_pool) const noexcept
	Produce a copy of this object that resolves against `a_pool`.

TriMeshSDF	deepCopy (Pool &a_dstPool) const
	Duplicate the BVH's storage into `a_dstPool`.

Public Member Functions inherited from EBGeometry::PoolHandle
PoolLocation	location () const noexcept
	Where this handle's arrays live.

bool	isAttachedTo (const Pool &a_pool) const noexcept
	Check whether this handle's arrays were reserved from `a_pool`.

Static Public Member Functions
static BVH::ConstructionOptions	defaultConstructionOptions (const size_t a_maxLeafGroups) noexcept
	The leaf-size settings the constructors taking a_maxLeafGroups use.

Static Public Attributes
static constexpr DistanceQuality	distanceQuality = DistanceQuality::Exact
	How far signedDistance() can be trusted as a distance: the Euclidean distance to a watertight mesh.

Additional Inherited Members
Protected Member Functions inherited from EBGeometry::PoolHandle
	PoolHandle () noexcept=default
	An unset location; the first reservation attaches it.

	PoolHandle (const PoolLocation &a_location) noexcept
	Adopt a location, as a handle rebuilt from a stored layout does.

	PoolHandle (const PoolHandle &) noexcept=default
	Copy a handle, as a derived handle's copy does.

	PoolHandle (PoolHandle &&) noexcept=default
	Move a handle; the same as a copy.

PoolHandle &	operator= (const PoolHandle &) noexcept=default
	Copy-assign a handle, as a derived handle's assignment does.

PoolHandle &	operator= (PoolHandle &&) noexcept=default
	Move-assign a handle; the same as a copy.

	~PoolHandle () noexcept=default
	Destructor; protected, since a PoolHandle exists only as the base of a handle.

void *	base () noexcept
	The base address this handle's offsets resolve against; see PoolLocation::base().

const void *	base () const noexcept
	The base address this handle's offsets resolve against, for read-only access.

void	attach (const Pool &a_pool, const char *a_who) noexcept
	Follow `a_pool`, as the first reservation does; see PoolLocation::attach().

PoolLocation	rebasedLocation (const Pool &a_pool, uint64_t a_endByte, const char *a_who) const noexcept
	The location of this handle's arrays in another pool of its mirror chain; see PoolLocation::rebasedOnto().

void	setLocation (const PoolLocation &a_location) noexcept
	Replace the location, for a view or a copy made by a derived handle.

Detailed Description

template<class T, size_t K, size_t W>
class EBGeometry::TriMeshSDF< T, K, W >

Signed distance function for a pure triangle mesh using SoA-grouped primitives in a compact (linearized) BVH.

Triangles are packed into SoA groups of W triangles each (TriangleAoSoA<T,W>), enabling SIMD evaluation of up to W signed distances simultaneously.

No default arguments: this is a low-level constructor, and callers who excavate down to it must consciously choose K and W. BVH::DefaultBranchingRatio<T>() and TriangleSoA::DefaultWidth<T>() (both 4) are the portable choice, and Parser::readIntoTriMeshSDF's defaults.

Each leaf primitive is a TriangleAoSoA<T, W>: an SoA triangle block for SIMD signed-distance evaluation, plus a physically separate per-lane array of face ids, the index of the mesh face each triangle was cut from. The hot signedDistance() path never reads the ids; getClosestFace() does, returning the closest triangle's signed distance together with its face id. The groups are self-contained – no reference back to a mesh – so the packed BVH is the only thing this class holds, and a mesh changed after the build is not seen.

A plain value type, like FlatMeshSDF and MeshSDF: the BVH is held by value in the Pool passed to the constructor, so the class is trivially copyable and every query is callable on the host and on a device. It has no virtual functions. Copies share the pool memory, and the pool must outlive all of them. To evaluate on a device, freeze and mirror the pool and pass rebasedView() into a kernel.

Template Parameters

T	Floating-point precision type (float or double).
K	BVH branching factor (number of children per internal node). Must be >= 2.
W	SoA width: number of triangles per SIMD group. Must be > 0.

Constructor & Destructor Documentation

◆ TriMeshSDF() [1/5]

template<class T , size_t K, size_t W>

EBGeometry::TriMeshSDF< T, K, W >::TriMeshSDF	(	const Layout &	a_layout,
		const PoolLocation &	a_location
	)

inlinenoexcept

Rebuild a handle from a stored layout and the location of the pool that holds it.

How an outer pool-resident object, such as a BVHUnion, evaluates a TriMeshSDF it stores as a layout. a_location must belong to the pool the layout was reserved from, or to a mirror of it; nothing is checked, since a device has no pool to check against.

Parameters

[in]	a_layout	The arrays.
[in]	a_location	Where they live.

◆ TriMeshSDF() [2/5]

template<class T , size_t K, size_t W>

EBGeometry::TriMeshSDF< T, K, W >::TriMeshSDF	(	const Mesh &	a_mesh,
		Pool &	a_pool,
		const BVH::Construction	a_construction,
		const size_t	a_maxLeafGroups
	)

inline

Full constructor. Extracts flat triangles from a DCEL mesh, then builds the BVH.

No default arguments: this is a low-level constructor, and callers who excavate down to it must consciously choose every parameter. Use Parser::readIntoTriMeshSDF for sensible defaults. The mesh is not retained: its triangles are copied into the BVH's SoA groups, each carrying the id of the face it was cut from.

Parameters

[in]	a_mesh	DCEL mesh. Faces with more than three vertices are fan-triangulated.
[in,out]	a_pool	Pool the packed BVH is reserved from; must outlive this object.
[in]	a_construction	Preset construction method; every BVH::Construction value is supported. SAH (binned Surface Area Heuristic) produces near-optimal traversal cost; CentroidSplit and MidpointSplit are faster to build but yield deeper trees. Every method honours a_maxLeafGroups through defaultConstructionOptions(): the top-down methods as a bound, the space-filling curves as a target, and ClusterSAH through its cluster size.
[in]	a_maxLeafGroups	Maximum number of full W-sized TriangleSoA groups per BVH leaf; the actual raw-triangle leaf-size bound used is a_maxLeafGroups * W. This bounds the pre-packing tree's leaf size, not the packed representation directly: each leaf's triangles become their own TriangleSoA group(s) during packing, with no batching across leaves, so a leaf smaller than W wastes some of its group's SIMD lanes on padding. For the top-down methods it is an upper bound, not a target — the partitioner still splits down to tighter, more selective leaves wherever the geometry warrants it; the space-filling curves aim for it. Expressing this as a count of W-sized groups (rather than a raw triangle count) makes it impossible to accidentally pick a leaf size that isn't a multiple of W. Must be > 0.

◆ TriMeshSDF() [3/5]

template<class T , size_t K, size_t W>

EBGeometry::TriMeshSDF< T, K, W >::TriMeshSDF	(	const std::vector< Tri > &	a_triangles,
		Pool &	a_pool,
		const BVH::Construction	a_construction,
		const size_t	a_maxLeafGroups
	)

inline

Full constructor. Takes the input triangles and creates the BVH.

Parameters

[in]	a_triangles	Input triangle soup; copied into the BVH's SoA groups. getClosestFace() reports the face id each triangle carries (Triangle::getFaceId()).
[in,out]	a_pool	Pool the packed BVH is reserved from; must outlive this object.
[in]	a_construction	Preset BVH construction method (see the mesh-based constructor for details).
[in]	a_maxLeafGroups	Maximum number of full W-sized TriangleSoA groups per BVH leaf (see the mesh-based constructor for the tree-quality/SIMD-occupancy trade-off). Must be > 0.

◆ TriMeshSDF() [4/5]

template<class T , size_t K, size_t W>

EBGeometry::TriMeshSDF< T, K, W >::TriMeshSDF	(	const Mesh &	a_mesh,
		Pool &	a_pool,
		const BVH::Construction	a_construction,
		const BVH::ConstructionOptions &	a_options
	)

inline

Full constructor from a DCEL mesh, with leaf-size settings.

As the constructor taking a_maxLeafGroups, which uses defaultConstructionOptions(a_maxLeafGroups). The chosen method reads only its own field of a_options, counted in triangles; see BVH::ConstructionOptions. A leaf's triangles are packed into ceil(n / W) groups.

Parameters

[in]	a_mesh	DCEL mesh. Faces with more than three vertices are fan-triangulated.
[in,out]	a_pool	Pool the packed BVH is reserved from; must outlive this object.
[in]	a_construction	Preset construction method; every BVH::Construction value is supported.
[in]	a_options	Leaf-size settings, in triangles.

◆ TriMeshSDF() [5/5]

template<class T , size_t K, size_t W>

EBGeometry::TriMeshSDF< T, K, W >::TriMeshSDF	(	const std::vector< Tri > &	a_triangles,
		Pool &	a_pool,
		const BVH::Construction	a_construction,
		const BVH::ConstructionOptions &	a_options
	)

inline

Full constructor from a triangle soup, with leaf-size settings.

Parameters

[in]	a_triangles	Input triangle soup; copied into the BVH's SoA groups.
[in,out]	a_pool	Pool the packed BVH is reserved from; must outlive this object.
[in]	a_construction	Preset construction method; every BVH::Construction value is supported.
[in]	a_options	Leaf-size settings, in triangles; see the mesh-based constructor.

Member Function Documentation

◆ computeBoundingVolume()

template<class T , size_t K, size_t W>

EBGeometry::BoundingVolumes::AABBT< T > EBGeometry::TriMeshSDF< T, K, W >::computeBoundingVolume ( ) const

inlinenoexcept

Compute the AABB enclosing the entire triangle mesh.

Returns: Axis-aligned bounding box of the mesh.

◆ deepCopy()

template<class T , size_t K, size_t W>

TriMeshSDF EBGeometry::TriMeshSDF< T, K, W >::deepCopy ( Pool & a_dstPool ) const

inline

Duplicate the BVH's storage into a_dstPool.

The copy constructor copies descriptors only. This gives genuinely independent storage.

Parameters

[in,out] a_dstPool Pool to reserve the copy from; may be this object's own pool.

Returns: A TriMeshSDF over an independent copy of the BVH, attached to a_dstPool.

◆ defaultConstructionOptions()

template<class T , size_t K, size_t W>

static BVH::ConstructionOptions EBGeometry::TriMeshSDF< T, K, W >::defaultConstructionOptions ( const size_t a_maxLeafGroups )

inlinestaticnoexcept

The leaf-size settings the constructors taking a_maxLeafGroups use.

At most a_maxLeafGroups * W triangles per leaf for the top-down methods, the same as the target for the space-filling curves, and for ClusterSAH a cluster size that keeps a leaf of K-1 clusters within that bound (or within K-1 triangles, if the bound is smaller, since a cluster holds at least one). Start from these to change one method's setting; see BVH::ConstructionOptions.

Parameters

[in] a_maxLeafGroups Maximum number of full W-sized TriangleSoA groups per leaf. Must be > 0.

Returns: The settings, in triangles.

◆ getClosestFace()

template<class T , size_t K, size_t W>

ClosestFace< T > EBGeometry::TriMeshSDF< T, K, W >::getClosestFace ( const Vec3T< T > & a_point ) const

inlinenoexcept

Find the face closest to a_point, and the signed distance to it.

The face-id-retrieving companion to signedDistance(): it drives the same SIMD-pruned BVH traversal (PackedBVH::traverse() with a PointQuery), but each visited leaf group reports the winning triangle's face id via TriangleAoSoA::signedDistance(point, uint32_t&).

Parameters

[in] a_point Query point. Must be finite.

Returns: The face id of the closest triangle and the signed distance to it. The signed distance agrees with what signedDistance() returns for the same point except where two triangles are equally near to rounding: on the host, signedDistance() ranks triangles by squared unsigned distance and signs only the winner, while this function ranks them by the absolute value of their signed distances.

◆ getRoot()

template<class T , size_t K, size_t W>

Root EBGeometry::TriMeshSDF< T, K, W >::getRoot ( ) const

inlinenoexcept

Get the PackedBVH storing SoA triangle groups.

Returns: The packed BVH.

◆ layout()

template<class T , size_t K, size_t W>

Layout EBGeometry::TriMeshSDF< T, K, W >::layout ( ) const

inlinenoexcept

The object's arrays without its location, for storing it inside another pool-resident object.

Returns: The layout.

◆ rebasedView()

template<class T , size_t K, size_t W>

TriMeshSDF EBGeometry::TriMeshSDF< T, K, W >::rebasedView ( const Pool & a_pool ) const

inlinenoexcept

Produce a copy of this object that resolves against a_pool.

Rebases the BVH; see BVH::PackedBVH::rebasedView() for the contract. This is the one sanctioned crossing to a device.

Parameters

[in] a_pool Pool to rebase onto: the object's own pool or one in its mirror chain.

Returns: A TriMeshSDF resolving against a_pool.

◆ signedDistance()

template<class T , size_t K, size_t W>

T EBGeometry::TriMeshSDF< T, K, W >::signedDistance ( const Vec3T< T > & a_point ) const

inlinenoexcept

Compute the signed distance from a_point to the triangle mesh.

Parameters

[in] a_point Query point.

Returns: Signed distance to the nearest triangle; negative inside the mesh.

The documentation for this class was generated from the following file:

Source/EBGeometry_MeshDistanceFunctions.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TriMeshSDF() [1/5]

◆ TriMeshSDF() [2/5]

◆ TriMeshSDF() [3/5]

◆ TriMeshSDF() [4/5]

◆ TriMeshSDF() [5/5]

Member Function Documentation

◆ computeBoundingVolume()

◆ deepCopy()

◆ defaultConstructionOptions()

◆ getClosestFace()

◆ getRoot()

◆ layout()

◆ rebasedView()

◆ signedDistance()