Update EBGeometry file parser and support more file types (#83)

Author: rmrsk

CheckDocs.py

@@ -0,0 +1,52 @@
+import os
+import subprocess
+import re
+from pathlib import Path
+
+def get_changed_files(base_branch="main"):
+    """Get list of changed .cpp, .hpp, .options, and .inputs files compared to base branch."""
+    result = subprocess.run(
+        ["git", "diff", "--name-only", base_branch],
+        capture_output=True,
+        text=True,
+        check=True
+    )
+    files = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+    exts = (".cpp", ".hpp", ".options", ".inputs", ".md")
+    return [str(Path(f).resolve()) for f in files if f.endswith(exts)]
+
+def find_literalincludes(rst_dir, changed_files):
+    """Search .rst files for literalinclude directives referencing changed files."""
+    includes_found = []
+
+    for rst_path in Path(rst_dir).rglob("*.rst"):
+        with open(rst_path, encoding="utf-8") as f:
+            for lineno, line in enumerate(f, start=1):
+                match = re.match(r"\s*\.\.\s+literalinclude::\s+(.*)", line)
+                if match:
+                    included_file = match.group(1).strip()
+                    # Resolve relative path from rst file location
+                    included_path = (rst_path.parent / included_file).resolve()
+                    if str(included_path) in changed_files:
+                        includes_found.append(
+                            (rst_path, lineno, included_file, included_path)
+                        )
+    return includes_found
+
+if __name__ == "__main__":
+    base_branch = "main"
+    rst_dir = "Docs/Sphinx/source"
+
+    changed_files = get_changed_files(base_branch)
+    if not changed_files:
+        print(f"No changed .cpp, .hpp, .options, .inputs, or .md files compared to {base_branch}")
+        exit(0)
+
+    includes = find_literalincludes(rst_dir, changed_files)
+
+    if includes:
+        print("Found literalincludes referencing changed files:\n")
+        for rst_file, line, included, resolved in includes:
+            print(f"{rst_file}:{line} -> includes '{included}' (resolved: {resolved})")
+    else:
+        print("No literalinclude directives reference changed files.")

Docs/Sphinx/source/Parsers.rst

@@ -6,15 +6,16 @@ Reading data
 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::
+.. important::
 
-   ``EBGeometry`` is currently limited to reading binary and ASCII STL files and reconstructing DCEL grids from those.
-   However, it is also possible to build DCEL grids from polygon soups read using third-party codes (see :ref:`Chap:ThirdPartyParser`).
+   ``EBGeometry`` is currently limited to reading STL, PLY, and VTK files, and then reconstructing DCEL grids from those.
+   PLY and and VTK files can contain associated data on the nodes and faces, but this is not automatically populated when constructing the DCEL grids. 
+   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 or multiple STL files, you can quickly turn them into signed distance fields using
+If you have one or multiple files, you can quickly turn them into signed distance fields using
 
 .. code-block:: c++
 
@@ -37,46 +38,52 @@ See :ref:`Chap:LinearSTL` for further details.
 
    This version will convert all DCEL polygons to triangles, and usually provides a nice code speedup.
 
-Reading STL files
------------------
+Reading mesh files
+------------------
 
-``EBGeometry`` supports a native parser for binary and ASCII STL files, which can be read into a few different representations:
+``EBGeometry`` supports a native parser for binary and ASCII files, which can be read into a few different representations:
 
 #. Into a DCEL mesh, see :ref:`Chap:ImplemDCEL`.
 #. Into a signed distance function representation of a DCEL mesh, see :ref:`Chap:ImplemCSG`.
 #. Into a signed distance function representation of a DCEL mesh, but using a BVH accelerator in full representation.
-#. Into a signed distance function representation of a DCEL mesh, but using a BVH accelerator in compact representation.    
+#. Into a signed distance function representation of a DCEL mesh, but using a BVH accelerator in compact representation.
+
+.. important::
+
+   The ``EBGeometry`` parser will read input files into internal objects that represent each file type.
+   Conversion of these objects into DCEL meshes is not required, and it is possible to creating bounding volume hierarchies directly from the facets.
+   This is useful when only an acceleration structure is needed for looking up facets or triangles, but no signed distance function is otherwise required. 
 
 DCEL representation
 ___________________
 
-To read one or multiple STL files and turn it into DCEL meshes, use
+To read one or multiple files and turn it into DCEL meshes, use
 
 .. literalinclude:: ../../../Source/EBGeometry_Parser.hpp
    :language: c++
-   :lines: 54-68
+   :lines: 124-138
    :dedent: 2	   
 
 Note that this will only expose the DCEL mesh, but not include any signed distance functionality.
 
 DCEL mesh SDF
 _____________
 
-To read one or multiple STL files and also turn it into signed distance representations, use
+To read one or multiple files and also turn it into signed distance representations, use
 
 .. literalinclude:: ../../../Source/EBGeometry_Parser.hpp
    :language: c++
-   :lines: 70-84
+   :lines: 140-154
    :dedent: 2	   
 
 DCEL mesh SDF with full BVH
 ___________________________
 
-To read one or multiple STL files and turn it into signed distance representations using a full BVH representation, use
+To read one or multiple files and turn it into signed distance representations using a full BVH representation, use
 
 .. literalinclude:: ../../../Source/EBGeometry_Parser.hpp
    :language: c++
-   :lines: 86-106
+   :lines: 156-176
    :dedent: 2	   
 
 .. _Chap:LinearSTL:
@@ -88,18 +95,18 @@ To read one or multiple STL files and turn it into signed distance representatio
 
 .. literalinclude:: ../../../Source/EBGeometry_Parser.hpp
    :language: c++
-   :lines: 107-128
+   :lines: 178-198
    :dedent: 2
 
 
 Triangle meshes with BVH
 ________________________
 
-To read one or multiple STL files and turn it into signed distance representations using a compact BVH representation, use
+To read one or multiple files and turn it into signed distance representations using a compact BVH representation, use
 
 .. literalinclude:: ../../../Source/EBGeometry_Parser.hpp
    :language: c++
-   :lines: 130-147
+   :lines: 200-217
    :dedent: 2	   
 
 This version differs from the DCEL meshes in that each DCEL polygon is converted into triangles after parsing.
@@ -122,9 +129,9 @@ Here, ``vertices`` contains the :math:`x,y,z` coordinates of each vertex, while
 
 To turn this into a DCEL mesh, one should compress the triangle soup (get rid of duplicate vertices) and then construct the DCEL mesh:
 
-.. literalinclude:: ../../../Source/EBGeometry_Parser.hpp
+.. literalinclude:: ../../../Source/EBGeometry_Soup.hpp
    :language: c++
-   :lines: 182-201
+   :lines: 37-56
    :dedent: 2
 
 The ``compress`` function will discard duplicate vertices from the soup, while the ``soupToDCEL`` will tie the remaining polygons into a DCEL mesh.

EBGeometry.hpp

@@ -13,6 +13,7 @@
 #include "Source/EBGeometry_SFC.hpp"
 #include "Source/EBGeometry_SignedDistanceFunction.hpp"
 #include "Source/EBGeometry_SimpleTimer.hpp"
+#include "Source/EBGeometry_Soup.hpp"
 #include "Source/EBGeometry_Transform.hpp"
 #include "Source/EBGeometry_Triangle.hpp"
 

Examples/AMReX_DCEL/main.cpp

@@ -103,36 +103,36 @@ main(int argc, char* argv[])
 
       if (which_geom == 0) { // Airfoil case
         rb       = RealBox({-100, -100, -75}, {400, 100, 125});
-        filename = "../Resources/airfoil.stl";
+        filename = "../Resources/airfoil_binary.stl";
       }
       else if (which_geom == 1) { // Sphere case
         rb       = RealBox({-400, -400, -400}, {400, 400, 400});
-        filename = "../Resources/sphere.stl";
+        filename = "../Resources/sphere_binary.stl";
       }
       else if (which_geom == 2) { // Dodecahedron
         rb       = RealBox({-2., -2., -2.}, {2., 2., 2.});
-        filename = "../Resources/dodecahedron.stl";
+        filename = "../Resources/dodecahedron_binary.stl";
       }
       else if (which_geom == 3) { // Horse
         rb       = RealBox({-0.12, -0.12, -0.12}, {0.12, 0.12, 0.12});
-        filename = "../Resources/horse.stl";
+        filename = "../Resources/horse_binary.stl";
       }
       else if (which_geom == 4) { // Car
         //	    rb = RealBox({-20,-20,-20}, {20,20,20}); // Doesn't work.
         rb       = RealBox({-10, -5, -5}, {10, 5, 5}); // Works.
-        filename = "../Resources/porsche.stl";
+        filename = "../Resources/porsche_binary.stl";
       }
       else if (which_geom == 5) { // Orion
         rb       = RealBox({-10, -5, -10}, {10, 10, 10});
-        filename = "../Resources/orion.stl";
+        filename = "../Resources/orion_binary.stl";
       }
       else if (which_geom == 6) { // Armadillo
         rb       = RealBox({-100, -75, -100}, {100, 125, 100});
-        filename = "../Resources/armadillo.stl";
+        filename = "../Resources/armadillo_binary.stl";
       }
       else if (which_geom == 7) { // Adirondacks
         rb       = RealBox({0, 0, 0}, {200, 200, 50});
-        filename = "../Resources/adirondack.stl";
+        filename = "../Resources/adirondack_binary.stl";
       }
 
       Array<int, AMREX_SPACEDIM> is_periodic{false, false, false};

Examples/AMReX_PaintEB/main.cpp

@@ -114,36 +114,36 @@ main(int argc, char* argv[])
 
   if (which_geom == 0) { // Airfoil case
     rb       = RealBox({-100, -100, -75}, {400, 100, 125});
-    filename = "../Resources/airfoil.stl";
+    filename = "../Resources/airfoil_binary.stl";
   }
   else if (which_geom == 1) { // Sphere case
     rb       = RealBox({-400, -400, -400}, {400, 400, 400});
-    filename = "../Resources/sphere.stl";
+    filename = "../Resources/sphere_binary.stl";
   }
   else if (which_geom == 2) { // Dodecahedron
     rb       = RealBox({-2., -2., -2.}, {2., 2., 2.});
-    filename = "../Resources/dodecahedron.stl";
+    filename = "../Resources/dodecahedron_binary.stl";
   }
   else if (which_geom == 3) { // Horse
     rb       = RealBox({-0.12, -0.12, -0.12}, {0.12, 0.12, 0.12});
-    filename = "../Resources/horse.stl";
+    filename = "../Resources/horse_binary.stl";
   }
   else if (which_geom == 4) { // Car
     //	    rb = RealBox({-20,-20,-20}, {20,20,20}); // Doesn't work.
     rb       = RealBox({-10, -5, -5}, {10, 5, 5}); // Works.
-    filename = "../Resources/porsche.stl";
+    filename = "../Resources/porsche_binary.stl";
   }
   else if (which_geom == 5) { // Orion
     rb       = RealBox({-10, -5, -10}, {10, 10, 10});
-    filename = "../Resources/orion.stl";
+    filename = "../Resources/orion_binary.stl";
   }
   else if (which_geom == 6) { // Armadillo
     rb       = RealBox({-100, -75, -100}, {100, 125, 100});
-    filename = "../Resources/armadillo.stl";
+    filename = "../Resources/armadillo_binary.stl";
   }
   else if (which_geom == 7) { // Adirondacks
     rb       = RealBox({0, 0, 0}, {200, 200, 50});
-    filename = "../Resources/adirondack.stl";
+    filename = "../Resources/adirondack_binary.stl";
   }
 
   Array<int, AMREX_SPACEDIM> is_periodic{false, false, false};

Examples/Chombo3_DCEL/main.cpp

@@ -91,48 +91,48 @@ main(int argc, char* argv[])
     loCorner = -50 * RealVect::Unit;
     hiCorner = 250 * RealVect::Unit;
 
-    filename = "../Resources/airfoil.stl";
+    filename = "../Resources/airfoil_binary.stl";
   }
   else if (whichGeom == 1) { // Sphere
     loCorner = -400 * RealVect::Unit;
     hiCorner = 400 * RealVect::Unit;
 
-    filename = "../Resources/sphere.stl";
+    filename = "../Resources/sphere_binary.stl";
   }
   else if (whichGeom == 2) { // Dodecahedron
     loCorner = -2 * RealVect::Unit;
     hiCorner = 2 * RealVect::Unit;
 
-    filename = "../Resources/dodecahedron.stl";
+    filename = "../Resources/dodecahedron_binary.stl";
   }
   else if (whichGeom == 3) { // Horse
     loCorner = -0.12 * RealVect::Unit;
     hiCorner = 0.12 * RealVect::Unit;
 
-    filename = "../Resources/horse.stl";
+    filename = "../Resources/horse_binary.stl";
   }
   else if (whichGeom == 4) { // Porsche
     loCorner = -10 * RealVect::Unit;
     hiCorner = 10 * RealVect::Unit;
 
-    filename = "../Resources/porsche.stl";
+    filename = "../Resources/porsche_binary.stl";
   }
   else if (whichGeom == 5) { // Orion
     loCorner = -10 * RealVect::Unit;
     hiCorner = 10 * RealVect::Unit;
 
-    filename = "../Resources/orion.stl";
+    filename = "../Resources/orion_binary.stl";
   }
   else if (whichGeom == 6) { // Armadillo
     loCorner = -125 * RealVect::Unit;
     hiCorner = 125 * RealVect::Unit;
 
-    filename = "../Resources/armadillo.stl";
+    filename = "../Resources/armadillo_binary.stl";
   }
   else if (whichGeom == 7) { // Adirondacks
     loCorner = RealVect::Zero;
     hiCorner = 250 * RealVect::Unit;
-    filename = "../Resources/adirondack.stl";
+    filename = "../Resources/adirondack_binary.stl";
   }
 
   using Meta   = EBGeometry::DCEL::DefaultMetaData;

