Scalar Quantities

Visualize scalar-valued data at the nodes or cells of a volume grid.

volume grid node cell values

Example: registering a volume grid and adding a scalar quantity

#include "polyscope/polyscope.h"
#include "polyscope/volume_grid.h"

polyscope::init();

// define the resolution and bounds of the grid
uint32_t dimX = 20;
uint32_t dimY = 20;
uint32_t dimZ = 20;
glm::vec3 bound_low{-3., -3., -3.};
glm::vec3 bound_high{3., 3., 3.};

// register the grid
polyscope::VolumeGrid* psGrid = polyscope::registerVolumeGrid(
        "sample grid", {dimX, dimY, dimZ}, bound_low, bound_high);

// add a scalar function on the grid
uint32_t nData = dimX*dimY*dimZ;
float* scalarVals = /* your dimX*dimY*dimZ buffer of data*/;

polyscope::VolumeGridNodeScalarQuantity* scalarQ = 
    psGrid->addNodeScalarQuantity("node scalar1", 
                                  std::make_tuple(scalarVals, nData));
scalarQ->setEnabled(true);

polyscope::show();

Add scalars

VolumeGridNodeScalarQuantity* VolumeGrid::addNodeScalarQuantity(std::string name, const T& data, DataType type = DataType::STANDARD)

Add a scalar quantity defined at the nodes of the grid.

The data is passed as a flattened vector of length nodeDimX*nodeDimY*nodeDimZ, with data layout such that the X values are changing fastest. For example with 3D xyz indexing, the values would be laid out as [data[0,0,0], data[1,0,0], data[2,0,0], ...], etc.

data is the (flattened) array of scalars at nodes. The type should be adaptable to a float scalar array; this includes may common types like std::vector<float> and Eigen::VectorXd. The length should be the number of nodes in the grid.

VolumeGridCellScalarQuantity* VolumeMesh::addCellScalarQuantity(std::string name, const T& data, DataType type = DataType::STANDARD)

Add a scalar quantity defined at the cells of the grid.

The data is passed as a flattened vector of length cellDimX*cellDimY*cellDimZ, with data layout such that the X values are changing fastest. For example with 3D xyz indexing, the values would be laid out as [data[0,0,0], data[1,0,0], data[2,0,0], ...], etc.

data is the (flattened) array of scalars at cells. The type should be adaptable to a float scalar array; this includes may common types like std::vector<float> and Eigen::VectorXd. The length should be the number of cells in the grid.

Add implicit scalars

Implicit helpers

Implicit helpers offer an easier way to interface your data with Polyscope. You define a callback function which can be called at an xyz coordinate to return a value, and pass that function as input. Polyscope then automatically takes care of calling the function at the appropriate locations to sample the function onto the grid.

See Implicit Helpers for more details about implicit helpers, and the meaning of batch helpers.

VolumeGridNodeScalarQuantity* VolumeGrid::addNodeScalarQuantityFromCallable(std::string name, Func&& func, DataType type = DataType::STANDARD)

Add a scalar quantity defined at the nodes of the grid, sampling automatically via a callable function.

func is a function which takes a single glm::vec3 world-space position as input, and returns the scalar value at that point

VolumeGridCellScalarQuantity* VolumeGrid::addCellScalarQuantityFromCallable(std::string name, Func&& func, DataType type = DataType::STANDARD)

Add a scalar quantity defined at the cells of the grid, sampling automatically via a callable function.

func is a function which takes a single glm::vec3 world-space position as input, and returns the scalar value at that point

VolumeGridNodeScalarQuantity* VolumeGrid::addNodeScalarQuantityFromBatchCallable(std::string name, Func&& func, DataType type = DataType::STANDARD)

Add a scalar quantity defined at the nodes of the grid, sampling automatically via a callable function.

func is a function which performs a batch of evaluations of the implicit function. It should have a signature like void(float* in_pos_ptr, float* out_val_ptr, size_t N). The first arg is a length-3N array of positions for queries, and the second is an (already-allocated) length-N output array of floats to write the result to. The last arg is the numbrer of queries N.

