Houdini 21.0 Character KineFX

APEX path pattern

On this page

Overview

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

APEX graphs

APEX path patterns are used in graph nodes like graph::FindNodes and graph::FindPorts to find specific groups of nodes and ports. APEX path patterns can also be used to filter for graph metadata like tags and properties. Tags on graph nodes are used extensively in pre-built rig components to label and find nodes in a rig.

Skeletons and geometry

APEX path patterns are used in graph nodes like skel::FindJoints and skel::FindFirstJoint to find specific points in a geometry or joints in a skeleton (a skeleton is a hierarchy of points). APEX path patterns can also be used to filter for skeleton metadata like tags and properties. Tags are used to label skeleton joints, which are then picked up by pre-built rig components to build up the rig functionality of a character.

Packed character folder structure

APEX path patterns are used in the Unpack Folder SOP to extract specific elements from the nested packed character folder structure, which stores character elements for animation.

APEX path pattern syntax

The rules of the APEX path pattern syntax are listed in the table below. The “hierarchy levels” in the table refer to:

  • Nested subnets (for APEX graphs).

  • Levels within the skeleton hierarchy. If the geometry is not a skeleton (hierarchy), all the points are considered to be at the first hierarchy level.

  • Nested folders in the packed character folder structure.

Syntax

Description

*

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_.

