AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
axom::quest::Delaunay< DIM > Class Template Reference

A class for incremental generation of a 2D or 3D Delaunay triangulation. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/feature-kweiss-improve-python-sidre/src/axom/quest/Delaunay.hpp>

Inheritance diagram for axom::quest::Delaunay< DIM >:

Classes

struct  CircumsphereEval
 Precomputed circumsphere center and squared radius for in-sphere tests. More...
 
struct  InsertionStats
 Statistics about point insertion operations (cavity size during Bowyer-Watson insertion) More...
 
struct  OrientationEval
 Orientation determinant evaluation with tolerance for robust geometric tests. More...
 
struct  PointLocationResult
 Combined result from point location including element index and status. More...
 
struct  PointLocationStats
 Statistics about point location query performance. More...
 

Public Types

enum class  InsertionValidationMode { None , Local , ConformingMesh , Full }
 Controls the level of validation performed during point insertion. More...
 
enum class  PointLocationStatus { Found , Outside , Failed }
 Result status from point location queries. More...
 
using DataType = double
 
using PointType = primal::Point< DataType, DIM >
 
using VectorType = primal::Vector< DataType, DIM >
 
using ElementType = typename std::conditional< DIM==2, primal::Triangle< DataType, 2 >, primal::Tetrahedron< DataType, 3 > >::type
 
using BaryCoordType = primal::Point< DataType, DIM+1 >
 
using BoundingBox = primal::BoundingBox< DataType, DIM >
 
using IAMeshType = slam::IAMesh< DIM, DIM, PointType >
 
using IndexType = typename IAMeshType::IndexType
 
using IndexArray = typename IAMeshType::IndexArray
 
using IndexPairType = std::pair< IndexType, IndexType >
 

Public Member Functions

 AXOM_STATIC_ASSERT_MSG (DIM==2||DIM==3, "The template parameter DIM can only be 2 or 3. ")
 
 Delaunay ()
 Default constructor. More...
 
 Delaunay (const Delaunay &)=delete
 
Delaunayoperator= (const Delaunay &)=delete
 
 Delaunay (Delaunay &&other)
 
Delaunayoperator= (Delaunay &&other)
 
InsertionStats getInsertionStats () const
 Returns statistics about insertion operations. More...
 
void setCollectPointLocationStats (bool enabled)
 Enable or disable collection of point location statistics. More...
 
PointLocationStats getPointLocationStats () const
 Returns statistics about point location query performance. More...
 
void setInsertionValidationMode (InsertionValidationMode mode)
 Controls the amount of validation performed around each point insertion. More...
 
InsertionValidationMode getInsertionValidationMode () const
 Returns the current insertion validation mode. More...
 
void initializeBoundary (const BoundingBox &bb)
 Defines the boundary of the triangulation. More...
 
void reserveForPointCount (IndexType num_points)
 Reserve storage for an expected number of inserted points. More...
 
void insertPoint (const PointType &new_pt)
 Adds a new point and locally re-triangulates the mesh to ensure it remains Delaunay. More...
 
ElementType getElement (int element_index) const
 Retrieves the geometric element (triangle or tetrahedron) at the given index. More...
 
void printMesh ()
 Prints out mesh details, for debugging purpose. More...
 
void writeToVTKFile (const std::string &filename)
 Write the mesh to a legacy VTK file for visualization. More...
 
void removeBoundary ()
 Removes the bounding box vertices and all attached elements. More...
 
const IAMeshTypegetMeshData () const
 Get the underlying IA mesh data structure. More...
 
bool isValid (bool verboseOutput=false) const
 Checks that the mesh satisfies the Delaunay empty-circumsphere property. More...
 
bool isConforming (bool verboseOutput=false) const
 Checks mesh conformity, orientation, and boundary consistency. More...
 
bool isSearchableElement (IndexType element_idx) const
 Returns true if an element is active and can participate in point-location queries. More...
 
IndexType findContainingElement (const PointType &query_pt, bool warnOnInvalid=true) const
 Locate the element containing a query point using directed walk. More...
 
