Documentation for level sets and volume slice planes

cpp/source/features/slice_planes.md

@@ -156,3 +156,13 @@ psMesh->setCullWholeElements(false);
 
     Test whether the cull whole elements setting is applied.
 
+
+### Slicing Volume Meshes
+
+When slicing geometry meshes, it is often useful to inspect geometry and quantities along the sliced plane within the mesh. To generate this geometry along a slice plane to "fill" the culled space, select the volume mesh you want to slice from the "Slice Volume Mesh" dropdown in the slice plane options. Scalar quantities on the surface of the mesh will also be propagated correctly onto the generated slice.
+
+??? func "`#!cpp void SlicePlane::setVolumeMeshToSlice(std::string name)`"
+
+    Set the volume mesh to slice for this plane. If the provided string is a valid name of a volume mesh in the scene, that slice plane will generate new geometry along the plane to fill in culled data.
+
+![volume mesh sliced]([[url.prefix]]/media/sliced_volume_mesh.png)

cpp/source/structures/volume_mesh/basics.md

@@ -25,9 +25,7 @@ Eigen::MatrixXi F; // faces (we don't use these here)
 igl::readMESH("path/to/volume.mesh", V, T, F);
 
 // Register the volume mesh with Polyscope
-polyscope::registerTetMesh("my mesh", V, T);
-
-// Add a scalar quantity
+polyscope::register![volume mesh color values]([[url.prefix]]/media/volume_color.jpg)ntity
 size_t nVerts = V.rows();
 std::vector<double> scalarV(nVerts);
 for (size_t i = 0; i < nVerts; i++) {
@@ -103,7 +101,8 @@ The locations of the vertices in a mesh can be updated with the member function
 
 ### Slice planes
 
-[Slice planes]([[url.prefix]]/features/slice_planes) are particularly useful for inspecting the internal stucture of a volume mesh, as shown in the demo video at the top. Slice planes can be manipulated programmatically or manually in the GUI; see the slice plane documentation for more details.
+[Slice planes]([[url.prefix]]/features/slice_planes) are particularly useful for inspecting the internal stucture of a volume mesh, as shown in the demo video at the top. Slice planes can be manipulated programmatically or manually in the GUI; they also have special functionality for filling in sliced data for volume meshes. See the slice plane documentation for more details. 
+
 
 ### Options
 

cpp/source/structures/volume_mesh/scalar_quantities.md

@@ -45,6 +45,57 @@ polyscope::show();
     - `data` is the array of scalars, with one value per cell. The type should be [adaptable]([[url.prefix]]/data_adaptors) to a `float` scalar array; this includes may common types like `std::vector<float>` and `Eigen::VectorXd`. The length should be the number of cell in the mesh.
 
 
+### Level sets
+
+When a vertex scalar quantity is attached to a volume mesh, level sets of the vertex data can be rendered by enabling "Level Set" in the settings for the vertex scalar quantity. Show other scalar quantities on this generated geometry by selecting "Show Quantity".
+
+
+![level set distance]([[url.prefix]]/media/level_set.png)
+<b>Example</b>: showing a level set of a vertex scalar quantity which just represents the distance from the mesh's origin, resulting in a sphere with radius equal to the value at the level set.
+
+```cpp
+/* ... initialization, create mesh ... */ 
+// Add a scalar quantity
+size_t nVerts = verts.rows();
+std::vector<double> scalarV(nVerts);
+for (size_t i = 0; i < nVerts; i++) {
+  // use the x-coordinate of vertex position as a test function
+  scalarV[i] = abs(V(i,0));
+}
+auto scalarQ = polyscope::getVolumeMesh("my mesh")->addVertexScalarQuantity("scalar Q", scalarV);
+
+// Add a second scalar quantity which is just distance from origin
+std::vector<double> scalarV2(nVerts);
+for (size_t i = 0; i < nVerts; i++) {
+  // use the x-coordinate of vertex position as a test function
+  scalarV2[i] = sqrt(pow(V(i,0), 2) + pow(V(i,1), 2) + pow(V(i,2), 2));
+}
+auto scalarQ2 = polyscope::getVolumeMesh("my mesh")->addVertexScalarQuantity("scalar Q2", scalarV2);
+
+// Set level set options
+scalarQ2->setEnabledLevelSet(true);  
+// Sphere of radius 8
+scalarQ2->setLevelSetValue(8.0f);  
+// Show original scalar on this level set
+scalarQ2->setLevelSetVisibleQuantity("scalar Q");  
+// set the name of the other scalar quantity 
+// to be rendered onto the level set
+
+// Show the GUI
+polyscope::show();
+```
+
+??? func "`#!cpp VolumeMeshVertexScalarQuantity::setEnabledLevelSet(bool enabled)`"
+
+    Enable or disable level set rendering for a vertex scalar quantity. Enabling level set rendering will disable the normal surface rendering and all other quantities.
+
+??? func "`#!cpp VolumeMeshVertexScalarQuantity::setLevelSetValue(float val)`"
+
+    Set the value of the level set to show.
+
+??? func "`#!cpp VolumeMeshVertexScalarQuantity::setLevelSetVisibleQuantity(std::string name)`"
+
+    Set the secondary scalar quantity to render onto the level set geometry. Only names of vertex scalar quantities on the same volume mesh will work.
 
 ### Options
 

py/source/features/slice_planes.md

@@ -158,3 +158,13 @@ ps_mesh.set_cull_whole_elements(False)
 
     Test whether the cull whole elements setting is applied.
 
+### Slicing Volume Meshes
+
+When slicing geometry meshes, it is often useful to inspect geometry and quantities along the sliced plane within the mesh. To generate this geometry along a slice plane to "fill" the culled space, select the volume mesh you want to slice from the "Slice Volume Mesh" dropdown in the slice plane options. Scalar quantities on the surface of the mesh will also be propagated correctly onto the generated slice.
+
+??? func "`#!python SlicePlane.set_volume_mesh_to_slice(name)`"
+
+    Set the volume mesh to slice for this plane. If the provided string is a valid name of a volume mesh in the scene, that slice plane will generate new geometry along the plane to fill in culled data.
+
+![volume mesh sliced]([[url.prefix]]/media/sliced_volume_mesh.png)
+

py/source/structures/volume_mesh/basics.md

@@ -90,7 +90,7 @@ The locations of the vertices in a mesh can be updated with the member function
 
 ### Slice planes
 
-[Slice planes]([[url.prefix]]/features/slice_planes) are particularly useful for inspecting the internal stucture of a volume mesh, as shown in the demo video at the top. Slice planes can be manipulated programmatically or manually in the GUI; see the slice plane documentation for more details.
+[Slice planes]([[url.prefix]]/features/slice_planes) are particularly useful for inspecting the internal stucture of a volume mesh, as shown in the demo video at the top. Slice planes can be manipulated programmatically or manually in the GUI; they also have special functionality for filling in sliced data for volume meshes. See the slice plane documentation for more details. 
 
 ### Options
 

py/source/structures/volume_mesh/scalar_quantities.md

@@ -43,3 +43,11 @@ ps.show()
     - `cmap` string, which [colormap](../../../features/color_maps) to use
 
     if not specified, these optional parameters will assume a reasonable default value, or a [persistent value](../../../basics/parameters/#persistent-values) if previously set.
+
+### Level sets
+
+When a vertex scalar quantity is attached to a volume mesh, level sets of the vertex data can be rendered by enabling "Level Set" in the settings for the vertex scalar quantity. Show other scalar quantities on this generated geometry by selecting "Show Quantity".
+
+
+![level set distance]([[url.prefix]]/media/level_set.png)
+<b>Example</b>: showing a level set of a vertex scalar quantity which just represents the distance from the mesh's origin, resulting in a sphere with radius equal to the value at the level set.