Update documentation (#69)

Author: rmrsk

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.

Docs/Sphinx/source/Parsers.rst

@@ -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::

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
   */