Workspace 7.1.0
Glyphing
[ Previous: Changing a model's appearance ] [ Up: Introductory Tutorials ] [ Next: Linear Transforms ]

Introduction

In the previous tutorial, we learned one way of visualising a MeshModel's state information using Workspace - by coloring the model's Nodes or Elements according to its state data. In this tutorial, we will learn how to visualise aspects of the model's state information using a different technique - Glyphing.

Glyphing is the process of applying "Glyphs" to each of the Nodes in a MeshModel at the time it is displayed. Depending upon the type of glypher being used, the glyphs can take many forms, and can vary in appearance from node-to-node. Some examples of glyphing applications include:

  • Drawing spherical particles for each node, scaling each particle according to its radius
  • Drawing arrows on each node to represent their current velocity
  • Drawing symbols on each node that has a kinetic energy above a certain threshold

In this tutorial, you will learn:

A sample workflow has been provided for this tutorial.

Prerequisites

This tutorial assumes that you have completed the previous two tutorials: Basic Rendering and Modifying a Model's Appearance. The steps in the tutorial build upon the workflow completed in the last tutorial - if you did not complete this tutorial, please use the sample workflow for tutorial #2 as the basis to begin this tutorial.

1. Adding a glypher to the scene

In this step of the tutorial, we are going to create the most commonly used type of Glypher, a SphereGlypher. The Sphere Glypher, as its name suggests, draws a Sphere at each node of the MeshModel.

Many types of MeshModels, such as 3D graph data and the outputs of particle simulations do not have Elements in them and consist only of Nodes. These MeshModels often contain state information at each node describing the particle shape. SphereGlyphers are particularly useful for providing additional depth or realism to these types of data sets.

Before we do anything else, the first thing we are going to do is change which model we're looking at, and update the selected state we are using to color its nodes. To do this:

  1. Click on the SelectableMeshReader to select it.
  2. In the Operation editor, click on the folder icon next to the File name input to browse for a different model file.
  3. Select the particle_sample.vtk file.
  4. Execute the workflow.
  5. Click on the StringSelectionInfo operation to select it.
  6. In the Operation editor, modify the StringSelection property to "velocity"

This will update the selectable mesh reader to point to the new model, however, Workspace caches the OpenGL representation of the model, so we need to indicate to it that we want it to do away with this cached version. There are two ways to do this. The first:

  1. Click on the MeshModelInstanceBuilder operation to select it.
  2. In the OperationEditor, change the ModelID field to "particle_model"
  3. The new model ID means that a new cached item is referred to instead of the old one. If we want to refer back to the previous one, all we need to do is restore the original ID and Workspace will point to it without re-loading anything.

Alternatively, we can:

  1. Click on the SelectableMeshReader to expose its outputs
  2. Click and drag a connection from the "Dependencies" output of the SelectableMeshReader to the "Clear cache indicator" input of the MeshModelInstanceBuilder
  3. This will make sure that whenever the SelectableMeshReader's inputs are updated, the cached instance data is refreshed.

This model contains a frame from a multi-frame particle simulation. This particular frame shows the particles after they have just collided with an object.

Now that we have a particle model, we want to create a SphereGlypher and attach it to our particle model:

  1. From the Scene > Glyphers section of the Operation Catalogue, drag a SphereGlypherBuilder operation onto the workspace canvas.
    Creating the SphereGlypherBuilder
  2. Connect the Glypher output of the SphereGlypherBuilder to the Glyphers array input of the MeshModelInstanceBuilder operation.

If we now Click on the SphereGlypher operation, we will see a number of properties:

Properties of the SphereGlypher

For this tutorial, we will set a few values to create an interesting visual effect:

  1. Check the Use scale as radius property.
  2. Set the Scale to 0.05. The glypher will use this radius for each sphere it creates.
  3. Set the Interval property to 7. This will ensure that only every 7th glyph is drawn.
  4. Set the Subdivisions property to 1. This will draw spheres that appear slightly more round than the default level.

To see the results, create a WSGLWidget for our scene as we did in step 2 of the Basic Rendering tutorial. If we zoom into the model slightly, the scene should appear similar to this:

The particle model displayed with sphere glyphs of a uniform radius

2. Using state data to drive glypher properties

In many models, some of the states present at each node describe aspects of that node's physical appearance, such as the particle radius or orientation. The different glyphers in Workspace provide inputs which the user can use to attach states to various glyph properties.

In this part of the tutorial, we are going to demonstrate this by using the "radius" property of our model to drive the radius of our glyphs. To do this:

  1. Click on the SphereGlypherBuilder to select it.
  2. In the Operation editor, deselect the Use scale as radius checkbox.
  3. In the Operation editor, enter 1 for the Scale input.
  4. In the Operation editor, enter the text "radius" for the Radius state name input.
  5. Observe that in the WSGLWidget, the size of the spheres are now scaled in accordance with the radius property.
    The particle model displayed with sphere glyphs scaled by particle radius

Often, manually entering the state name is not ideal - in many cases, it is not possible to know the names of the properties stored in the model. As we did in the previous tutorial when coloring by node-properties, we can use a "StringSelection", sourced from the list of states in the model data itself, to drive the selected property. To do this, we need another StringSelection for our "radius" property, in addition to our existing item for "velocity":

  1. Drag a box around the ConvertQStringListToStringSelection and StringSelectionInfo operations on the workspace canvas to select them.
    Selecting the ConvertToStringSelection and StringSelectionInfo operations
  2. Using the keyboard, enter the command CTRL + C to copy the operations. Alternatively, click the Edit > Copy menu item in the top-left corner of the screen.
  3. Using the keyboard, enter the command CTRL + V to paste the operations onto the workspace canvas. We now have another StringSelection object which we can use to scale our glyphs independently of the model's color. (Note: at this point, you may be prompted to stop workspace execution. If this occurs, select 'OK' in the presented dialog box.)
  4. Connect the Selected string output of the new StringSelectionInfo operation to the Radius state name input of the SphereGlypherBuilder operation.
  5. Connect the Node states output of the MeshModelStateInfo operation to the String list input of the new ConvertQStringListToStringSelection operation.
  6. Click on the new StringSelectionInfo operation to select it.
  7. In the Operation editor, select "radius" for the value of the Selected String input - you may need to execute the workflow before you can select "radius" from the drop down list.

At this point, the WSGLWidget should display exactly the same view we had before - we have only changed how the radius state name is sourced. Our workflow should look similar to this:

The workflow so far

3. More out-of-the-box glyphers

In addition to the sphere glypher described in section 1, Workspace supplies a number of other useful glyphers. This section provides a brief overview of the different glyphers that are available out-of-the-box, and how to use them.

3.1. The superquadric glypher

In some situations, instead of using perfectly spherical particles, some models use particles which are approximations of randomly shaped particles. Superquadric particles are one type of approximation. The Superquadric Glypher applies a 3D equivalent of a 'rounded rectangle' at each node in the model, where each shape can vary in its radius (independently in the x, y and z directions), its orientation, and its shape (i.e. whether it is more spherical or rectangular). All three of these properties can be set manually for all particles, or extracted from state-data.

3.2. The vector glypher

The Vector Glypher draws vectors (arrows) at each node in the model. Unlike the other glyphers, the vector glypher uses NodeMappers to obtain the values for each of its per-node variable properties (length and direction). By default, if no direction mapper is supplied and the glypher is applied to a model containing a surface mesh, it will apply glyphs representing the surface normals at each node in the mesh.

4. Applying multiple glyphers to a model

Workspace allows multiple glyphers to be applied to the same model at the same time. In our example, we are going to apply a VectorGlypher on top of our exiting SphereGlypher. To do this:

  1. From the Scene > Glyphers section of the Operation Catalogue, drag a VectorGlypher onto the workspace canvas.
    Creating the VectorGlypherBuilder
  2. Similar to the previous tutorial where we created a NodeStateMapper to control how our NodeColoringShader works, we need to create a VectorNodeStateMapper to control how our VectorGlypher works. A VectorNodeStateMapper is the same as a NodeStateMapper, except that it maps each node to a vector rather than a scalar. From the Mesh section of the Operation Catalogue, drag a VectorNodeStateMapperBuilder onto the workspace canvas. This operation differs from the NodeStateMapper, in that instead of mapping any node state (vector or scalar) to a scalar value, it maps vector node states to vector values.
    Creating the Vector Node State Mapper
  3. Connect the Selected String output of our original StringSelectionInfo operation (the one with 'velocity' selected) to the State name input of the VectorNodeStateMapper operation.
  4. Connect the Vector Node Mapper output of the VectorNodeStateMapper to the Vector Node Mapper input of the VectorGlypherBuilder.
  5. Connect the VectorGlypher output of our VectorGlypherBuilder to the Glyphers array input of our MeshModelInstanceBuilder operation.
  6. Click on the VectorGlypherBuilder to select it.
  7. In the Operation editor, change the Length scale property to 0.1. This will scale all of the vectors by 0.1, irrespective of their length.
  8. In the Operation editor, change the Interval property to 7. This will make sure only every 7th vector is drawn, which will match our settings for the SphereGlypher.
  9. Execute the workflow.
The workflow after adding the vector glypher

Now, if we look at the WSGLWidget, we will see that both spheres and vectors have been applied to the nodes of the model; the spheres show the size of each particle, and the vectors show its direction.

The particle model glyphed with spheres (scaled by radius) and vectors (representing 0.1 * velocity)

Summary

That concludes the tutorial. We have now learned:

  • What glyphing is and how to apply it to the models in our scene
  • How to use a model's state data to drive the properties of our glyphers
  • The different types of glyphers available in Workspace
  • How to apply multiple glyphers to a single model at the same time

Next Steps

The next few tutorials provide information about some of the other visualisation techniques:

  1. Instancing and applying linear transforms to models
  2. Off-screen rendering


[ Previous: Changing a model's appearance ] [ Up: Introductory Tutorials ] [ Next: Linear Transforms ]