BaryCoordType getBaryCoords (IndexType element_idx, const PointType &q_pt) const
 Compute barycentric coordinates of a query point within an element. More...
 
IndexArray getSeedElements (IndexType element_idx, const BaryCoordType &bary_coord) const
 Returns initial seed elements for cavity expansion based on point location. More...
 
OrientationEval evaluateElementOrientationDeterminant (IndexType element_idx) const
 Computes the signed orientation determinant of an element together with its scale-aware tolerance and classification. More...
 

Static Public Member Functions

static int signWithTolerance (double value, double tolerance)
 Classify a value as positive, negative, or zero within tolerance. More...
 
static CircumsphereEval evaluateCircumsphereOnMesh (const IAMeshType &mesh, IndexType element_idx)
 Builds the circumsphere (center and squared radius) of a mesh element. More...
 
static double sphereSquaredDistanceTolerance (const CircumsphereEval &sphere, const PointType &x, double distance_sq)
 Scale-aware tolerance for comparing a squared distance against a circumsphere's squared radius, used to classify on-sphere cases robustly. More...
 
static int inSphereOrientationOnMesh (const IAMeshType &mesh, const PointType &q, IndexType element_idx)
 Classifies the query point against an element's circumsphere via the in-sphere determinant: ON_POSITIVE_SIDE (outside), ON_NEGATIVE_SIDE (inside), or ON_BOUNDARY (on the sphere, within tolerance). More...
 
static double inSphereDeterminantOnMesh (const IAMeshType &mesh, const PointType &q, IndexType element_idx)
 Returns the raw (unclassified) in-sphere determinant of q against the circumsphere of element_idx. The sign indicates inside/outside. The caller applies its own tolerance (see inSphereOrientationOnMesh()). More...
 
static const char * orientationResultName (int result)
 Returns a human-readable name for a primal::OrientationResult value (for diagnostics and warning messages). More...
 
static bool isPointInSphereOnMesh (const IAMeshType &mesh, const PointType &q, IndexType element_idx, bool includeBoundary)
 Convenience predicate: true if q is inside element element_idx's circumsphere (and, when includeBoundary is set, on it within tolerance). More...
 
static int classifyOrientationDeterminant (double det, double tol)
 Classifies an orientation determinant against a tolerance into a primal::OrientationResult (ON_POSITIVE_SIDE/ON_BOUNDARY/ON_NEGATIVE_SIDE). More...
 

Static Public Attributes

static constexpr double BARY_EPS = 1e-12
 
static constexpr int VERT_PER_ELEMENT = DIM + 1
 
static constexpr int VERTS_PER_FACET = VERT_PER_ELEMENT - 1
 
static constexpr IndexType INVALID_INDEX = -1
 

Detailed Description

template<int DIM = 2>
class axom::quest::Delaunay< DIM >

A class for incremental generation of a 2D or 3D Delaunay triangulation.

Construct a Delaunay triangulation incrementally by inserting points one by one. The public API lives in this header while the larger insertion, point-location, and validation routines are split into companion detail/ headers.

A bounding box of the points needs to be defined first via initializeBoundary(...). The algorithm uses the Bowyer-Watson incremental insertion approach with robust geometric predicates for handling degenerate cases including regular grids and co-spherical point configurations.

Note
This class is not thread-safe. Multiple concurrent insertions are not supported.
Template Parameters
DIMThe spatial dimension (2 for triangulation, 3 for tetrahedralization)

Member Typedef Documentation

◆ DataType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::DataType = double

◆ PointType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::PointType = primal::Point<DataType, DIM>

◆ VectorType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::VectorType = primal::Vector<DataType, DIM>

◆ ElementType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::ElementType = typename std::conditional<DIM == 2, primal::Triangle<DataType, 2>, primal::Tetrahedron<DataType, 3> >::type

◆ BaryCoordType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::BaryCoordType = primal::Point<DataType, DIM + 1>

