Attach meta-data to DCEL meshes (#60)

Author: rmrsk

.github/workflows/CI.yml

@@ -1,3 +1,4 @@
+
 name: Continuous integration
 
 on:
@@ -21,7 +22,7 @@ jobs:
         directory: [Source, Examples]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Run clang-format
         uses: jidicula/clang-format-action@v4.10.1
         with:
@@ -39,7 +40,7 @@ jobs:
         directory: [Examples/EBGeometry_DCEL, Examples/EBGeometry_F18, Examples/EBGeometry_OctreeBoundingVolume, Examples/EBGeometry_PackedSpheres, Examples/EBGeometry_RandomCity, Examples/EBGeometry_Shapes]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install dependencies
         run: |
           sudo apt-get update
@@ -71,7 +72,7 @@ jobs:
         directory: [Examples/EBGeometry_DCEL, Examples/EBGeometry_PackedSpheres, Examples/EBGeometry_RandomCity, Examples/EBGeometry_Shapes]    
 
     steps:
-      - uses: actions/checkout@v3      
+      - uses: actions/checkout@v4      
       - name: Install Intel oneAPI
         working-directory: /tmp        
         run: |
@@ -100,7 +101,7 @@ jobs:
     needs: Formatting
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3      
+      - uses: actions/checkout@v4      
       - name: Install dependencies
         run: |
           sudo apt-get update

.gitignore

@@ -27,6 +27,10 @@ Examples/AMReX_Shapes/plt*
 Examples/AMReX_Shapes/tmp_build_dir
 Examples/AMReX_Shapes/Backtrace.*
 
+Examples/AMReX_PaintEB/plt*
+Examples/AMReX_PaintEB/tmp_build_dir
+Examples/AMReX_PaintEB/Backtrace.*
+
 Examples/Chombo3_DCEL/d/**
 Examples/Chombo3_DCEL/o/**
 Examples/Chombo3_DCEL/f/**

Docs/Sphinx/source/Concepts.rst

@@ -14,13 +14,13 @@ It has the additional property
 
    \left|\nabla S(\mathbf{x})\right| = 1 \quad\textrm{everywhere}.
 
-Note that the normal vector is always
+The normal vector is always
 
 .. math::
 
    \mathbf{n} = \nabla S\left(\mathbf{x}\right).
    
-EBGeometry uses the following convention for the sign:
+``EBGeometry`` uses the following convention for the sign:
 
 .. math::
 
@@ -60,7 +60,7 @@ DCEL
 Principle
 ---------
 
-EBGeometry uses a doubly-connected edge list (DCEL) structure for storing surface meshes.
+``EBGeometry`` uses a doubly-connected edge list (DCEL) structure for storing surface meshes.
 The DCEL structures consist of the following objects:
 
 * Planar polygons (facets).
@@ -79,7 +79,7 @@ From the DCEL structure we can easily obtain all edges or vertices belonging to
    DCEL mesh structure. Each half-edge stores references to next half-edge, the pair edge, and the starting vertex.
    Vertices store a coordinate as well as a reference to one of the outgoing half-edges.
 
-In EBGeometry the half-edge data structure is implemented in its own namespace.
+In ``EBGeometry`` the half-edge data structure is implemented in its own namespace.
 This is a comparatively standard implementation of the DCEL structure, supplemented by functions that permit signed distance computations to various features on such a mesh.
 
 .. important::
@@ -111,7 +111,7 @@ Three cases can be distinguished:
 
    .. tip::
 
-      EBGeometry uses the crossing number algorithm by default.
+      ``EBGeometry`` uses the crossing number algorithm by default.
 
    If the point projects to the inside of the face, the signed distance is just :math:`\mathbf{n}_f\cdot\left(\mathbf{x} - \mathbf{x}_f\right)` where :math:`\mathbf{n}_f` is the face normal and :math:`\mathbf{x}_f` is a point on the face plane (e.g., a vertex).
    If the point projects to *outside* the polygon face, the closest feature is either an edge or a vertex.
@@ -188,7 +188,7 @@ For example, analytic signed distance functions can also be embedded in BVHs, pr
 
 .. note::
 
-   EBGeometry is not limited to binary trees, but supports :math:`k` -ary trees where each regular node has :math:`k` child nodes. 
+   ``EBGeometry`` is not limited to binary trees, but supports :math:`k` -ary trees where each regular node has :math:`k` child nodes. 
 
 Construction
 ------------
@@ -203,7 +203,7 @@ Although the rules for BVH construction are highly flexible, performant BVHs are
 * **Balanced**, in the sense that the tree depth does not vary greatly through the tree, and there is approximately the same number of primitives in each leaf node. 
 
 Construction of a BVH is usually done recursively, from top to bottom (so-called top-down construction).
-Alternative construction methods also exist, but are not used in EBGeometry. 
+Alternative construction methods also exist, but are not used in ``EBGeometry``. 
 In this case one can represent the BVH construction of a :math:`k` -ary tree is done through a single function:
 
 .. math::
@@ -255,7 +255,7 @@ For the traversal algorithm we consider the following steps:
    For example, it is necessary to traverse almost the entire tree when one tries to compute the signed distance at the origin of a tessellated sphere.
 
 Note that types of tree traversal (that do not compute the signed distance) are also possible, e.g. we may want to compute the union :math:`I\left(\mathbf{x}\right) = \min\left(I_1\left(\mathbf{x}\right), I_2\left(\mathbf{x}\right), .\ldots\right)`.
-EBGeometry supports a fairly flexible approach to the tree traversal and update algorithms.
+``EBGeometry`` supports a fairly flexible approach to the tree traversal and update algorithms.
 
 Octree
 ======
@@ -268,7 +268,7 @@ Octree construction can be done in (at least) two ways:
 #. In depth-first order where entire sub-trees are built first.
 #. In breadth-first order where tree levels are added one at a time.
 
-EBGeometry supports both of these methods. 
+``EBGeometry`` supports both of these methods. 
 Octree traversal is generally speaking quite similar to the traversal algorithms used for BVH trees.
 
 Constructive solid geometry
@@ -278,7 +278,7 @@ Basic transformations
 ---------------------
 
 Implicit functions, and by extension also signed distance fields, can be manipulated using basic transformations (like rotations).
-EBGeometry supports many of these:
+``EBGeometry`` supports many of these:
 
 * Rotations.
 * Translations.
@@ -294,11 +294,11 @@ EBGeometry supports many of these:
 Combining objects
 -----------------
 
-EBGeometry supports standard operations in which implicit functions can be combined:
+``EBGeometry`` supports standard operations in which implicit functions can be combined:
 
 * Union.
 * Intersection.
 * Difference.
 
 Some of these CSG operations also have smooth equivalents, i.e. for smoothing the transition between combined objects.
-Fast CSG operations are also supported by EBGeometry, e.g. the BVH-accelerated CSG union where one uses the BVH when searching for the relevant geometric primitive(s). 
+Fast CSG operations are also supported by ``EBGeometry``, e.g. the BVH-accelerated CSG union where one uses the BVH when searching for the relevant geometric primitive(s). 

Docs/Sphinx/source/Examples.rst

@@ -1,14 +1,14 @@
 .. _Chap:Examples:
 
-Below, we consider a few examples that show how to use EBGeometry.
+Below, we consider a few examples that show how to use ``EBGeometry``.
 All the examples are located in the :file:`Examples` folder.
 For instructions on how to compile and run the examples, refer to the README file in the example folder.
 
 EBGeometry
 ==========
 
-EBGeometry-specified examples are given in :file:`Examples/EBGeometry_<something>`.
-These examples display most of the EBGeometry functionality:
+``EBGeometry``-specified examples are given in :file:`Examples/EBGeometry_<something>`.
+These examples display most of the ``EBGeometry`` functionality:
 
 * Generating analytic implicit or signed distance functions.
 * Representation of surface grids as signed distance functions.
@@ -21,10 +21,10 @@ AMReX
 =====
 
 The AMReX examples are given in :file:`Examples/AMReX_<something>`.
-These examples are intended to expose the same features as the EBGeometry-specific examples.
+These examples are intended to expose the same features as the ``EBGeometry``-specific examples.
 
 Chombo3
 =======
 
 The Chombo-3 examples are given in :file:`Examples/Chombo3_<something>`.
-These examples are intended to expose the same features as the EBGeometry-specific examples.
+These examples are intended to expose the same features as the ``EBGeometry``-specific examples.

Docs/Sphinx/source/ImplemBVH.rst

@@ -32,7 +32,7 @@ The compact BVH is discussed below in :ref:`Chap:LinearBVH`.
 Bounding volumes
 ----------------
 
-EBGeometry supports the following bounding volumes, which are defined in :file:`EBGeometry_BoundingVolumes.hpp``:
+``EBGeometry`` supports the following bounding volumes, which are defined in :file:`EBGeometry_BoundingVolumes.hpp`:
 
 *  **BoundingSphere**, templated as ``EBGeometry::BoundingVolumes::BoundingSphereT<T>`` and describes a bounding sphere.
    Various constructors are available.
@@ -56,7 +56,7 @@ The second step is to recursively build the BVH, which is done through the funct
 
 .. literalinclude:: ../../../Source/EBGeometry_BVH.hpp
    :language: c++
-   :lines: 28, 62-94, 217-227, 248-257, 263-268, 274-285, 404, 643
+   :lines: 29, 62-94, 217-227, 248-257, 263-268, 274-285, 404, 643,644
    :caption: Header section of the BVH implementation.
 
 The optional input arguments to ``topDownSortAndPartition`` are polymorphic functions of type indicated above, and have the following responsibilities:
@@ -73,7 +73,7 @@ Default arguments for these are provided, bubt users are free to partition their
 Compact form
 ------------
 
-In addition to the standard BVH node ``NodeT<T, P, BV, K>``, EBGeometry provides a more compact formulation of the BVH hierarchy where the nodes are stored in depth-first order.
+In addition to the standard BVH node ``NodeT<T, P, BV, K>``, ``EBGeometry`` provides a more compact formulation of the BVH hierarchy where the nodes are stored in depth-first order.
 The "linearized" BVH can be automatically constructed from the standard BVH but not vice versa.
 
 .. figure:: /_static/CompactBVH.png

Docs/Sphinx/source/ImplemCSG.rst

@@ -6,13 +6,13 @@ Geometry representation
 Implicit functions
 ------------------
 
-EBGeometry implements implement functions and signed distance functions through virtual classes
+``EBGeometry`` implements implement functions and signed distance functions through virtual classes
 
 .. literalinclude:: ../../../Source/EBGeometry_ImplicitFunction.hpp
    :language: c++
    :lines: 25-74
 
-and for the signed distance field,
+Signed distance fields inherit from implicit functions as follows:
 
 .. literalinclude:: ../../../Source/EBGeometry_SignedDistanceFunction.hpp
    :language: c++

Docs/Sphinx/source/ImplemDCEL.rst

@@ -10,7 +10,7 @@ The DCEL functionality exists under the namespace ``EBGeometry::DCEL`` and conta
 
 .. important::
 
-   The DCEL functionality is *not* restricted to triangles, but supports N-sided polygons. 
+   The DCEL functionality is *not* restricted to triangles, but supports N-sided polygons, including *meta-data* attached to the vertices, edges, and facets. 
 
 Main types
 ----------
@@ -21,7 +21,7 @@ The main DCEL functionality (vertices, edges, faces) is provided by the followin
 
   .. code-block:: c++
 
-     template <class T>
+     template <class T, class Meta>
      class VertexT
 
   The DCEL vertex class stores the vertex position, normal vector, and the outgoing half-edge from the vertex.
@@ -33,7 +33,7 @@ The main DCEL functionality (vertices, edges, faces) is provided by the followin
 
   .. code-block:: c++
 
-     template <class T>
+     template <class T, class Meta>
      class EdgeT
 
   The half-edges store a reference to their face, as well as pointers to the next edge, pair edge, and starting vertex.
@@ -44,7 +44,7 @@ The main DCEL functionality (vertices, edges, faces) is provided by the followin
 
   .. code-block:: c++
 
-     template <class T>
+     template <class T, class Meta>
      class FaceT
 
   Faces also store
@@ -62,7 +62,7 @@ The main DCEL functionality (vertices, edges, faces) is provided by the followin
 
   .. code-block:: c++
 
-     template <class T>
+     template <class T, class Meta>
      class MeshT : public SignedDistanceFunction<T>
 
   The mesh stores all the vertices, half-edges, and faces, and if it is watertight and orientable it is also a signed distance function.
@@ -77,10 +77,13 @@ The above DCEL classes have member functions of the type:
 
 which can be used to compute the distance to the various features on the mesh.
 
+Meta-data can be attached to the DCEL primitives by selecting an appropriate type for ``Meta`` above (which defaults to ``short``). 
+
+
 .. _Chap:BVHIntegration:
 
 BVH integration
 ---------------
 
 DCEL grids can easily be embedded in BVHs by enclosing bounding volumes around the polygons (e.g., triangles).
-Partitioning and bounding volume constructors are provided in :file:`Source/EBGeometry_DCEL_BVH.hpp`.
+Partitioning and bounding volume constructors are provided in :file:`Source/EBGeometry_MeshDistanceFunctions.hpp`.

Docs/Sphinx/source/ImplemOctree.rst

@@ -11,7 +11,7 @@ Octrees are encapsulated by a class
 
 .. literalinclude:: ../../../Source/EBGeometry_Octree.hpp
    :language: c++
-   :lines: 71-72
+   :lines: 74-75
 
 
 where the template parameters are:
@@ -30,15 +30,15 @@ where the template parameters are:
 Construction
 ------------
 
-Constructing the octree is done by first initializing the root node and then building it in either depth-first or breadth-first ordering:
+Constructing the octree is done by first initializing the root node and then building it in either depth-first or breadth-first ordering.
 
 .. literalinclude:: ../../../Source/EBGeometry_Octree.hpp
    :language: c++
-   :lines: 71-73,80-81,87-88,94-96,180-184,191-194,226
+   :lines: 74-76, 83, 90, 97-98,104,111,117-118,183-187,194-198,229,230
 
 The input functions to ``buildDepthFirst`` and ``buildBreadthFirst`` are as follows:
 
-#.  ``StopFunction`` determines if the node should be split or not. If it returns true, the node will *not* be split.
+#. ``StopFunction`` determines if the node should be split or not. If it returns true, the node will *not* be split.
 #. ``MetaConstructor`` constructs meta-data in the child nodes. This can/should include the physical corners of the node, but this is not a requirement.
 #. ``DataConstructor`` constructs data in the child node. This can e.g. be a partitioning of the parent data.
 
@@ -47,7 +47,7 @@ Tree traversal
 
 .. literalinclude:: ../../../Source/EBGeometry_Octree.hpp
    :language: c++
-   :lines: 71-73,101-102,108-109,114-115,202-208,226
+   :lines: 74-76,205-211,239
 
 The input functions to ``traverse`` are as follows:
 

Docs/Sphinx/source/ImplemVec.rst

@@ -3,7 +3,7 @@
 Vector types
 ============
 
-EBGeometry implements its own 2D and 3D vector types ``Vec2T`` and ``Vec3T``. 
+``EBGeometry`` implements its own 2D and 3D vector types ``Vec2T`` and ``Vec3T``. 
 
 ``Vec2T`` is a two-dimensional Cartesian vector.
 It is templated as
@@ -19,7 +19,7 @@ It is templated as
       };
    }
 
-Most of EBGeometry is written as three-dimensional code, but ``Vec2T`` is needed for DCEL functionality when determining if a point projects onto the interior or exterior of a planar polygon, see :ref:`Chap:DCEL`. 
+Most of ``EBGeometry`` is written as three-dimensional code, but ``Vec2T`` is needed for DCEL functionality when determining if a point projects onto the interior or exterior of a planar polygon, see :ref:`Chap:DCEL`. 
 ``Vec2T`` has "most" common arithmetic operators like the dot product, length, multiplication operators and so on.
 
 ``Vec3T`` is a three-dimensional Cartesian vector type with precision ``T``.

Docs/Sphinx/source/Implementation.rst

@@ -3,7 +3,7 @@
 Overview
 ========
 
-Here, we consider the basic EBGeometry API.
-EBGeometry is a header-only library, implemented under its own namespace ``EBGeometry``.
+Here, we consider the basic ``EBGeometry`` API.
+``EBGeometry`` is a header-only library, implemented under its own namespace (``EBGeometry``).
 Various major components, like BVHs and DCEL, are implemented under namespaces ``EBGeometry::BVH`` and ``EBGeometry::DCEL``.
-Below, we consider a brief introduction to the API and implementation details of EBGeometry.
+Below, we consider a brief introduction to the API and implementation details of ``EBGeometry``.

Docs/Sphinx/source/Introduction.rst

@@ -5,28 +5,28 @@ Requirements
 
 * A C++ compiler which supports C++14.
 
-EBGeometry is a header-only library and is comparatively simple to set up and use. 
+``EBGeometry`` is a header-only library and is comparatively simple to set up and use. 
 To use it, make :file:`EBGeometry.hpp` (stored at the top level) visible to your code and include it.  
 
 Quickstart
 ==========
 
-To obtain EBGeometry, clone the code from `github <https://github.com/rmrsk/EBGeometry>`_:
+To obtain ``EBGeometry``, clone the code from `github <https://github.com/rmrsk/EBGeometry>`_:
 
 .. code-block:: bash
 
    git clone git@github.com:rmrsk/EBGeometry.git
 
-To compile the EBGeometry example codes, navigate to the EBGeometry/Examples folder.
-Folders that are named ``EBGeometry_<something>`` are pure ``EBGeometry`` examples and can be compiled without any third-party dependencies.
+To compile the ``EBGeometry`` example codes, navigate to the :file:`EBGeometry/Examples` folder.
+Folders that are named :file:`EBGeometry_<something>` are pure ``EBGeometry`` examples and can be compiled without any third-party dependencies.
 
-To run the EBGeometry examples, navigate to one of the folders and execute
+To run the ``EBGeometry`` examples, navigate to one of the folders and execute
 
 .. code-block:: bash
 
    g++ -O3 -std=c++17 main.cpp && ./a.out
 
-All EBGeometry examples should run using this command.
+All ``EBGeometry`` examples should run using this command.
 README files present in each folder provide more information regarding the functionality and usage of each example code.
 
 Third-party examples