Skip to content

Vector Quantities

Visualize vector-valued data at the elements of a surface mesh.

Ambient vectors

Ambient vectors are “standard” vectors, which have X-Y-Z vector coordinates in world space.

face_vector_demo

SurfaceMesh::addVertexVectorQuantity(std::string name, const T& vectors, VectorType vectorType=VectorType::STANDARD)

Add a vector quantity defined at the vertices of the mesh.

  • vectors is the array of vectors at vertices. The type should be adaptable to a 3-vector array of floats. The length should be the number of vertices in the mesh.
  • vectorType indicates how to interpret vector data. The default setting is as a freely-scaled value, which will be automatically scaled to be visible. Passing VectorType::AMBIENT ensures vectors have the proper world-space length.

Note: the inner vector type of the input must be 3D dimensional, or you risk compiler errors, segfaults, or worse. If you want to add 2D vectors (usually to a 2D mesh), addVertexVectorQuantity2D exists with the same signature. See 2D data.

SurfaceMesh::addFaceVectorQuantity(std::string name, const T& vectors)

Add a vector quantity defined at the faces of the mesh.

  • vectors is the array of vectors at faces. The type should be adaptable to a 3-vector array of floats. The length should be the number of faces in the mesh.
  • vectorType indicates how to interpret vector data. The default setting is as a freely-scaled value, which will be automatically scaled to be visible. Passing VectorType::AMBIENT ensures vectors have the proper world-space length.

Note: the inner vector type of the input must be 3D dimensional, or you risk compiler errors, segfaults, or worse. If you want to add 2D vectors (usually to a 2D mesh), addFaceVectorQuantity2D exists with the same signature. See 2D data.

Tangent vectors

Tangent vectors lie flat against the surface of a mesh. They are defined as 2D vector in a local 2D coordinate system at each vertex or face. We need to specify the vector itself as well as the basis vectors for the local coordinate systems.

Example: visualizing tangent vectors with geometry-central 

#include "polyscope/polyscope.h"
#include "polyscope/surface_mesh.h"

polyscope::init();

// Load mesh
std::unique_ptr<HalfedgeMesh> mesh;
std::unique_ptr<VertexPositionGeometry> geometry;
std::tie(mesh, geometry) = loadMesh(filename);

// Register the mesh with polyscope
psMesh = polyscope::registerSurfaceMesh("mesh",
              geometry->inputVertexPositions, mesh->getFaceVertexList(),
              polyscopePermutations(*mesh));


// Gather vertex tangent spaces
geometry->requireVertexTangentBasis();
VertexData<Vector3> vBasisX(*mesh);
VertexData<Vector3> vBasisY(*mesh);
for(Vertex v : mesh->vertices()) {
  vBasisX[v] = geometry->vertexTangentBasis[v][0];
  vBasisY[v] = geometry->vertexTangentBasis[v][1];
}

// Make a vector field
VertexData<Vector2> vecField = /* some field */

// Register the field
polyscope::getSurfaceMesh("mesh")->
  addVertexIntrinsicVectorQuantity("great vectors", 
                                   vecField, vBasisX, vBasisY);

polyscope::show();

SurfaceMesh::addVertexTangentVectorQuantity(std::string name, const T& vectors, const B1& basisX, const B2& basisY, int nSym=1, VectorType vectorType=VectorType::STANDARD)

Add a tangent vector quantity defined at the vertices of the mesh.

  • vectors is the array of 2D vectors at vertices. The type should be adaptable to a 2-vector array of floats. The length should be the number of vertices in the mesh.
  • basisX is the array of 3D vectors at vertices defining the X vector of the tangent basis. The type should be adaptable to a 3-vector array of floats. The length should be the number of vertices in the mesh.
  • basisY is the array of 3D vectors at vertices defining the Y vector of the tangent basis. The type should be adaptable to a 3-vector array of floats. The length should be the number of vertices in the mesh.
  • nSym is a symmetry order, for visualizing line fields (n = 2) and cross fields (n = 4), etc. If it is set to a non-1 value, nSym distinct vectors will be displayed at each element, by rotating the input vector 2*PI/nSym radians.
  • vectorType indicates how to interpret vector data. The default setting is as a freely-scaled value, which will be automatically scaled to be visible. Passing VectorType::AMBIENT ensures vectors have the proper world-space length.
SurfaceMesh::addFaceTangentVectorQuantity(std::string name, const T& vectors, const B1& basisX, const B2& basisY, int nSym=1, VectorType vectorType=VectorType::STANDARD)

Add a tangent vector quantity defined at the faces of the mesh.

  • vectors is the array of vectors at faces. The type should be adaptable to a 2-vector array of floats. The length should be the number of faces in the mesh.
  • basisX is the array of 3D vectors at faces defining the X vector of the tangent basis. The type should be adaptable to a 3-vector array of floats. The length should be the number of faces in the mesh.
  • basisY is the array of 3D vectors at faces defining the Y vector of the tangent basis. The type should be adaptable to a 3-vector array of floats. The length should be the number of faces in the mesh.
  • nSym is a symmetry order, for visualizing line fields (n = 2) and cross fields (n = 4), etc. If it is set to a non-1 value, nSym distinct vectors will be displayed at each element, by rotating the input vector 2*PI/nSym radians.
  • vectorType indicates how to interpret vector data. The default setting is as a freely-scaled value, which will be automatically scaled to be visible. Passing VectorType::AMBIENT ensures vectors have the proper world-space length.

One forms

One forms are tangent vector-like quantities represented as integrated scalars along edges. They commonly arise, for example, as a gradient which is difference of scalar values at vertices.

SurfaceMesh::addOneFormTangentVectorQuantity(std::string name, const T& data, const O& orientations)

Add a one-form quantity via a scalar at edges, which will be shown like a vector field.

  • data is the array of scalars at edges. The type should be adaptable to an array of floats. The length should be the number of edges in the mesh.
  • orientations 1-forms are defined with respect to an orientation of edges, so you need to tell Polyscope which direction your edges point in. This input is an array of booleans at edges. The type should be adaptable to an array of chars (because std::vector<bool> is broken). The length should be the number of edges in the mesh. These booleans should be true if the edge points from the lower indexed adjacent vertex to the higher-indexed vertex, and false otherwise.

Remember, before passing edge-valued data, be sure your indexing convention matches what Polyscope expects.

Vector Quantity Options

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

Parameter Meaning Getter Setter Persistent?
enabled is the quantity enabled? bool isEnabled() setEnabled(bool newVal) yes
vector radius the radius vectors are drawn with double getVectorRadius() setVectorRadius(double val, bool isRelative=true) yes
vector length vectors will be scaled so the longest is this long. ignored if VectorType::Ambient double getVectorLengthScale() setVectorLengthScale(double val, bool isRelative=true) yes
vector color the color to draw the vectors with glm::vec3 getVectorColor() setVectorColor(glm::vec3 val) yes
material what material to use std::string getMaterial() setMaterial(std::string name) yes

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