VolumeGridCellScalarQuantity* VolumeGrid::addCellScalarQuantityFromBatchCallable(std::string name, Func&& func, DataType type = DataType::STANDARD)

Add a scalar quantity defined at the cells of the grid, sampling automatically via a callable function.

func is a function which performs a batch of evaluations of the implicit function. It should have a signature like void(float* in_pos_ptr, float* out_val_ptr, size_t N). The first arg is a length-3N array of positions for queries, and the second is an (already-allocated) length-N output array of floats to write the result to. The last arg is the numbrer of queries N.

Scalar Quantity Options

These options and behaviors are available for all types of scalar quantities on any structure.

Parameter	Meaning	Getter	Setter	Persistent?
enabled	is the quantity enabled?	`bool isEnabled()`	`setEnabled(bool newVal)`	yes
color map	the color map to use	`std::string getColorMap()`	`setColorMap(std::string newMap)`	yes
map range	the lower and upper limits used when mapping the data in to the color map	`std::pair<double,double> getMapRange()`	`setMapRange(std::pair<double,double>)` and `resetMapRange()`	no
isolines enabled	are isolines shaded (default=`false`)	`bool getIsolinesEnabled()`	`setIsolinesEnabled(bool newVal)`	yes
isoline width	width of isoline stripes, in data units	`float getIsolineWidth()`	`setIsolineWidth(float newVal)`	yes
isoline darkness	darkness of isoline stripes (default=`0.7`)	`float getIsolineDarkness()`	`setIsolineDarkness(float newVal)`	yes

(all setters return this to support chaining. setEnabled() returns generic quantity, so chain it last)

Visualizing Isosurfaces

For a scalar values at nodes, we can additionally extract isosurfaces (aka levelsets) via the marching cubes algorithm, and visualize them as surface meshes.

volume grid node scalar values

Example: visualizing scalar isosurfaces

/* continued after `scalarQ` has been added as in the first example above */

scalarQ->setGridcubeVizEnabled(false); // hide the default grid viz
scalarQ->setIsosurfaceLevel(0.5); // set which isosurface we will visualize
scalarQ->setIsosurfaceVizEnabled(true); // extracts the isosurface
polyscope::show();

// add a slice plane to cut through the grid while leaving the isosurface
// untouched, as in the screenshot above
scalarQ->setGridcubeVizEnabled(true);
polyscope::SlicePlane* p = polyscope::addSceneSlicePlane();
scalarQ->setSlicePlanesAffectIsosurface(false); 
polyscope::show();

// extract the isosurface as its own mesh structure
scalarQ->registerIsosurfaceAsMesh("my isosurface mesh");

The following settings on the VolumeGridNodeScalarQuantity class affect the behavior of isosurfaces.

Note

By default, the grid obscures the isosurface so it cannot be seen. You probably want to either:

use a slice plane, along with the setSlicePlanesAffectIsosurface(false) option, or
use setGridcubeVizEnabled(false) to disable the default grid visualization

Parameter	Meaning	Getter	Setter	Persistent?
enabled	is the isosurface enabled	`bool getIsosurfaceVizEnabled()`	`setIsosurfaceVizEnabled(bool)`	yes
level	at what value to extract the isosurface (default: 0)	`float getIsosurfaceLevel()`	`setIsosurfaceLevel(float)`	yes
color	the color of the isosurface mesh	`glm::vec3 getIsosurfaceColor()`	`setIsosurfaceColor(glm::vec3)`	yes
slice planes affect	do slice planes affect the isosurface	`bool getSlicePlanesAffectIsosurface()`	`setSlicePlanesAffectIsosurface(bool)`	yes
gridcube viz enabled	are the usual gridcubes rendered	`bool getGridcubeVizEnabled()`	`setGridcubeVizEnabled(bool)`	yes

You can also register the isosurface as its own Polyscope surface mesh structure for further visualization.

SurfaceMesh* VolumeGridNodeScalarQuantity::registerIsosurfaceAsMesh(std::string structureName = "")

Extract the scalar function isosurface as described above, and register it as its own new SurfaceMesh structure.

structureName` is the name of the newly created structure. If not given, a default name will be automatically generated.