Examples/EBGeometry_DCEL/main.cpp

@@ -40,12 +40,14 @@ main(int argc, char* argv[])
   else {
     std::cout << "Missing file name. Use ./a.out 'filename' where 'filename' "
                  "is one of the files in ../Resources. Setting this equal to the armadillo file\n";
-    file = "../Resources/armadillo.stl";
+    file = "../Resources/armadillo_binary.stl";
   }
 
-  // Three representations of the same object. Note that this reads the mesh three
-  // times and builds the BVH twice (there are converters that avoid this, users will
-  // only use one of these representations).
+  // Representations of the same object. Note that this reads the mesh and builds the BVH
+  // tree multiple times.
+  //
+  // There are converters that avoid this, but users will almost always only use one of
+  // these representations.
   const auto dcelSDF = EBGeometry::Parser::readIntoMesh<T, Meta>(file);
   const auto bvhSDF  = EBGeometry::Parser::readIntoFullBVH<T, Meta, BV, K>(file);
   const auto linSDF  = EBGeometry::Parser::readIntoLinearBVH<T, Meta, BV, K>(file);

Examples/EBGeometry_F18/main.cpp

@@ -135,10 +135,12 @@ main(int argc, char* argv[])
 
   // Debug -- make sure all functions produce the same result!.
   if (std::abs(sumSlowSlow) - std::abs(sumFastFast) > std::numeric_limits<T>::min()) {
-    std::cerr << "Got wrong distance! Diff = " << std::abs(sumSlowFast) - std::abs(sumFastFast) << "\n";
+    std::cerr << "Got wrong slowslow-fastfast distance with diff = " << std::abs(sumSlowFast) - std::abs(sumFastFast)
+              << "\n";
   }
   if (std::abs(sumSlowSlow) - std::abs(sumFastSlow) > std::numeric_limits<T>::min()) {
-    std::cerr << "Got wrong distance! Diff = " << std::abs(sumSlowFast) - std::abs(sumFastSlow) << "\n";
+    std::cerr << "Got wrong slowslow-fastslow distance with diff = " << std::abs(sumSlowFast) - std::abs(sumFastSlow)
+              << "\n";
   }
 
   const std::chrono::duration<T, std::micro> slowSlowTime = (t1 - t0);