◆ BoundingBox

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::BoundingBox = primal::BoundingBox<DataType, DIM>

◆ IAMeshType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::IAMeshType = slam::IAMesh<DIM, DIM, PointType>

◆ IndexType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::IndexType = typename IAMeshType::IndexType

◆ IndexArray

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::IndexArray = typename IAMeshType::IndexArray

◆ IndexPairType

template<int DIM = 2>
using axom::quest::Delaunay< DIM >::IndexPairType = std::pair<IndexType, IndexType>

Member Enumeration Documentation

◆ InsertionValidationMode

template<int DIM = 2>
enum axom::quest::Delaunay::InsertionValidationMode
strong

Controls the level of validation performed during point insertion.

Enumerator
None 

No additional insertion-time validation beyond existing asserts (production mode).

Local 

Checks only insertion-local seed/cavity/ball invariants.

ConformingMesh 

Checks local cavity/ball invariants and that the resulting IA mesh is conforming. Intended for debugging and unit tests.

Full 

Additionally runs a global empty-circumsphere check after each insertion (very expensive). Use only for deep debugging; unsuitable for large meshes.

◆ PointLocationStatus

template<int DIM = 2>
enum axom::quest::Delaunay::PointLocationStatus
strong

Result status from point location queries.

Enumerator
Found 

Query point was successfully located inside an element.

Outside 

Query point lies outside the triangulation boundary.

Failed 

Location failed (internal error or degenerate case)

Constructor & Destructor Documentation

◆ Delaunay() [1/3]

template<int DIM = 2>
axom::quest::Delaunay< DIM >::Delaunay ( )
inline

Default constructor.

Note
User must call initializeBoundary(BoundingBox) before adding points.

◆ Delaunay() [2/3]

template<int DIM = 2>
axom::quest::Delaunay< DIM >::Delaunay ( const Delaunay< DIM > &  )
delete

◆ Delaunay() [3/3]

template<int DIM = 2>
axom::quest::Delaunay< DIM >::Delaunay ( Delaunay< DIM > &&  other)
inline

Member Function Documentation

◆ AXOM_STATIC_ASSERT_MSG()

template<int DIM = 2>
axom::quest::Delaunay< DIM >::AXOM_STATIC_ASSERT_MSG ( DIM  = =2||DIM==3,
"The template parameter DIM can only be 2 or 3. "   
)

◆ operator=() [1/2]

template<int DIM = 2>
Delaunay& axom::quest::Delaunay< DIM >::operator= ( const Delaunay< DIM > &  )
delete

◆ operator=() [2/2]

template<int DIM = 2>
Delaunay& axom::quest::Delaunay< DIM >::operator= ( Delaunay< DIM > &&  other)

◆ getInsertionStats()

template<int DIM = 2>
InsertionStats axom::quest::Delaunay< DIM >::getInsertionStats ( ) const
inline

Returns statistics about insertion operations.

Returns
InsertionStats containing cavity size metrics

◆ setCollectPointLocationStats()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::setCollectPointLocationStats ( bool  enabled)
inline

Enable or disable collection of point location statistics.

Parameters
enabledIf true, track walk performance metrics (adds minimal overhead)
Note
Stats collection is disabled by default

◆ getPointLocationStats()

template<int DIM = 2>
PointLocationStats axom::quest::Delaunay< DIM >::getPointLocationStats ( ) const
inline

Returns statistics about point location query performance.

Returns
PointLocationStats containing walk performance metrics
Note
Returns zeros if setCollectPointLocationStats(true) was not called

◆ setInsertionValidationMode()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::setInsertionValidationMode ( InsertionValidationMode  mode)
inline

Controls the amount of validation performed around each point insertion.

Note
This is intended for debugging. InsertionValidationMode::Full is a diagnostic mode and should not be enabled in performance-sensitive runs.

◆ getInsertionValidationMode()

template<int DIM = 2>
InsertionValidationMode axom::quest::Delaunay< DIM >::getInsertionValidationMode ( ) const
inline

