Add option invert_polyhedron_faces for pvgridder.MeshStack3D.generate_mesh()

[keurfonluu]

• Added: option invert_polyhedron_faces to ensure that polyhedral cells have no inverted faces (see cell_centers() returns wrong points i.e. outside of the convex hull of the mesh pyvista/pyvista#8129 (comment)). Note that VTK mesh validator may still flag some cells as having inverted faces. For instance:

import pyvista as pv
import pvgridder as pvg

terrain = pv.examples.download_crater_topo().extract_subset((500, 900, 400, 800, 0, 0), (50, 50, 1))
terrain_delaunay = pvg.Polygon(terrain, celltype="triangle")
terrain = terrain.cast_to_structured_grid().warp_by_scalar("scalar1of1")
bgmesh = pvg.VoronoiMesh2D(terrain_delaunay, preference="point").generate_mesh()
mesh = (
    pvg.MeshStack3D(bgmesh)
    .add(0.0)
    .add(terrain.translate((0.0, 0.0, -1000.0)), 1, method="log_r", group="Bottom layer")
    .add(500.0, 1, group="Middle layer")
    .add(terrain, 2, method="log", group="Top Layer")
    .generate_mesh(invert_polyhedron_faces=True)
)
report = mesh.validate_mesh(action="warn")

InvalidMeshWarning: UnstructuredGrid mesh is not valid due to the following problems:
 - Mesh has 43 non-convex cells. Invalid cell ids: [12, 33, 45, 48, 50, 61, ...]
 - Mesh has 2 cells with inverted faces. Invalid cell ids: [103, 152]

The report flags cell 103 as having inverted faces (meaning that their normals point inwards). However, when plotting the normal vectors of the faces of cell 103, we can see that the normals are pointing outwards.

cell = mesh.extract_cells(103).extract_geometry()
cell.plot_normals(mag=200, faces=True, color="red", style="wireframe")

With invert_polyhedron_faces=False, the normal vectors point inwards, meaning that enabling this option correctly inverts the faces.

InvalidMeshWarning: UnstructuredGrid mesh is not valid due to the following problems:
 - Mesh has 392 non-convex cells. Invalid cell ids: [0, 1, 2, 3, 4, 5, ...]
 - Mesh has 392 cells with inverted faces. Invalid cell ids: [0, 1, 2, 3, 4, 5, ...]

Reminders:

• Run invoke ruff to make sure the code follows the style guide,
• Add tests for new features or tests that would have caught the bug that you're fixing,
• Write detailed docstrings for all functions, classes and/or methods,
• If adding new functionality, unit test it and add it to the documentation.