Houdini 20.5 Character KineFX

APEX graph basics

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.

APEX (All-Purpose EXecution) is a graph evaluation framework that builds and runs graphs, and outputs their results. In KineFX, character rigs are represented using APEX graphs.

A graph is a piece of logic that, when evaluated, performs a specific task. Graphs can be built up to perform more complex functionality like determining how an entire character behaves, complete with an FK hierarchy for the skeleton, and logic to deform geometry. Graphs take in data in the form of input parameters, perform operations on the data, and make data available as outputs. Within a graph, geometry can be manipulated alongside other types, so you can, for example, perform numerical operations on skeleton joint transforms all in one graph:

Numerical operations alongside geometry in an APEX graph

In the SOP context, APEX graphs are a piece of geometry. The rig logic represented by an APEX graph is built up in the SOP network as the graph is passed from SOP node to SOP node, with pieces of logic added to or changed on the graph along the way. When building of the graph is complete, the rig logic is evaluated at a point in the network of your choosing (using the APEX Invoke Graph SOP or Python SOP), or through a specific action in the viewport.

This idea of delayed evaluation of the rig logic allows you to procedurally build up rig logic pieces and assemble them together without having the rig constantly evaluating and calculating, which significantly impacts performance. Delayed evaluation also allows you to choose when and where to evaluate the rig. The example below shows two different ways that rig logic can be added to a character. In both cases, there is a clear delineation between the rig logic and rig evaluation:

Delayed rig evaluation

APEX sits at a layer below SOPs and is not tied to any network context. You can build, manipulate, and run APEX graphs using the Python API, other APEX graphs, and SOPs. In the future, there may be other contexts that can access and utilize APEX graphs.

Note

For users who are familiar with VOPs and VEX, APEX is a mid-level visual programming framework - higher than VEX and lower than SOPs. In VOPs, we are limited to the types that VEX understands. APEX is essentially procedural VOPs with support for more types (via an extensible type system).

The type of data that APEX graphs can output is limited only by the context within which the graph is run. When run in SOPs, graphs can output geometry, as well as any data that can be stored in a dictionary attribute on the geometry. When run in Python, graphs can output the types that can be cast to a Python type.

Visualizing graphs

The APEX network view is a UI that is used to visualize APEX graphs. To open the APEX network view, click the New Tab icon at the top of a pane and select New Pane Tab Type ▸ Animation ▸ APEX Network View. You can also manually build a graph in the APEX network view while on an APEX Edit Graph SOP. See graphs for numerical operations for some examples.

The structure of a graph is represented as geometry, where the graph nodes are represented as points in the viewport, and the connections between the nodes are represented as lines between the points. In the example below, the positions and colors of the graph nodes and their connections directly correlate to the points and lines in the viewport:

Graph in the APEX network view
APEX graph represented in the viewport

When the positions and colors of the graph nodes change, this is reflected in the viewport geometry:

Graph in the APEX network view
APEX graph represented in the viewport

The components of the graph and geometry have the following correlation:

Graph (visualized in the APEX network view)

Geometry (visualized in the viewport)

Nodes

Points

Wires

Line primitives

Input and output ports on connected nodes

Vertices

Input parameters on the graph input node

Parameters stored on the geometry

Graph nodes, subgraphs, and subnets

Graph nodes perform a specific operation and can be APEX functions, verbs, subgraphs, or subnets.

APEX functions

APEX functions perform a specific operation on whatever is connected to its input ports.

Verbs

A verb is the basic operation of an OP node. It does not include other operations that relate to the node like caching, reading inputs, and evaluating parameters. For example, the Joint Deform SOP is an HDA wrapper around the bonedeform verb, so Joint Deform cannot be used in APEX graphs, but bonedeform can.

Subgraph

A subgraph is a locked graph and is similar to an HDA in that modifying a subgraph modifies all instances of the subgraph. The SmoothIk node is an example of a subgraph.

Subgraphs are stored as a subgraph library in a .bgeo geometry file. A subgraph library has the following structure:

  • A single unpacked APEX graph, where the subgraph name is defined by the name detail attribute.

    or

  • A number of packed geometry primitives, each containing an APEX graph. For each of the primitives, the subgraph name is defined by the top-level name primitive attribute.

The subgraph .bgeo files are loaded from the @/apexgraph directories, where @ expands to the directories in the HOUDINI_PATH.

Subnet

A subnet is a container that encapsulates multiple graph nodes inside a single node. Subnets help to simplify and improve the readability of a graph. If you create several subnets with the same contents, updating one of the subnets will not affect the others.

To...Do this

Save an unpacked graph to a subgraph library file

When saving an unpacked APEX graph to a subgraph library file, a name detail attribute must be created on the graph. Subgraph nodes that are created in the APEX network view are defined by this name attribute.

Save unpacked graph to a subgraph library

  1. Create the name attribute using an Attribute Create SOP:

    • Set Name = name.

    • Set Class to Detail.

    • Specify the name you would like for your subgraph in the String parameter. This is the name that will appear when searching for the subgraph in the TAB menu of the APEX network view.

  2. Save the subgraph to a subgraph library file using a ROP Geometry Output SOP:

    • Set the Output File parameter to the path and filename for the subgraph library (.bgeo) file. The subgraph library file must be saved in a directory named apexgraph in the HOUDINI_PATH, for example, $HIP/apexgraph/test.bgeo.

    • Click Save to Disk.