Returns the current insertion validation mode.

◆ initializeBoundary()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::initializeBoundary ( const BoundingBox bb)

Defines the boundary of the triangulation.

Subsequent points added to the triangulation must lie within this boundary. Creates an initial bounding box triangulation (2 triangles in 2D, 6 tetrahedra in 3D).

Parameters
bbThe bounding box that will contain all inserted points
Precondition
Must be called before any points are inserted

◆ reserveForPointCount()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::reserveForPointCount ( IndexType  num_points)
inline

Reserve storage for an expected number of inserted points.

Uses a dimension-specific heuristic for the total simplex count so large bulk-builds can avoid repeated mesh-container reallocations.

Parameters
num_pointsExpected number of points to be inserted
Note
Based on Euler characteristic: 2D expects ~2n triangles for n points, 3D expects ~6n tetrahedra. Heuristics account for bounding box and over-tessellation.

References axom::utilities::ceil().

◆ insertPoint()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::insertPoint ( const PointType new_pt)

Adds a new point and locally re-triangulates the mesh to ensure it remains Delaunay.

Uses the Bowyer-Watson incremental insertion algorithm:

  1. Locate the element containing the new point via directed walk
  2. Expand a cavity of all elements whose circumspheres contain the new point
  3. Retriangulate the cavity by connecting the new point to the cavity boundary
Parameters
new_ptThe point to insert
Precondition
initializeBoundary() must have been called
new_pt must lie within the bounding box
The current mesh must be a valid Delaunay triangulation
Postcondition
The mesh remains a valid Delaunay triangulation
Note
If insertion fails (rare), a warning is logged and the mesh is unchanged

◆ getElement()

template<int DIM = 2>
ElementType axom::quest::Delaunay< DIM >::getElement ( int  element_index) const
inline

Retrieves the geometric element (triangle or tetrahedron) at the given index.

Parameters
element_indexThe index of the element to retrieve
Returns
Triangle (2D) or Tetrahedron (3D) with vertex coordinates

◆ printMesh()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::printMesh ( )
inline

Prints out mesh details, for debugging purpose.

◆ writeToVTKFile()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::writeToVTKFile ( const std::string &  filename)

Write the mesh to a legacy VTK file for visualization.

Parameters
filenameThe name of the file to write to
Note
The suffix ".vtk" will be appended to the provided filename
This method compacts the mesh before export to eliminate deleted elements

◆ removeBoundary()

template<int DIM = 2>
void axom::quest::Delaunay< DIM >::removeBoundary ( )

Removes the bounding box vertices and all attached elements.

The initial bounding box (created by initializeBoundary) consists of 2^DIM vertices that define a rectangular boundary. This method removes those vertices and all simplices incident to them, leaving only the Delaunay triangulation of the inserted points.

Postcondition
No more points can be inserted after calling this method
The mesh is compacted (deleted element slots are removed)

◆ getMeshData()

template<int DIM = 2>
const IAMeshType* axom::quest::Delaunay< DIM >::getMeshData ( ) const
inline

Get the underlying IA mesh data structure.

Returns
Pointer to the IAMesh (for advanced users or ScatteredInterpolation)

◆ isValid()

template<int DIM = 2>
bool axom::quest::Delaunay< DIM >::isValid ( bool  verboseOutput = false) const

Checks that the mesh satisfies the Delaunay empty-circumsphere property.

A Delaunay triangulation is valid when no vertex lies strictly inside the circumsphere of any simplex. This method checks all vertex-simplex pairs.

Parameters
verboseOutputIf true, prints detailed diagnostic information
Returns
true if the Delaunay property holds, false otherwise
Note
This is an O(n·m) check where n = vertices, m = elements. Use for validation.

◆ isConforming()

template<int DIM = 2>
bool axom::quest::Delaunay< DIM >::isConforming ( bool  verboseOutput = false) const

Checks mesh conformity, orientation, and boundary consistency.

