signed_distance.hpp File Reference

The Signed Distance Query evaluates the signed distance function, \( \phi \), at an arbitrary point, \( \vec{p} \), with respect to an oriented surface, \( \mathcal S\). More...

#include "axom/config.hpp"
#include "axom/quest/interface/internal/mpicomm_wrapper.hpp"
#include <cstddef>
#include <string>

Namespaces
	axom
	axom::mint
	axom::quest

Enumerations
enum class	axom::quest::SignedDistExec { axom::quest::CPU = 0 , axom::quest::OpenMP = 1 , axom::quest::GPU = 2 }

Functions
Signed Distance Query Initialization Methods
int	axom::quest::signed_distance_init (const std::string &file, MPI_Comm comm=MPI_COMM_SELF)
	Initializes the Signed Distance Query with a surface given in an STL formatted file. More...
int	axom::quest::signed_distance_init (const mint::Mesh *m, MPI_Comm comm=MPI_COMM_SELF)
	Initializes the Signed Distance Query with the given surface mesh. More...
bool	axom::quest::signed_distance_initialized ()
	Checks if the Signed Distance Query has been initialized. More...
Signed Distance Query Options
void	axom::quest::signed_distance_set_dimension (int dim)
	Sets the dimension for the Signed Distance Query. More...
void	axom::quest::signed_distance_set_closed_surface (bool status)
	Indicates whether the input to the signed distance consists of a water-tight surface mesh, or not. More...
void	axom::quest::signed_distance_set_compute_signs (bool computeSign)
	Sets whether the distance query should compute or ignore the sign. More...
void	axom::quest::signed_distance_set_allocator (int allocatorID)
	Sets the allocator to use for creating internal signed distance query data structures. More...
void	axom::quest::signed_distance_set_verbose (bool status)
	Enables/Disables verbose output for the Signed Distance Query. More...
void	axom::quest::signed_distance_use_shared_memory (bool status)
	Enable/Disable the use of on-node shared memory (via Umpire's shared-memory resource) for storing the surface mesh. By default this option is disabled. More...
void	axom::quest::signed_distance_set_shared_memory_size (std::size_t min_segment_size)
	Set the minimum size (in bytes) of the backing shared-memory segment used to store the surface mesh when signed_distance_use_shared_memory(true) is enabled. More...
void	axom::quest::signed_distance_set_execution_space (SignedDistExec execSpace)
	Set the execution space in which to run signed distance queries. By default this option is set to SIGNED_DIST_EVAL_CPU. More...
Signed Distance Query Evaluation Methods
double	axom::quest::signed_distance_evaluate (double x, double y, double z=0.0)
	Evaluates the signed distance function at the given point. More...
double	axom::quest::signed_distance_evaluate (double x, double y, double z, double &cp_x, double &cp_y, double &cp_z, double &n_x, double &n_y, double &n_z)
	Evaluates the signed distance function at the given 3D point. More...
void	axom::quest::signed_distance_evaluate (const double *x, const double *y, const double *z, int npoints, double *phi)
	Evaluates the signed distance function at the given set of points. More...
void	axom::quest::signed_distance_get_mesh_bounds (double *lo, double *hi)
	Computes the bounds of the specified input mesh supplied to the Signed Distance Query. More...
Signed Distance Query Finalization Methods
void	axom::quest::signed_distance_finalize ()
	Finalizes the SignedDistance query. More...

Detailed Description

The Signed Distance Query evaluates the signed distance function, \( \phi \), at an arbitrary point, \( \vec{p} \), with respect to an oriented surface, \( \mathcal S\).

Given a discrete representation of the surface, i.e., a surface mesh, that is oriented according to an outward-facing unit normal, the signed distance function, \( \phi(\vec{p}) \), evaluated at a point, \( \vec{p} \), is defined such that:

\begin{equation} \phi( \vec{p} ) = \begin{cases} +d, & \vec{p} \mbox{ is in front of the surface, } \mathcal{S} \\ \pm0, & \vec{p} \mbox{ is on the boundary, } \partial\mathcal{S} \\ -d, & \vec{p} \mbox{ is behind the surface, } \mathcal{S} \end{cases} \end{equation}

Warning

Currently, the Signed Distance Query supports:

• reading in surface meshes given in the STL format
• oriented 3D triangular surface meshes

Usage Example:

int main( int argc, char** argv )
{
  MPI_Init( &argc, &argv );
  MPI_Comm mpi_comm = MPI_COMM_WORLD;
  ...
  // STEP 0: set parameters
  quest::signed_distance_set_dimension( 3 );
  quest::signed_distance_set_max_levels( 25 );
  quest::signed_distance_set_max_occupancy( 5 );
 
  // STEP 1: initialize
  quest::signed_distance_init( "path/to/stlmesh.stl", mpi_comm );
 
  // STEP 2: evaluate the signed distance at N query points
  for ( int i=0; i < N; ++i )
  {
     ...
     phi[ i ] = quest::signed_distance_evaluate( x[i], y[i], z[i] );
 
  } // END for all N query points
 
  // STEP 3: Finalize
  quest::signed_distance_finalize( );
 
  MPI_Finalize( );
  return 0;
}