Houdini 20.5 Character KineFX

APEX path pattern

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.

Overview

The APEX path pattern syntax is a set of rules that allow you to filter and select specific elements within APEX graphs and the packed character format:

APEX graph elements

Rig component scripts use APEX path patterns to find specific groups of graph nodes and ports (via graph::FindNodes and graph::FindPorts). APEX path patterns can also be used to filter additional metadata on graph nodes in the form of tags and properties, which are used to mark and store data on nodes.

Packed character format

APEX path patterns are used in the Unpack Folder SOP to extract specific elements from the nested folder structure of the packed character format.

APEX path pattern syntax

The rules of the APEX path pattern syntax are listed in the table below. The “hierarchy levels” mentioned in the table refer to nested subnets (for APEX graphs), and nested folder structures (for the packed character format).

Syntax

Description

*

An asterisk matches any number of characters in a name.

For example, root/*/element_* matches any element two levels down from root whose name starts with element_.

**

Two asterisks matches any number of hierarchy levels.

For example, **/*ext matches any element that ends with ext at any hierarchy level.

?

Matches any single character.

[]

Matches any single character within the brackets.

For example, root/object[1234] matches elements in root whose names are object1, object2, object3, or object4.

{}

Groups and attributes are put inside braces.

For example, {@name=test3.rig @index=2-3} matches test3.rig, as well as all elements with an index attribute of 2 or 3.

Note

Pattern matching with groups and attributes are only supported for the packed character format, and not for graph elements.

Combine patterns with &, + and -