Verifies three properties:

  1. Topological conformity (manifold facets, reciprocal adjacencies) via IAMesh::isConforming()
  2. All simplices are positively oriented (positive signed volume/area)
  3. If boundary exists, all boundary facets lie on the bounding box faces
Parameters
verboseOutputIf true, prints detailed diagnostic information
Returns
true if all checks pass, false otherwise

◆ isSearchableElement()

template<int DIM = 2>
bool axom::quest::Delaunay< DIM >::isSearchableElement ( IndexType  element_idx) const

Returns true if an element is active and can participate in point-location queries.

Parameters
element_idxThe element index to check
Returns
true if element is valid (not a deleted/recycled slot)
Note
During insertion, all active elements have valid vertices. After removeBoundary(), the mesh is compacted so all element indices are valid.

◆ findContainingElement()

template<int DIM = 2>
IndexType axom::quest::Delaunay< DIM >::findContainingElement ( const PointType query_pt,
bool  warnOnInvalid = true 
) const

Locate the element containing a query point using directed walk.

Parameters
query_ptThe point to locate
warnOnInvalidIf true, log a warning if location fails
Returns
Element index containing the point, or INVALID_INDEX if not found
Note
Uses grid-seeded directed walk for O(n^(1/DIM)) expected performance

◆ getBaryCoords()

template<int DIM = 2>
BaryCoordType axom::quest::Delaunay< DIM >::getBaryCoords ( IndexType  element_idx,
const PointType q_pt 
) const

Compute barycentric coordinates of a query point within an element.

Parameters
element_idxThe element containing (or near) the query point
q_ptThe query point
Returns
Barycentric coordinates (DIM+1 values that sum to 1)
Note
If the point is inside, all coordinates are non-negative (within tolerance)

◆ getSeedElements()

template<int DIM = 2>
IndexArray axom::quest::Delaunay< DIM >::getSeedElements ( IndexType  element_idx,
const BaryCoordType bary_coord 
) const
inline

Returns initial seed elements for cavity expansion based on point location.

If the query point lies on a face/edge of the containing element (indicated by a barycentric coordinate near zero), the neighbor across that face is also included as a seed. This ensures the cavity expansion starts from all elements that might contain the point in their circumsphere.

Parameters
element_idxThe element containing (or nearest to) the query point
bary_coordBarycentric coordinates of the query point in that element
Returns
Array of seed element indices (at least 1, possibly more if point is on boundary feature)

References axom::utilities::abs(), axom::quest::Delaunay< DIM >::BARY_EPS, SLIC_ASSERT, and axom::quest::Delaunay< DIM >::VERT_PER_ELEMENT.

◆ signWithTolerance()

template<int DIM = 2>
static int axom::quest::Delaunay< DIM >::signWithTolerance ( double  value,
double  tolerance 
)
inlinestatic

Classify a value as positive, negative, or zero within tolerance.

Parameters
valueThe value to classify
toleranceThe tolerance for considering the value as zero
Returns
+1 if value > tolerance, -1 if value < -tolerance, 0 otherwise

◆ evaluateCircumsphereOnMesh()

template<int DIM = 2>
static CircumsphereEval axom::quest::Delaunay< DIM >::evaluateCircumsphereOnMesh ( const IAMeshType mesh,
IndexType  element_idx 
)
static

Builds the circumsphere (center and squared radius) of a mesh element.

Parameters
meshThe triangulation containing the element
element_idxThe element whose circumsphere is computed
Returns
The precomputed circumsphere for repeated in-sphere distance tests

◆ sphereSquaredDistanceTolerance()

template<int DIM = 2>
static double axom::quest::Delaunay< DIM >::sphereSquaredDistanceTolerance ( const CircumsphereEval sphere,
const PointType x,
double  distance_sq 
)
static

Scale-aware tolerance for comparing a squared distance against a circumsphere's squared radius, used to classify on-sphere cases robustly.

Parameters
sphereThe circumsphere being tested against
xThe query point
distance_sqThe squared distance from x to the sphere center
Returns
The tolerance (in squared-distance units) for the on-sphere band

