Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #69

Merged
merged 1 commit into from
Aug 27, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions Docs/Sphinx/source/ImplemBVH.rst
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 6 additions & 5 deletions Docs/Sphinx/source/Parsers.rst
Original file line number Diff line number Diff line change
@@ -3,25 +3,26 @@
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++

std::vector<std::string> files; // <---- List of file names.

const auto distanceFields = EBGeometry::Parser::readIntoLinearBVH<float>(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::
2 changes: 1 addition & 1 deletion Source/EBGeometry_Parser.hpp
Original file line number Diff line number Diff line change
@@ -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
*/