Examples/Resources/README.md

@@ -1,11 +1,12 @@
-This folder contains various surface grids, remarks on where the data was obtained, and what was done with it. 
+This folder contains various surface grids. The files that are listed below were obtained externally. See provided references. 
 
-| Model Name | Image | PLY file      | Source     | Note |
+| Model Name | Image | Base file     | Source     | Note |
 |------------|-------|---------------|------------|------|
-| Adirondack    | <img src="img/adirondack.png"   width="200"/> | [.stl](adirondack.stl)   | [GrabCAD](https://grabcad.com/library/adirondack-park-elevation-model-1) |                           |
-| Airfoil       | <img src="img/airfoil.png"      width="200"/> | [.stl](airfoil.stl)      | [AMReX](http://git@github.com/AMReX-Codes/amrex-tutorials.git)           |                           |
-| Armadillo     | <img src="img/armadillo.png"    width="200"/> | [.stl](armadillo.stl)    | [Stanford](http://graphics.stanford.edu/data/3Dscanrep/)                 |                           |
-| Dodecahedron  | <img src="img/dodecahedron.png" width="200"/> | [.stl](dodecahedron.stl) | [John Burkardt](https://people.sc.fsu.edu/~jburkardt/data/ply/ply.html)  |                           |
-| Horse         | <img src="img/horse.png"        width="200"/> | [.stl](horse.stl)        | [Alec Jacobson](https://github.com/alecjacobson/common-3d-test-models)   | Repaired using MeshLab    |
-| Orion         | <img src="img/orion.png"        width="200"/> | [.stl](orion.stl)        | [NASA](https://nasa3d.arc.nasa.gov/detail/orion-capsule)                 |                           |
-| Sphere        | <img src="img/sphere.png"       width="200"/> | [.stl](sphere.stl)       | [John Burkardt](https://people.sc.fsu.edu/~jburkardt/data/ply/ply.html)  |                           |
+| Adirondack    | <img src="img/adirondack.png"   width="200"/> | [.stl](adirondack_binary.stl)   | [GrabCAD](https://grabcad.com/library/adirondack-park-elevation-model-1) |                           |
+| Airfoil       | <img src="img/airfoil.png"      width="200"/> | [.stl](airfoil_binary.stl)      | [AMReX](http://git@github.com/AMReX-Codes/amrex-tutorials.git)           |                           |
+| Armadillo     | <img src="img/armadillo.png"    width="200"/> | [.stl](armadillo_binary.stl)    | [Stanford](http://graphics.stanford.edu/data/3Dscanrep/)                 |                           |
+| Dodecahedron  | <img src="img/dodecahedron.png" width="200"/> | [.stl](dodecahedron_binary.stl) | [John Burkardt](https://people.sc.fsu.edu/~jburkardt/data/ply/ply.html)  |                           |
+| Horse         | <img src="img/horse.png"        width="200"/> | [.stl](horse_binary.stl)        | [Alec Jacobson](https://github.com/alecjacobson/common-3d-test-models)   | Repaired using MeshLab    |
+| Orion         | <img src="img/orion.png"        width="200"/> | [.stl](orion_binary.stl)        | [NASA](https://nasa3d.arc.nasa.gov/detail/orion-capsule)                 |                           |
+| Sphere        | <img src="img/sphere.png"       width="200"/> | [.stl](sphere_binary.stl)       | [John Burkardt](https://people.sc.fsu.edu/~jburkardt/data/ply/ply.html)  |                           |
+