Visualize metadata using scripting

In Viewport 2.0, you can visualize metadata assigned to vertices, edges, faces, and vertex faces on polygons. See also Visualize metadata in Viewport 2.0.

Follow these guidelines to add metadata to components (in this case, vertices) of your object, and visualize the metadata using the showMetadata command.

When you use the showMetadata command to visualize metadata, you can view different stream/member combinations on different objects, but only one stream/member on each object. For example, you can visualize StreamOne on Object1 and StreamTwo on Object2 at the same time, but not both StreamOne and StreamTwo on Object1 at the same time.

  1. To add metadata to your object, first define a data structure using the dataStructure command, and create your data streams and attach them to your object(s) using the addMetadata command; for example, as follows: 

    // Define the data structure and create a data stream called StreamOne 
dataStructure -format "raw" -asString "name=ColorStruct:float[3]=Color"; 
addMetadata -streamName "StreamOne" -channelName "vertex" -structure "ColorStruct" smcPlaneShape smcPlane1Shape;
    Note:

    Metadata should not be added to a deformed mesh.

    In general, any operation that changes the topology of a polyShape’s inMesh attribute (that is, the input attribute of the polyShape node), for example, hard edge modification, will not modify the incoming metadata in the same way and may lead to unexpected results.

  2. Use the editMetadata command to assign values to the metadata stream(s) for the specified components. Use the -value flag to define metadata values in the stream, and the -index flag to indicate the vertex/vertices that you want to apply the metadata to. 

    // Set StreamOne values and assign StreamOne to specified vertices on smcPlaneShape
editMetadata -streamName "StreamOne" -value 2 -value 0.5 -value 1 -index 1 smcPlaneShape;
    Note:

    Alternatively, you can also assign metadata on vertices by first selecting the vertices: 

    select -r smcPlane.vtx[2:3];
editMetadata -streamName "StreamOne" -value 2 -value 0.5 -value 1;

    The above is equivalent to: 

    editMetadata -streamName "StreamOne" -value 2 -value 0.5 -value 1 -index 2 -index 3 smcPlaneShape;
  3. To visualize the metadata, use the showMetadata command and indicate the stream, member, and data type of the member that you want to display, and the -method flag to indicate the mode that you want your metadata to display in. If you do not specify a mode, the color mode is used. 
    // Visualize StreamOne on smcPlaneShape
showMetadata -stream "StreamOne" -member "Color" -dataType "float[3]" -method "string" smcPlaneShape;
  4. To disable visualization, specify the stream name and use the off flag.

    You can specify the object name to disable visualization on only that object. If you do not specify an object name and no objects are selected in the scene, then visualization is disabled on all objects for the specified stream and member. 

    showMetadata -stream "StreamOne" -off -member "Color" -dataType "float[3]" smcPlaneShape;

The example provided below demonstrates how to attach two streams of metadata (StreamOne and StreamTwo) to the vertices on two objects (smcPlane and smcPlane1), and how to visualize the data streams one by one in Viewport 2.0. It concludes by disabling the visualization. 

// Start a new scene and create two cubes 
file -new -f; 
polyCube -n smcPlane -ch off; 
pickWalk -d down; 
move -r 1.5 0 0 ; 
polyCube -n smcPlane1 -ch off; 
pickWalk -d down; 


// Define the data structure and create and attach the data streams to the two shapes 
dataStructure -format "raw" -asString "name=ColorStruct:float[3]=Color"; 
addMetadata -streamName "StreamOne" -channelName "vertex" -structure "ColorStruct" smcPlaneShape smcPlane1Shape; 
addMetadata -streamName "StreamTwo" -channelName "vertex" -structure "ColorStruct" smcPlaneShape smcPlane1Shape; 


// Assign metadata values to the two streams 
editMetadata -streamName "StreamOne" -value 0.25 -value 1.25 -value 2 -index 1 smcPlaneShape; 
editMetadata -streamName "StreamTwo" -value -2 -value -0.5 -value 2.5 -index 2 smcPlaneShape; 
editMetadata -streamName "StreamTwo" -value -4 -value -0.5 -value 2.5 -index 3 smcPlaneShape; 
editMetadata -streamName "StreamTwo" -value -1.25 -value -0.75 -value 3 -index 4 smcPlane1Shape; 
editMetadata -streamName "StreamOne" -value 6 -value 2 -value 3.5 -index 5 smcPlane1Shape; 
editMetadata -streamName "StreamOne" -value 2 -value 0.5 -value 1 -index 6 smcPlane1Shape; 


// NOTE: By default, all streams are hidden. 
// Activate visualization of "StreamOne" for one cube. Use color mode. 
showMetadata -stream "StreamOne" -member "Color" -dataType "float[3]" -method "color" smcPlane1Shape;  

// Metadata is now visible. 
// Auto remap the data range of the values in the stream.
showMetadata -stream "StreamOne" -member "Color" -dataType "float[3]" -method "color" -auto smcPlane1Shape;

// Enable color interpolation to extrapolate color to the faces surrounding the vertices
showMetadata -stream "StreamOne" -member "Color" -dataType "float[3]" -method "color" -interpolation true smcPlane1Shape;  

// Activate visualization of "StreamOne" for the other cube. Use string mode.
showMetadata -stream "StreamOne" -member "Color" -dataType "float[3]" -method "string" smcPlaneShape;  

// Metadata is now visible on both cubes. 
// Now, activate visualization of "StreamTwo" for the second cube. Use ray mode.
showMetadata -stream "StreamTwo" -member "Color" -dataType "float[3]" -method "ray" smcPlaneShape; 

// The rays appear too long. 
// Scale the length using the rayscale flag.
showMetadata -stream "StreamTwo" -member "Color" -dataType "float[3]" -method "ray" -rayScale 0.3 smcPlaneShape; 

// The visible metadata has now changed, and you have now used all three methods of display. 
// Deactivate the stream.  To turn off visualization on an object, specify the stream name and use the off flag. 
showMetadata -stream "StreamTwo" -member "Color" -dataType "float[3]" -off smcPlaneShape;   

// Now metadata is no longer visible on the second cube (smcPlaneShape)

In this example, StreamTwo is visualized on smcPlaneShape in ray mode with the Ray length scale set to 0.3, while StreamOne is visualized on smcPlane1Shape in color mode, with the data range automatically remapped and color interpolation enabled.

For more information regarding the flags available for use with the showMetadata command, see the Technical Documentation, MEL Commands and Python Commands section.

You can only visualize two streams simultaneously using this scripting method, not using the marking menu or Metadata Visualization Options.

Related topics

Parent topic: Visualizing metadata