On this page
This feature is still under development. The current functionality is unfinished and subject to change, and may have thin or no documentation. Please bear this in mind when using it.

This page lists the metadata that are available on graph nodes and ports.

Tags

Tags are identifiers that are used to mark and filter for graph nodes and ports, allowing you to identify groups of nodes and ports independent of their element names. This is useful, as element names on rigs and graphs often change.

Tags are stored on graph nodes in a string array attribute called tags. You can use the APEX path pattern function %tag() in graph nodes like graph::FindNodes and graph::FindPorts to find nodes and ports that have specific tags on them. You can also use the %tag() function in pre-built rig components to label and find nodes and ports in character rigs.

There are a few ways that tags can be created on graph nodes:

  • You can create and edit tags in the APEX network view.

  • You can build a graph (in the APEX network view or using APEX Script) that acts like a “script” to create another graph with tags.

  • Pre-built rig components can add tags to a character rig. For example, the fktransform component picks up on tags that were previously created on skeleton joints, and places these tags on the corresponding nodes in the rig. Some rig components also add tags on the nodes they create.

Create and edits tags in the APEX network view

To create and edit tags in the APEX network view:

  1. click the node(s) and select Edit Tags.

  2. In the Edit Tags window:

    • To create a tag, click and type in the tag name.

    • To edit a tag, double-click a tag and update the tag.

    • To remove a tag, select the tag and click .

  3. Click Accept. The tags will appear on top of the node:

    Note

    Port tags are stored on the graph node in the format <port>:<tag>.

Working with tags in APEX Script

Create tags

In this example, we use APEX Script to create a graph with node and port tags:

  1. In an APEX Script SOP, add the following code in the Snippet parameter:

    # Initialize a graph
    graph = ApexGraphHandle()
    
    # Create tags
    tags1: StringArray = ['abc', 'both']
    tags2: StringArray = ['t:abc', 'r:xyz', 'both']
    
    # Add TransformObject nodes to the new graph
    graph.addNode('test1', 'TransformObject', tags=tags1)
    graph.addNode('test2', 'TransformObject', tags=tags2)
    
    # Write out the graph as geometry
    geo = graph.writeToGeo()
    BindOutput(geo)
    
  2. To see the graph representation of the APEX Script snippet in the APEX network view, set Show to Component Script in the Visualizer section (node layout and colors have been modified for clarity):

  3. To see the new graph created by the APEX Script snippet:

    • Set Bind Output Geometry to <output_node>:<output_port>, in our case, output:geo.

    • In the Visualizer section, set Show to Output 1.

  4. To view the tags in the geometry spreadsheet:

    • The new graph is available on the 1st output of the APEX Script SOP:

    • Select the new_graph node.

    • In the geometry spreadsheet, select Points on the top toolbar:

Find nodes and ports based on tags

In this example, we find nodes and ports with specific tags using the APEX path pattern tag function in graph::FindNodes and graph::FindPorts.

Tip

graph::FindNodes and graph::FindPorts have a name mapping to matchNodes() and matchPorts().

  1. We take the graph created from the previous example and input it into a second APEX Script SOP:

  2. In the find_tags APEX Script SOP, use the predefined headers to automatically add the APEX Script commands that take in and modify an input graph:

    • Turn on the Header parameter.

    • In the Header section, set Template to Graph, which adds the following code to the beginning and end of your APEX Script snippet:

  3. Specify the input to the find_tags node - in the Invocation section, under Input1 Bindings, turn on Bind To Geometry Parameter, and set the parameter to geo. geo is the graph geometry that is input to the APEX Script SOP, specified in the header from the previous step.

  4. To find the tags in the input graph, add the following code in the Snippet parameter:

    # Find the nodes and ports with the specified tags
    abc_node_tag = graph.FindNodes('%tag(abc)')
    both_node_tag = graph.FindNodes('%tag(both)')
    xyz_port_tag = graph.FindPorts('%tag(xyz)')
    
    # Add found node and port names to an array for outputting
    both_nodes = StringArray()
    for n in both_node_tag:
        n_name = n.data()
        both_nodes.append(n_name)
    
    abc_nodes = StringArray()
    for n in abc_node_tag:
        n_name = n.data()
        abc_nodes.append(n_name)
    
    xyz_ports = StringArray()
    for p in xyz_port_tag:
        p_name = p.data()
        xyz_ports.append(p_name)
    
    # Output node and port arrays
    BindOutput(abc_nodes, both_nodes, xyz_ports)
    

    Note

    Even though the port tag is stored on the graph node as r:xyz, only specify the tag name, and not the port name, in the tag function when using graph.FindPorts(). For example, use graph.FindPorts('%tag(xyz)'), not graph.FindPorts('%tag(r:xyz)').

  5. By default, the first entry of Output Dictionary Bindings in the APEX Script SOP Invocation section is filled out with the following:

    • Apex Outputs Group is the set to output. This is the name of the output node in the graph.

    • Output Attrib is set to parms. This is the name of the output dictionary to store the node and port arrays.

  6. To view the found nodes and ports in the geometry spreadsheet:

    • Select the find_tags node.

    • In the geometry spreadsheet, select Detail on the top toolbar.

    • click on the entry in the Detail column of the parms attribute and select Inspect:

      "abc_nodes":["test1"]
      
      "both_nodes":["test1","test2"]
      
      "xyz_ports":["test2"]
      

Update tags

