documentation for volume mesh prism and pyramid element types (#18)

* Adding in some documentation on additional element types

* new cell indexing diagram

* docs wording tweaks

* adjust cell diagrams

* update volume mesh cell type docs

* fix video url

* clarify padding is -1

---------

Co-authored-by: Nicholas Sharp <nmwsharp@gmail.com>

Author: mgsutton

cpp/source/structures/volume_mesh/basics.md

@@ -1,9 +1,11 @@
 # Volume Meshes
 
-Volumetric meshes, such as tetrahedral (*tet*) and hexahedral (*hex*, cube-like) meshes, represent a region of 3D space. Polyscope can display tet and hex meshes, including those which have a mix of hex and tet elements. We'll use the term *cell* to refer generically to a tet or hex in a volume mesh. As always, Polyscope can also handle scalar, color, or vector quantities associated with the vertices or cells of the mesh, and you can click on the mesh elements to inspect values.
+Visualize volumetric 3D meshes, with tetrahedral and hexahedral (cube-like) elements, or even more general prism or pyramidal elements. Meshes may be pure tet/hex/etc, or a mixture of different element types---we'll use the term *cell* to refer generically to either a tet, hex, prism or pyramid element in a volume mesh.
+
+As always, Polyscope can visualize the mesh itself, as well as any combination of scalar, color, or vector quantities associated with the vertices or cells of the mesh. Try clicking on the mesh to inspect the value of any quantity at that location, or using *slice planes* to inspect the internal structure and quantities defined within.
 
 <video width=100% autoplay muted loop>
-  <source src="/media/movies/volume_demo_compress.mp4" type="video/mp4">
+  <source src="[[url.prefix]]/media/movies/volume_demo_compress.mp4" type="video/mp4">
   Your browser does not support the video tag.
 </video>
 
@@ -40,9 +42,9 @@ polyscope::getVolumeMesh("my mesh")->addVertexScalarQuantity("scalar Q", scalarV
 polyscope::show();
 ```
 
-Volume meshes are registered with Polyscope by passing the location of each vertex in the mesh, as well as the vertex indices for each cell. There are a few different variants to register meshes with tets, hexes, or a mix of the two. All of these register helpers return a pointer to a `polyscope::VolumeMesh` object which you can then add quantities to.
+Volume meshes are registered with Polyscope by passing the location of each vertex in the mesh, as well as the vertex indices for each cell. There are a few different variants to register meshes with pure tets and hexes, or a more general mixture of tets, hexes, prisms and pyramids. All of these register helpers return a pointer to a `polyscope::VolumeMesh` object which you can then add quantities to.
 
-![tet element ordering conventions]([[url.prefix]]/media/tet_element_orderings.jpg)
+![element ordering conventions]([[url.prefix]]/media/volume_mesh_element_orderings.jpg)
 
 ???+ func "`#!cpp polyscope::registerTetMesh(std::string name, const V& vertexPositions, const C& tetIndices)`"
 
@@ -60,19 +62,21 @@ Volume meshes are registered with Polyscope by passing the location of each vert
 
     - `hexIndices` is the 2D array of vertex indices for each hexahedral cell, with dimension `(C,8)` where `C` is the number of hexes. The type should be [adaptable]([[url.prefix]]/data_adaptors) to a nested array of `size_t`; this allows many common types to be used as input, including `Eigen::MatrixXi` and `std::vector<std::array<size_t, 8>>`. All indices should be valid 0-based indices in to the vertex list.
 
-??? func "`#!cpp polyscope::registerVolumeMesh(std::string name, const V& vertexPositions, const C& hexIndices)`"
+??? func "`#!cpp polyscope::registerVolumeMesh(std::string name, const V& vertexPositions, const C& cellIndices)`"
 
-    Add a new volume mesh structure to Polyscope, which may have a mix of cell types. This variant takes a rectangular array as input, where all cell rows have 8 entries, but cells with less than 8 vertices are padded with negative values.
+    Add a new volume mesh structure to Polyscope, with a general mix of cell types.
+    
+    This variant takes a rectangular array as input, where all cell rows have 8 entries, but cells which are specified by less than 8 vertices are padded with `-1`.
     
-    For instance, a row of the 2D array `hexIndices` which refers to a tet cell might hold `[12, 9, 22, 51, -1, -1, -1, -1]`.
+    For instance, a row of the 2D array `cellIndices` which refers to a tet cell might hold `[12, 9, 22, 51, -1, -1, -1, -1]`.  A row in the 2D array `cellIndices` which refers to a prism cell might hold `[18, 32, 51, 17, 85, 23, -1, -1]`, etc.
 
     - `vertexPositions` is the vector array of 3D vertex locations. The type should be [adaptable]([[url.prefix]]/data_adaptors) to an array of `float`-valued 3-vectors; this allows many common types to be used as input, including `Eigen::MatrixXd` and `std::vector<std::array<double, 3>>`. The length will be the number of vertices.
 
-    - `hexIndices` is the 2D array of vertex indices for each hexahedral cell, with dimension `(C,8)` where `C` is the number of tet/hexes. For tet elements, the rows of the array should be padded with negative indices, which will be ignored. The type should be [adaptable]([[url.prefix]]/data_adaptors) to a nested array of `unsigned int`; this allows many common types to be used as input, including `Eigen::MatrixXi` and `std::vector<std::array<int, 8>>`. All indices should be valid 0-based indices in to the vertex list. Signed types should be used to support the negative element convention as described above.
+    - `cellIndices` is the 2D array of vertex indices for each cell, with dimension `(C,8)` where `C` is the number of cells. For tet, prism and pyramid elements, the rows of the array should be right-padded with `-1` as appropriate for the cell topology. The type should be [adaptable]([[url.prefix]]/data_adaptors) to a nested array of `unsigned int`; this allows many common types to be used as input, including `Eigen::MatrixXi` and `std::vector<std::array<int, 8>>`. All indices should be valid 0-based indices in to the vertex list, except padding entries which must be `-1`. Signed types should be used to support the `-1` padding convention. (NOTE: internally cell indices use `UINT32_MAX` for invalid entries, but you should pass padding as `-1` via a signed type to the input adaptor.)
 
 ??? func "`#!cpp polyscope::registerTetHexMesh(std::string name, const V& vertexPositions, const Ct& tetIndices, const Ct& hexIndices)`"
 
-    Add a new volume mesh structure to Polyscope. This variant takes a mix of tet and hex elements, where each are given in their own separate list.
+    Add a new volume mesh structure to Polyscope. This variant takes a mix of tet and hex elements, where each are given in their own separate list. Note that prisms and pyramids are also supported by the class, but not this constructor; use the general variant.
 
     - `vertexPositions` is the vector array of 3D vertex locations. The type should be [adaptable]([[url.prefix]]/data_adaptors) to an array of `float`-valued 3-vectors; this allows many common types to be used as input, including `Eigen::MatrixXd` and `std::vector<std::array<double, 3>>`. The length will be the number of vertices.
     

py/source/structures/volume_mesh/basics.md

@@ -1,9 +1,9 @@
 # Volume Meshes
 
-Volumetric meshes, such as tetrahedral (*tet*) and hexahedral (*hex*, cube-like) meshes, represent a region of 3D space. Polyscope can display tet and hex meshes, including those which have a mix of hex and tet elements. We'll use the term *cell* to refer generically to a tet or hex in a volume mesh. As always, Polyscope can also handle scalar, color, or vector quantities associated with the vertices or cells of the mesh, and you can click on the mesh elements to inspect values.
+Visualize volumetric 3D meshes, with tetrahedral and hexahedral (cube-like) elements, or even more general prism or pyramidal elements. Meshes may be pure tet/hex/etc, or a mixture of different element types---we'll use the term *cell* to refer generically to either a tet, hex, prism or pyramid element in a volume mesh. As always, Polyscope can also handle scalar, color, or vector quantities associated with the vertices or cells of the mesh, and you can click on the mesh elements to inspect values, or use *slice planes* to inspect the internal structure.
 
 <video width=100% autoplay muted loop>
-  <source src="/media/movies/volume_demo_compress.mp4" type="video/mp4">
+  <source src="[[url.prefix]]/media/movies/volume_demo_compress.mp4" type="video/mp4">
   Your browser does not support the video tag.
 </video>
 
@@ -37,9 +37,9 @@ ps_vol.add_scalar_quantity("my cell val", data_cell, defined_on='cells',
 ps.show() 
 ```
 
-Volume meshes are registered with Polyscope by passing the location of each vertex in the mesh, as well as the vertex indices for each cell. There are a few different argument variants to register meshes with tets, hexes, or a mix of the two. 
+Volume meshes are registered with Polyscope by passing the location of each vertex in the mesh, as well as the vertex indices for each cell. There are a few different argument variants to register meshes with tets, hexes, or a general mix of element types.
 
-![tet element ordering conventions]([[url.prefix]]/media/tet_element_orderings.jpg)
+![element ordering conventions]([[url.prefix]]/media/tet_element_orderings.jpg)
 
 
 
@@ -50,13 +50,15 @@ Volume meshes are registered with Polyscope by passing the location of each vert
     - `name` string, a name for the structure
     - `vertices` an `Nx3` numpy float array of vertex locations 
 
-    The elements are specified by a combination of the following arguments:
+    The element indices are specified by some combination of the following arguments:
 
     - `tets` a `Tx4` numpy integer array of tetrahedra, as 0-based indices in to the vertices array
     - `hexes` a `Hx8` numpy integer array of hexahedra, as 0-based indices in to the vertices array
-    - `mixed_cells` a `Mx8` numpy integer array which may contain a mix of tetrahedra and hexahedra. For any rows which are tets and thus have just 4 indices, the remaining indices should be set to any negative value.
+    - `mixed_cells` a `Mx8` numpy integer array which may contain a mix of tet, hex, prism, and pyramid elements. Each row holds 8 entries; cells with fewer than 8 vertices are right-padded with `-1`. For example, a tet row might be `[12, 9, 22, 51, -1, -1, -1, -1]`, or a pyramid row might be `[3, 7, 14, 2, 19, -1, -1, -1]`.
 
-    You may pass in `tets`, `hexes`, or both to specify the connectivty. Alternately, `mixed_cells` may be used. However, it is not supported to specify both `tets`/`hexes` and `mixed_cells`.  For the purposes of element ordering, when `tets` and `hexes` are both passed, the cells are presumed to be ordered with all tetrahedral cells coming first, then hexahedral cells.
+    You may pass in `tets`, `hexes`, or both to specify the connectivity. Alternately, `mixed_cells` may be used for any combination of cell types, including pyramids and prisms as well. However, it is not supported to specify both `tets`/`hexes` and `mixed_cells`; just pass all cells as `mixed_cells` in this case.  
+    
+    For the purposes of element ordering, when `tets` and `hexes` are both passed, the cells are presumed to be ordered with all tetrahedral cells coming first, then hexahedral cells.
 
 
     Additional optional keyword arguments: