API: MeshDisplay

MeshDisplay Viewer API

While implementing geometric algorithms, it is fairly reasonable to wish to visualize and interact with your code, but it would be tedious to implement a viewer for each application. To that, this codebase includes a general purpose mesh viewer class, which can be used to visualize a wide range of data and can be customized for different applications.

---

Basic Use

Visualizing a mesh onscreen requires at least three steps: creating a viewer object, setting the mesh and other data, and beginning the view loop. Note that once startMainLoop() is called, control of the program is passed to the viewer, and your code will not progress past that line until the viewer window is closed.

meshDisplay = MeshDisplay(windowTitle="Your window's name")
meshDisplay.setMesh(mesh)
# (Set data to display and add callback here, if desired)
meshDisplay.startMainLoop()

There are many ways to interact with this viewer using the mouse and keyboard. Clicking and dragging will rotate the mesh, and holding shift while clicking and dragging will translate the mesh. Clicking on vertices/faces/edges will cause the appropriate callback to be executed. Pressing h will print a list of keyboard commands for the viewer, which include several visualization options.

Basic Methods:

• MeshDisplay(windowTitle='MeshDisplay', width=1200, height=800) Constructs a new viewer object. The window opened by the viewer will have the specified title, width, and height
• setMesh(mesh) Sets a mesh object for this viewer to display. Must be a HalfEdgeMesh object.
• startMainLoop() Causes the viewer to being executing and actually appear onscreen. This method does not return until the viewer is closed.

---

Visualizing Data

The viewer can visualize data as scalars defined on vertices and faces, or as vectors defined on vertices or faces.

Visualization Methods:

• setShapeColorFromScalar(self, colorScalarAttr, definedOn='vertex', vMinMax=None, cmapName='OrRd') Colors the surface of the mesh according to a scalar value defined at its surface

  • colorScalarAttr is a string which gives the name of the attribute to color by
  • definedOn indicates where the values are defined, should be either vertex or face
  • vMinMax is a length 2 list which gives a range for the data, which is used when setting the colormap. For instance, vMinMax=[0.0,1.0] indicates the data is defined between [0,1], and these values are used when setting a colormap. If this optional argument is not given, the max/min of the data are used.
  • cmapName The colormap to use, all matplotlib colormap names are valid, though you may be using an older version of matplotlib that does not include all of the options on that page.

  I recommend the 'OrRd' colormap for sequential values that represent a magnitude, such as those defined from [0,X]. I recommend 'seismic' or 'coolwarm' for diverging values that are centered around a neutral value, such as those defined from [-X,X].

• setShapeColorFromRGB(colorAttrName, definedOn='vertex') Colors the surface of the mesh according to (R,G,B) color values defined at its surface.

  • colorAttrName is a string which gives the name of the attribute to color by
  • definedOn indicates where the values are defined, should be either vertex or face

• setShapeColorToDefault() Remove any color visualization and return the shape to its default color

• setVectors(vectorAttrName, vectorDefinedAt='vertex') Visualize vector data defined on the surface

  • vectorAttrName is a string which gives the name of the vector attribute to draw
  • definedOn indicates where the values are defined, should be either vertex or face

---

Callbacks

To customize the viewer for different applications, you can define callback functions, which are executed whenever a particular key is pressed, or when a face/edge/vertex is clicked.

The following example demonstrates the uses of both types of callbacks:

# Register a keyboard callback
def countVertices():
    numVerts = len(mesh.verts)
    print("Mesh has " + str(numVerts) + " vertices.")
meshDisplay.registerKeyCallback('z', countVertices, docstring="Count vertices")

# Register a mouse click callback
def pickFace(face):
    print("   Vertex positions: ")
    for (i, vert) in enumerate(face.adjacentVerts()):
        print("     v{}: {}".format((i+1),printVec3(vert.position)))
meshDisplay.pickFaceCallback = pickFace

Callback methods

• registerKeyCallback(key, function, docstring="Application-defined command") Register a new keyboard callback function
  • 'key' A string, giving the key which will be pressed to execute this function
  • 'function' The function which should be executed (must take no arguments)
  • 'docstring' A string describing the purpose of this function. This is what gets printed when the h key is pressed.
• pickVertexCallback A member, normally set to None, which can be assigned to a function that will serve as a vertex callback. The function should take one argument, which is the vertex that was clicked.
• pickFaceCallback A member, normally set to None, which can be assigned to a function that will serve as a face callback. The function should take one argument, which is the face that was clicked.
• pickEdgeCallback A member, normally set to None, which can be assigned to a function that will serve as an edge callback. The function should take one argument, which is the edge that was clicked.