This folder shows how to turn a triangulated surface mesh (loaded from an STL/PLY/OBJ/VTK file) into a signed distance function, and compares three different ways of evaluating it.
A signed distance function returns, for any point in space, the distance to the nearest point on the mesh's surface, signed by whether the query point is inside or outside the surface. This only makes sense if the mesh is watertight (it has no holes or gaps) and consistently oriented (its triangles all wind the same way, so "inside" is unambiguous everywhere) -- see Geometry representations for the underlying theory.
Computing that distance exactly requires checking every triangle in the mesh, which becomes slow as the mesh grows -- the cost scales linearly with the number of triangles. This example compares that direct, brute-force evaluation against two accelerated representations that instead organize the mesh's triangles into a bounding volume hierarchy: a tree of nested bounding boxes that lets a query skip the (usually large majority of) triangles whose enclosing box is nowhere near the query point. The third representation additionally evaluates several candidate triangles at once using your CPU's SIMD (vector) instructions. All three give identical results for a watertight mesh; the example measures how much faster each accelerated representation is in practice, over many random query points.
Note that the achievable speedup depends on both the geometry and where you query it: a tessellated sphere, for example, has a "blind spot" at its center where every point on the surface is roughly equidistant, so even a bounding volume hierarchy ends up visiting most of the triangles for a query placed there.
This example is standalone and can be built in three ways. Each needs the path
to the EBGeometry root -- the directory that contains EBGeometry.hpp -- which
is two levels up from this folder (../..) when building in place. See
Direct compilation,
Building with GNU Make, and
Building with CMake in the user
documentation for more detail on each approach.
CMake
cmake -S . -B build
cmake --build build
The binary is MeshSDF.ex, in this same directory (same as the other two methods below). Build in single precision, against a library
in a different location, or with EBGEOMETRY_EXPECT() runtime assertions enabled, with cache variables:
cmake -S . -B build -DEBGEOMETRY_PRECISION=float -DEBGEOMETRY_HOME=/path/to/EBGeometry -DEBGEOMETRY_ENABLE_ASSERTIONS=ON
GNU make
make
This produces ./MeshSDF.ex. Override the defaults on the command line:
make PRECISION=float EBGEOMETRY_HOME=/path/to/EBGeometry ASSERTIONS=ON
Directly with a compiler
g++ -std=c++17 -O3 -march=native -I../.. main.cpp -o MeshSDF.ex -pthread
Add -DEBGEOMETRY_PRECISION=float for single precision, or -DEBGEOMETRY_ENABLE_ASSERTIONS to enable
EBGEOMETRY_EXPECT() runtime assertion checks.
For a GPU
The same source also builds for a GPU, and its last section then runs in a kernel (a GPU build without a visible GPU skips that part):
make GPU=HIP HIP_ARCH=gfx90a # or GPU=CUDA CUDA_ARCH=sm_80
cmake -S . -B build -DEBGEOMETRY_EXAMPLE_GPU=HIP # or CUDA
hipcc -std=c++17 -O3 -x hip --offload-arch=gfx90a -I../.. main.cpp -o MeshSDF.ex
See GPU builds in the user documentation.
With the viewer
At the end the example opens a window on the mesh (EBGeometry::Render::view()). The window needs
SDL2 (for example libsdl2-dev, or brew install sdl2) and is built only on request:
make VIEWER=SDL2
cmake -S . -B build -DEBGEOMETRY_VIEWER=SDL2
g++ -std=c++17 -O3 -march=native -DEBGEOMETRY_VIEWER_SDL2 $(sdl2-config --cflags) -I../.. main.cpp -o MeshSDF.ex $(sdl2-config --libs) -pthread
Without it, view() prints a line saying how to build it and returns.
Run from this directory so the default mesh path resolves:
./MeshSDF.ex
./MeshSDF.ex ../../common-3d-test-models/data/cow.obj
With no argument the example loads armadillo.obj from the
common-3d-test-models submodule, so make sure it is checked out
(git submodule update --init; see
Obtaining EBGeometry for details). You can pass
the path to any watertight, triangulated STL/PLY/OBJ/VTK file instead.
The program prints the mesh's face count and bounding box, then the time per query of each of the
three representations over the same random points, with the speedup of the two BVH-backed ones over
the flat scan, the values at the first few points (the same in all three), and which face is nearest
the first point. Then it evaluates the TriMeshSDF at those points through
EBGeometry::GPU::transform: in a kernel in a GPU build, in a host loop otherwise.
Finally it opens the viewer on the TriMeshSDF, if built with it, and waits until the window is
closed. Drag to orbit and scroll to zoom; the window lists its other keys (see
the viewer's keys).
A surface seen from inside the solid is drawn red: that is what the inside looks like through the
section plane's cut, and what a mesh whose faces are wound the wrong way looks like from outside.
The TriMeshSDF is ray traced (rays through its BVH, tested against its triangles), so the window
follows the mouse: a quick preview while the camera moves, refined to the full frame once it rests.
In a GPU build the window renders on the GPU (G switches to the CPU and back). Build that in single
precision, since many GPUs are much slower in double precision:
make GPU=CUDA VIEWER=SDL2 PRECISION=float
--no-view skips the window (ctest passes it), as does running without a display:
./MeshSDF.ex --no-view