**

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 packed character folder structures, and not graph elements or geometry points.

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 space are returned.

  • “&” operates like an “and” operation. Elements that match the patterns on both sides of the “&” are returned.

  • “-” operates like a subtraction operation. Elements that match the first pattern but not the second are returned.

    For example, root/* - *ext returns all the elements in root that don’t end with ext.

()

Parentheses indicate the order of execution for combined patterns.

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

Port syntax for APEX graphs

For APEX graphs, the graph::FindPorts node can filter for graph ports 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 input variadic port xform on any node that starts with joint_.

Functions

APEX path pattern functions perform specific filtering operations on graphs, graph nodes, ports, and geometry points. Functions are not used for packed character folder structures.

In the APEX path pattern syntax, functions are preceded by a “%”, and can take in multiple arguments:

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

There is also an alternative syntax for specifying a tag using a “#” before the tag name, for example, #<tag_name>.

APEX graph functions

Node functions

The following functions operate on nodes:

Function

Description

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

Finds the graph nodes that are ancestors of the node in <node_path>.

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

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

As a short form, you can use i for the inclusive option, t for traverse, or it for both.

Examples:

  • %ancestors(<node>)

  • %ancestors(<node>, inclusive)

  • %ancestors(<node>, traverse)

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

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

  • %ancestors(<node>, i, t)

  • %ancestors(<node>, it)

%callback(<callback_name>)

A callback is the type of an APEX graph node, for example, graph::AddNode. %callback 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, %callback(graph*).

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

Finds the graph nodes that are descendants of the node in <node_path>.

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

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

As a short form, you can use i for the inclusive option, t for traverse, or it for both.

Examples:

  • %descendants(<node>)

  • %descendants(<node>, inclusive)

  • %descendants(<node>, traverse)

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

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

  • %descendants(<node>, i, t)

  • %descendants(<node>, it)

%isconnected()

Finds the nodes that have connections. A node is considered to be connected if any of its ports are connected.

%ispromoted()

Finds the nodes that are promoted as inputs or outputs (connected to the graph’s input or output node). It also finds nodes in nested subnets that are promoted up the chain to the top-level graph input or output node.

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

Properties are stored in the properties dictionary attribute on a 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>)

Tags are stored in the tag string array attribute on a node. The %tag function finds the nodes on all subnet levels that contain the tag <tag_name>.

Wildcards can be specified in <tag_name>, for example, %tag(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 tag <tag1>, <tag2>, or <tag3>.

#<tag_name>

In addition to the %tag function, you can also filter for tags using a “#” before the tag name, for example, #left.

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

Unlike %tag, <tag_name> in #<tag_name> cannot contain spaces.

Port functions

The following functions operate on ports:

%isconnected()

Finds the ports that are connected.

%ispromoted()

Finds the ports that are promoted as inputs or outputs (connected to the graph’s input or output node). It also finds ports in nested subnets that are promoted up the chain to the top-level graph input or output node.

%tag(<tag_name>)

Tags are stored in the tag string array attribute on a node. The %tag function finds the ports on all subnet levels that contain the tag <tag_name>.

Port tags are stored on graph nodes in the format <port>:<tag>. When using %tag to find ports, only specify the tag name, not the port name. For example, use %tag(xyz), not %tag(r:xyz).

Wildcards can be specified in <tag_name>, for example, %tag(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 tag <tag1>, <tag2>, or <tag3>.

#<tag_name>

In addition to the %tag function, you can also filter for tags using a “#” before the tag name, for example, #left.

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

Unlike %tag, <tag_name> in #<tag_name> cannot contain spaces.

%valuetype(<type_name>)

Finds the ports that have the value type <type_name>, for example, %valuetype(Vector3).

Wildcards can be specified in <type_name>, for example, %valuetype(Vector*).

Skeleton and geometry functions

In the descriptions below, <joint_pattern> is the pattern that is used to filter for skeleton joints. <joint_pattern> can contain APEX path patterns and APEX path pattern functions.

Function

Description

%ancestors(<joint_pattern>, [<start>], [<steps>])

Operates on skeletons. Finds the joints that are ancestors of the joints in <joint_pattern>.

<start> - From the joints in <joint_pattern>, this is the number of levels to go up the hierarchy before returning the ancestor joints. This value is optional and defaults to 1.

<steps> - The number of levels of joints to match after <start>. A negative value matches all the joints after <start>. This value is optional and defaults to -1.

For example, if we have the hierarchy, root → pelvis → thigh → calf:

  • %ancestors(calf_l) matches the thigh, pelvis, and root.

  • %ancestors(calf_l, 0) matches the calf, thigh, pelvis, and root.

  • %ancestors(calf_l, 2) matches the pelvis and root.

  • %ancestors(calf_l, 0, 0) matches the calf.

  • %ancestors(calf_l, 1, 1) matches the thigh and pelvis.

%children(<joint_pattern>)

Operates on skeletons. Finds the joints that are children of the joints in <joint_pattern>.

%descendants(<joint_pattern>, [<start>], [<steps>])

Operates on skeletons. Finds the joints that are descendants of the joints in <joint_pattern>.

<start> - From the joints in <joint_pattern>, this is the number of levels to go down the hierarchy before returning the descendant joints. This value is optional and defaults to 1.

<steps> - The number of levels of joints to match after <start>. A negative value matches all the joints after <start>. This value is optional and defaults to -1.

For example, if we have the hierarchy, calf → ball → foot:

  • %descendants(calf) matches the ball and foot.

  • %descendants(calf, 0) matches the calf, ball, and foot.

  • %descendants(calf, 2) matches the foot.

  • %descendants(calf, 0, 0) matches the calf.

  • %descendants(calf, 1, 2) matches the ball and foot.

%group(<group>)

Operates on any geometry. Finds the points on a geometry that match <group>. <group> uses the Houdini group syntax, for example, %group(@P.x>0).

%leaves([<joint_pattern>])

Operates on skeletons. Finds the joints that are the leaves of the skeleton.

The optional <joint_pattern> finds the leaves of the joints matched by the pattern.

%parents(<joint_pattern>)

Operates on skeletons. Finds the joints that are the parents of the joints in <joint_pattern>.

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

Operates on any geometry. Properties are stored in the properties dictionary attribute on a point. The %properties function finds all the points 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. <value> can be an integer or string.

%roots([<joint_pattern>])

Operates on skeletons. Finds the joints that are the roots of the skeleton.

The optional <joint_pattern> finds the roots of the joints matched by the pattern.

%tag(<tag_name>)

Operates on any geometry. Tags are stored in the tag string array attribute on a point. The %tag function finds the points on the geometry that contain the tag <tag_name>.

Wildcards can be specified in <tag_name>, for example, %tag(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 point with tag <tag1>, <tag2>, or <tag3>.

#<tag_name>

Operates on any geometry. In addition to the %tag function, you can also filter for tags using a “#” before the tag name, for example, #left.

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

Unlike %tag, <tag_name> in #<tag_name> cannot contain spaces.

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