To load the saved subgraph:

  1. Open a Python Shell, Windows ▸ Python Shell, and run the following commands:

    import apex
apex.Registry().reloadSubgraphs()

  2. Select an APEX Edit Graph SOP in the network editor or put down a new APEX Edit Graph SOP. You can now search for the subgraph in the APEX network view using the TAB menu.

Save packed graphs to a subgraph library file

Use a Pack Folder SOP to add graphs to a packed folder structure. The Pack Folder SOP creates a name primitive attribute for each of the graphs:

Save packed graphs to a subgraph library

  1. In the Pack Folder SOP:

    • Turn on Pack Output to pack the subgraphs.

    • Turn on Only Pack Unpacked so that an additional level of packing is not added to the subgraphs that are already packed.

    • The Name parameter is automatically populated when an input is connected to the Pack Folder SOP. The order of the inputs to the Pack Folder SOP corresponds to the order that the Name parameters are listed.

      Set the Name parameters to the names you would like for each of the subgraphs. These are the names that will appear when searching for the subgraphs in the TAB menu of the APEX network view. Leave the Type parameter empty so that no extension is added to the subgraph node name.

  2. Save the subgraphs to a subgraph library file using a ROP Geometry Output SOP:

    • Set the Output File parameter to the path and filename for the subgraph library (.bgeo) file. The subgraph library file must be saved in a directory named apexgraph in the HOUDINI_PATH, for example, $HIP/apexgraph/test.bgeo.

    • Click Save to Disk.

To load the saved subgraphs:

  1. Open a Python Shell, Windows ▸ Python Shell, and run the following commands:

    import apex
apex.Registry().reloadSubgraphs()

  2. Select an APEX Edit Graph SOP in the network editor or put down a new APEX Edit Graph SOP. You can now search for the subgraph in the APEX network view using the TAB menu.

Update all subgraph instances

After making changes to a subgraph, update all the subgraph instances by doing the following:

  1. Save the subgraph to a subgraph library (.bgeo) file. In the ROP Geometry Output SOP, click Save to Disk.

  2. Open a Python Shell, Windows ▸ Python Shell, and run the following commands:

    import apex
apex.Registry().reloadSubgraphs()

Create a subnet

  1. Box select the graph nodes you want to put into a subnet.

  2. click the selected nodes ▸ Collapse to Subnet.

Change the port name of a subnet

Dive into the subnet and change the port name on the graph input or output node. Rename ports by clicking the port name.

Note

Only subports can be renamed. “Regular” ports cannot be renamed. Subports are created when connections are made to variadic ports. See ports for more information.

Ports

Connections between nodes are made when wires are created between the ports on the nodes. Port values come from either port connections, the values set in the node parameter window, or certain default values. The node parameter window is used for editing the port’s values in the APEX network view. To bring up the node parameter window, select a graph node and press P.

Port

Value

Connected ports

Values from connections override the values set inside the node parameter window.

Unconnected ports

Unconnected port values come from either the values set in the node parameter window, the corresponding SOP verb node, or default values set internally in APEX.

Node parameter window

Ports that appear in the node parameter window with a black background are present in the geometry spreadsheet parms point attribute. Ports appear in the parms attribute when:

  • The port value is set directly in the node parameter window.

  • A SOP node is imported to an APEX graph (for example, using the APEX Edit Graph SOP’s Import SOP Nodes button), and non-default SOP parameter values were specified in the SOP node (in the parameter editor).

Ports that appear in the node parameter window with a gray background are not present in the parms attribute. These port values are set according to the following:

  • For SOP verb nodes, the port is set to the SOP verb node’s default parameter value.

  • For non-SOP verb nodes, the port is initialized to a default value defined internally in APEX.

Note

The values displayed in the node parameter window are not always the values used by the ports. If a port is not present in the geometry spreadsheet parms point attribute, its corresponding value in the node parameter window is not used.

Different port colors refer to different data types on the port. There are also two special types of ports - variadic ports and in-place ports:

Variadic port

Multiple connections can be made to a variadic port, which creates subports on the node. The port next is an example of a variadic port that exists on several nodes. Other examples of variadic ports are the b port on the Add node, and the transforms port on the skel::GetPointTransforms and skel::SetPointTransforms nodes.

Connecting to variadic ports

Note

Only subports can be renamed. “Regular” ports cannot be renamed. Rename subports by clicking the subport name.

In-place port

The value of in-place ports are updated without creating a copy. In-place ports are identified with a square:

How-to

To...Do this

Change the parameter values on a graph node

Select a graph node and press P to bring up the node parameter window.

Rename a subport on the graph

click the subport name.

Keep a particular graph visible in the APEX network view

Click the icon on the top toolbar to pin the graph. The icon will change to .

Unpin the graph if you want the APEX network view to follow the SOP node selection in the network editor.

Lay out the graph nodes

Connect your graph (for example, the APEX Edit Graph SOP) to an APEX Layout Graph SOP.

Delete a wire on the graph

Hold Y and drag across the wire.

or

Select the wire and press Delete.

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