Multiple patterns can be combined with the &, + and - operators. Pattern matches are applied from left to right.

  • “+” or a space operates like an “or” operation. Elements that match any of the patterns separated by a “+” or a space are returned.

  • “&” operates like an “and” operation. Any element that matches both of the patterns on either side of the “&” is returned.

  • “-” operates like a subtraction operation. Any element that matches the first pattern but not the second pattern is returned.

    For example, root/* - *ext matches all elements in root, but not the elements that end with ext.

()

Parentheses indicate the order of execution for combined patterns.

For example, root/left* - (*arm & *leg) matches all elements in root that start with left, but not the elements that end with arm or leg.

Graph ports

Ports on APEX graph nodes can be filtered in the graph::FindPorts node using the following syntax:

<node_path>:<port_name>[in|out][<subport_name>]

  • The optional [in]/[out] specifies whether the port is an input or output port on the node.

  • The optional [<subport_name>] specifies the subport name of the variadic port <port_name>.

For example, joint_*:xform[in][leg] matches the subport named leg on the xform input variadic port of any node with a name that starts with joint_.

Tags

Tags are identifiers that are used to mark and access graph nodes. They are metadata on graph nodes that are stored in the string array attribute called tags. Tags can be used to filter for nodes, which allow you to identify single nodes or groups of nodes independent of its element names. This is useful, as element names on rigs and graphs often change.

Tags need to be stored in a particular format so that APEX can recognize it and filter for it based on the APEX path pattern syntax.

Note

Tags are only used for nodes; there are no port tags.

Tags can be created on graph nodes using array::Build<String>, which creates an array of strings that is then used to populate a node’s tag attribute. The example graph below builds another graph that contains a single node with its tag attribute populated.

Graph that creates tags on a node

Graph Node

Description

tag_value*

The 3 Value nodes are set to string values node_tag1, node_tag2, and node_tag3. The values are set in the node parameter window by selecting the node and pressing P.

build_tags

Builds an array of strings using the values from the 3 Value nodes.

new_node

Creates a new node with its tags attribute set to the string array from build_tags.

The network below constructs the final graph using the graph “script”:

Create the final graph

SOP Node

Description

graph_script

The graph that is used to build another graph.

build_final_graph

Builds the final graph and stores it in Base.rig. Set the Component parameter to Use Second Input.

The resulting graph contains a single node named node_test. To view the graph:

  1. Set Show to Rig.

  2. Open the APEX network view.

    Resulting graph

To view the tags on the node_test graph node:

  1. Extract the graph using an Unpack Folder SOP.

    Extract resulting graph

  2. Select the resulting_graph node in the network view. Make sure Unpack Contents is turned on.

  3. In the geometry spreadsheet, select Points from the top toolbar:

    Tags displayed in geometry spreadsheet

To update the tags on a graph node, use graph::UpdateNode and graph::UpdateNodeTags.

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. Users can add and modify data in the properties dictionary using graph::UpdateNode and graph::UpdateNodeProperties.

The properties dictionary also contains predefined entries that store information on control shapes, rig parameter limits, and rig/skeleton mapping. See properties for more information.

Note

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

To view the properties on graph nodes:

  1. In the geometry spreadsheet, select Points from the top toolbar.

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

Functions

Functions perform specific filtering operations on graphs, graph nodes, and ports. Functions are not used in the packed character format.

In the APEX path pattern syntax, functions are preceded by a %, and can take in multiple arguments, depending on the specific function:

%<function>(<argument1>, <argument2>, ...)

Function

Operates On

Description

%ancestors(<node_path>, [traverse, inclusive])

Nodes

Finds all the graph nodes that have ancestor connections starting from the node specified in <node_path>.

The inclusive option includes the node in <node_path> in the list of nodes returned. For example, %ancestors(trs_output, inclusive) returns all the ancestors of trs_output, as well as trs_output itself.

The traverse option returns all the ancestors of <node_path>, including those within subnets and templates.

Examples:

  • %ancestors(<node>)

  • %ancestors(<node>, traverse)

  • %ancestors(<node>, inclusive)

  • %ancestors(<node>, inclusive, traverse)

  • %ancestors(<node>, traverse, inclusive)

%callback(<callback_name>)

Nodes

Finds the graph nodes at all subnet levels that match the callback name <callback_name>. Callback names are stored in the callback attribute on a node.

Wildcards can be specified in <callback_name>, for example, graph_*.

%descendants(<node_path>, [traverse, inclusive])

Nodes

Finds all the graph nodes that have descendant connections starting from the node specified in <node_path>.

The inclusive option includes the node in <node_path> in the list of nodes returned. For example, %descendants(trs_output, inclusive) returns all the descendants of trs_output, as well as trs_output itself.

The traverse option returns all the descendants of <node_path>, including those within subnets and templates.

Examples:

  • %descendants(<node>)

  • %descendants(<node>, traverse)

  • %descendants(<node>, inclusive)

  • %descendants(<node>, inclusive, traverse)

  • %descendants(<node>, traverse, inclusive)

%isconnected()

Nodes, ports

Finds all the nodes/ports that have connections.

%ispromoted()

Nodes, ports

Finds all the nodes/ports that are promoted as an input or output (connected to the graph input and output nodes). It also finds nodes and ports in nested subnets that are promoted up the chain to the top-level graph input and output nodes.

%properties(<property_name>, [<value>])

Nodes

Node properties are stored in the properties dictionary attribute on a graph node. The %properties function finds all the nodes that contain an entry in its properties dictionary attribute with a key that matches <property_name>.

The value of the property can be provided as an optional second argument.

%tag(<tag_name>)

Nodes

Finds the nodes on all subnet levels that contain the tag <tag_name>. Tags are stored in the tag attribute on a node.

Wildcards can be specified in <tag_name>, for example, left_*.

There can be multiple entries within <tag_name>, with each entry separated by a comma or space. For example, %tag(<tag1>, <tag2> <tag3>) matches any node with a tag of <tag1>, <tag2>, or <tag3>.

%valuetype(<type_name>)

Ports

Finds all the ports that have the value type <type_name>, for example, Vector3 or Matrix3.

Wildcards can be specified in <type_name>, for example, Vector*.

KineFX

Preparing character inputs

Rigging with rig components

Rigging with APEX graphs

Building graphs with APEX Script

Animating in the viewport

Technical Animation

Deformation

Animation Retargeting

Pre-H20

Panes

Appendix