In this example, we update the tags in a graph using graph::UpdateNode and graph::UpdateNodeTags:

  1. We take the graph created from the previous example and input it into a second APEX Script SOP:

  2. In the update_tags APEX Script SOP, use the predefined headers to automatically add the APEX Script commands that take in and modify an input graph:

    • Turn on the Header parameter.

    • In the Header section, set Template to Graph.

  3. Specify the input to the update_tags node - in the Invocation section, under Input1 Bindings, turn on Bind To Geometry Parameter, and set the parameter to geo.

  4. To output the updated graph, set Bind Output Geometry to output:geo.

  5. The update_tags node now takes in the input graph and outputs it unchanged. To see the graph output, set Show to Output 1 in the Visualizer section.

  6. To update the tags on the input graph nodes, add the following code in the Snippet parameter:

    new_tags1 = ['new_tag']
    new_tags2 = ['def', 'xform:xyz']
    
    node1 = graph.test1
    node2 = graph.test2
    
    # Adds to existing tags
    graph.UpdateNodeTags(nodeid=node1, tags=new_tags1)
    
    # Replaces existing tags
    graph.UpdateNode(nodeid=node2, tags=new_tags2)
    
  7. See the graph representation of the APEX Script snippet in the APEX network view - in the Visualizer section, set Show to Component Script (node layout and colors have been modified for clarity):

  8. To see the new graph created by the APEX Script snippet, set Show to Output 1 in the Visualizer section:

    Original tags (left); updated tags (right)

Properties

Properties on graph nodes store custom information that could be used at a later point in the graph. They are stored in a dictionary attribute called properties. You can add and modify data in the properties dictionary using graph::UpdateNode and graph::UpdateNodeProperties. You can also filter for properties using the APEX path pattern function %properties() in graph nodes like graph::FindNodes.

Note

Properties are only used for nodes; there are no port properties.

To view the properties on a graph node:

  1. In the network view, select the node that contains the graph.

  2. In the geometry spreadsheet, select Points on the top toolbar.

  3. click the entry under the properties column and select Inspect to view the properties dictionary.

In addition to the custom information added by a user, the properties dictionary can also contain predefined entries that store information on control shapes, rig parameter limits, and rig/skeleton mapping. Users can also use and modify this information. The predefined entries are:

{
    control: {
        color: Vector3
        shapeoffset: Matrix4
        shapeoverride: String
        visibility: Int
    }
    max:<parameter_name>: Vector3
    min:<parameter_name>: Vector3
    max_lock:<parameter_name>: Vector3
    min_lock:<parameter_name>: Vector3
    mapping:<skeleton or rig>: String
}    

The mapping property can be set using the APEX Map Character SOP, and the other properties can be set using the APEX Configure Controls SOP.

Property

Type

Description

control

dict

A dictionary that contains information on how the control looks in the viewport.

color

Vector3

The color of the control.

shapeoffset

Matrix4

The position of the control.

shapeoverride

string

The shape of the control.

visibility

int

Whether the control is visible in the animate state.

max, min

Vector3

A soft limit on the rig transform parameters. The Vector3 values are the limits on the x, y, and z values of the parameter. The user can control whether or not to enforce the limits or use the limits as a visual indicator in the animate state. See transform limits for more information.

The format of the max and min properties is:

[max|min]:<parameter_name>: [<x_value>, <y_value>, <z_value>]

max_lock, min_lock

Vector3

A hard limit on the rig transform parameters. The Vector3 values are the limits on the x, y, and z values of the parameter. This cannot be turned off in the animate state. See transform limits for more information.

The format of the max_lock and min_lock properties is:

[max_lock|min_lock]:<parameter_name>: [<x_value>, <y_value>, <z_value>]

mapping

string

Specifies the mapping between rigs/skeletons to TransformObject nodes. This is useful for mapping skeleton joints to controls, or in the case where one rig drives another, mapping the controls between two rigs. This mapping information is stored on the TransformObject node.

The format of the mapping property is:

mapping:<skeleton|rig>: <element name or APEX path pattern>

An example of the predefined entries in the properties dictionary:

{
    "control":{
        "color":[0.5,0,1],
        "shapeoffset":[0.3,0,0,0,0,0.3,0,0,0,0,0.3,0,0,0,0,1],
        "shapeoverride":"torus",
        "visibility":1
    },
    "max:t":[5, 5, 5],
    "min:t":[-5, -5, -5],
    "max_lock:t":[10, 10, 10]
    "min_lock:t":[-10, -10, -10],
    "mapping:Base.skel":"lowerarm_l"
}

Attributes

APEX graph geometry have the following attributes:

Name

Class

Type

Description

name

point

string

The name of the node.

callback

point

string

The callback name (node type) of the node.

Cd

point

float

The color of the node.

portname

vertex

string

The name of the port.

portalias

vertex

string

The subport name or renamed ports.

portindex

vertex

int

The index number of the port.

parms

point

dict

A dictionary of default values for the ports.

tags

point

string[]

An array of strings that are used as identifiers for graph nodes. Tags can be matched using the APEX path pattern function %tag() in graph nodes like graph::FindNodes.

properties

point

dict

A dictionary of additional metadata on the node. Properties can be matched using the APEX path pattern function %properties() in graph nodes like graph::FindNodes.

Callbacks

There are special callback names for some of the graph elements:

Node

Callback name

Graph input node

__parms__

Graph output node

__output__

Subnet

__subnet__

Sticky note

__stickynote__

KineFX

Overview

Preparing character elements

Rigging with APEX graphs

Building rig graphs with APEX Script

Rigging with rig components

Animating in the viewport

SOP-based animation

Deformation

Animation retargeting

Pre-H20

Panes

Appendix