◆ inSphereOrientationOnMesh()

template<int DIM = 2>
static int axom::quest::Delaunay< DIM >::inSphereOrientationOnMesh ( const IAMeshType mesh,
const PointType q,
IndexType  element_idx 
)
static

Classifies the query point against an element's circumsphere via the in-sphere determinant: ON_POSITIVE_SIDE (outside), ON_NEGATIVE_SIDE (inside), or ON_BOUNDARY (on the sphere, within tolerance).

Parameters
meshThe triangulation containing the element
qThe query point
element_idxThe element whose circumsphere is tested

◆ inSphereDeterminantOnMesh()

template<int DIM = 2>
static double axom::quest::Delaunay< DIM >::inSphereDeterminantOnMesh ( const IAMeshType mesh,
const PointType q,
IndexType  element_idx 
)
static

Returns the raw (unclassified) in-sphere determinant of q against the circumsphere of element_idx. The sign indicates inside/outside. The caller applies its own tolerance (see inSphereOrientationOnMesh()).

Parameters
meshThe triangulation containing the element
qThe query point
element_idxThe element whose circumsphere is tested

◆ orientationResultName()

template<int DIM = 2>
static const char* axom::quest::Delaunay< DIM >::orientationResultName ( int  result)
static

Returns a human-readable name for a primal::OrientationResult value (for diagnostics and warning messages).

Parameters
resultAn orientation result code (ON_POSITIVE_SIDE/ON_BOUNDARY/ON_NEGATIVE_SIDE)

◆ isPointInSphereOnMesh()

template<int DIM = 2>
static bool axom::quest::Delaunay< DIM >::isPointInSphereOnMesh ( const IAMeshType mesh,
const PointType q,
IndexType  element_idx,
bool  includeBoundary 
)
static

Convenience predicate: true if q is inside element element_idx's circumsphere (and, when includeBoundary is set, on it within tolerance).

Parameters
meshThe triangulation containing the element
qThe query point
element_idxThe element whose circumsphere is tested
includeBoundaryIf true, on-sphere points count as contained

◆ classifyOrientationDeterminant()

template<int DIM = 2>
static int axom::quest::Delaunay< DIM >::classifyOrientationDeterminant ( double  det,
double  tol 
)
static

Classifies an orientation determinant against a tolerance into a primal::OrientationResult (ON_POSITIVE_SIDE/ON_BOUNDARY/ON_NEGATIVE_SIDE).

Parameters
detThe raw orientation determinant
tolThe scale-aware tolerance for the ON_BOUNDARY band

◆ evaluateElementOrientationDeterminant()

template<int DIM = 2>
OrientationEval axom::quest::Delaunay< DIM >::evaluateElementOrientationDeterminant ( IndexType  element_idx) const

Computes the signed orientation determinant of an element together with its scale-aware tolerance and classification.

Parameters
element_idxThe element to evaluate
Returns
An OrientationEval bundling the determinant, tolerance, and class

Member Data Documentation

◆ BARY_EPS

template<int DIM = 2>
constexpr double axom::quest::Delaunay< DIM >::BARY_EPS = 1e-12
staticconstexpr

Tolerance for barycentric coordinate comparisons (distinguishes interior from boundary) Value chosen to handle typical floating-point error accumulation in coordinate computation

◆ VERT_PER_ELEMENT

template<int DIM = 2>
constexpr int axom::quest::Delaunay< DIM >::VERT_PER_ELEMENT = DIM + 1
staticconstexpr

◆ VERTS_PER_FACET

template<int DIM = 2>
constexpr int axom::quest::Delaunay< DIM >::VERTS_PER_FACET = VERT_PER_ELEMENT - 1
staticconstexpr

◆ INVALID_INDEX

template<int DIM>
constexpr Delaunay< DIM >::IndexType axom::quest::Delaunay< DIM >::INVALID_INDEX = -1
staticconstexpr

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