From 9acad6ba91ce0b65fc4114a6cf53e6d8c3b130f9 Mon Sep 17 00:00:00 2001 From: Robert Marskar Date: Tue, 27 Aug 2024 09:20:54 +0200 Subject: [PATCH] update documentation --- Docs/Sphinx/source/ImplemBVH.rst | 19 +++++++++++++++++++ Docs/Sphinx/source/Parsers.rst | 11 ++++++----- Source/EBGeometry_Parser.hpp | 2 +- 3 files changed, 26 insertions(+), 6 deletions(-) diff --git a/Docs/Sphinx/source/ImplemBVH.rst b/Docs/Sphinx/source/ImplemBVH.rst index 54d7a849..836fff33 100644 --- a/Docs/Sphinx/source/ImplemBVH.rst +++ b/Docs/Sphinx/source/ImplemBVH.rst @@ -278,6 +278,12 @@ If the traversal decides to visit a node, it immediately computes the specified Traversal examples __________________ +Below, we consider two examples for BVH traversal. +The examples show how we compute the signed distance from a DCEL mesh, and how to perform a *smooth* CSG union where the search for the two closest objects is done by BVH traversal. + +Signed distance +^^^^^^^^^^^^^^^ + The DCEL mesh distance fields use a traversal pattern based on * Only visit bounding volumes that are closer than the minimum distance computed (so far). @@ -291,3 +297,16 @@ These rules are given below. :lines: 97-132 :caption: Tree traversal criterion for computing the signed distance to a DCEL mesh using the BVH accelerator. See :file:`Source/EBGeometry_MeshDistanceFunctionsImplem.hpp` for details. + +CSG Union +^^^^^^^^^ + +Combinations of implicit functions in ``EBGeometry`` into aggregate objects can be done by means of CSG unions. +One such union is known as the *smooth union*, in which the transition between two objects is gradual rather than abrupt. +Below, we show the traversal code for this union, where we traverse through the tree and obtains the distance to the *two* closest objects rather than a single one. + +.. literalinclude:: ../../../Source/EBGeometry_CSGImplem.hpp + :language: c++ + :lines: 369-415 + :caption: Tree traversal when computing the smooth CSG union. + See :file:`Source/EBGeometry_CSGImplem.hpp` for details. diff --git a/Docs/Sphinx/source/Parsers.rst b/Docs/Sphinx/source/Parsers.rst index 7b982817..154fd0f6 100644 --- a/Docs/Sphinx/source/Parsers.rst +++ b/Docs/Sphinx/source/Parsers.rst @@ -3,18 +3,18 @@ Reading data ============ -Routines for parsing surface files from grids into ``EBGeometry``'s DCEL grids are given in the namespace ``EBGeometry::Parser``. +Routines for parsing surface grid from files into ``EBGeometry``'s DCEL grids are given in the namespace ``EBGeometry::Parser``. The source code is implemented in :file:`Source/EBGeometry_Parser.hpp`. .. warning:: ``EBGeometry`` is currently limited to reading binary and ASCII STL files and reconstructing DCEL grids from those. - However, it is a simple matter to also reconstructor DCEL grids from triangle soups read using third-party codes (see :ref:`Chap:ThirdPartyParser`). + However, it is also possible to build DCEL grids from polygon soups read using third-party codes (see :ref:`Chap:ThirdPartyParser`). Quickstart ---------- -If you have one of multiple STL files, you can quickly turn them into implicit functions with +If you have one or multiple STL files, you can quickly turn them into signed distance fields using .. code-block:: c++ @@ -22,6 +22,7 @@ If you have one of multiple STL files, you can quickly turn them into implicit f const auto distanceFields = EBGeometry::Parser::readIntoLinearBVH(files); +This will build DCEL meshes for each input file, and wrap the meshes in BVHs. See :ref:`Chap:LinearSTL` for further details. Reading STL files @@ -79,7 +80,7 @@ To read one or multiple STL files and turn it into signed distance representatio From soups to DCEL ------------------ -``EBGeometry`` also supports the creation of DCEL grids from polygon soups, which can then be later turned into an SDF representation. +``EBGeometry`` also supports the creation of DCEL grids from polygon soups, which can then later be turned into an SDF representation. A triangle soup is represented as .. code-block:: c++ @@ -95,7 +96,7 @@ To turn this into a DCEL mesh, one should compress the triangle soup (get rid of :language: c++ :lines: 146-165 -The ``compress`` function will discard duplicate vertices from the soup, while the ``soupToDCEL`` will simply turn the remaining polygon soup into a DCEL mesh. +The ``compress`` function will discard duplicate vertices from the soup, while the ``soupToDCEL`` will tie the remaining polygons into a DCEL mesh. This function will also compute the vertex and edge normal vectors. .. warning:: diff --git a/Source/EBGeometry_Parser.hpp b/Source/EBGeometry_Parser.hpp index afd71bd6..1a9d9854 100644 --- a/Source/EBGeometry_Parser.hpp +++ b/Source/EBGeometry_Parser.hpp @@ -154,7 +154,7 @@ namespace Parser { /*! @brief Turn raw vertices into DCEL vertices. - @param[out] a_verticesDCEL DCEL vertices + @param[out] a_mesh Output DCEL mesh. @param[in] a_verticesRaw Raw vertices @param[in] a_facets Facets */