Agent geometry node

Creates agent primitives.

On this page	Parameters Input sources Character Rig Agent Definition Cache FBX USD Locals Inputs Outputs
Since	14.0

This node is used to create agent primitives for a crowd of characters. The definition of the agents come from the files previously baked from an Agent ROP, or directly from a character rig in the scene.

An agent primitive contains references to:

A rig – The transform hierarchy of the agent.
A shape library – The geometry for the agent.
Layers – An assignment of the geometry from the shape library to a transform in the rig.
Clips – The animation used by the agent.

Tip

If the render gets clipped due to bounding boxes in crowds, try creating a collision layer by turning on the Generate Collision Layer parameter.

Parameters ¶

Group

The points in the input geometry to use as agent positions.

Agent Name

The base name of the agent. For each created agent, the name primitive attribute is set to this name with a _‹number› suffix. When Allow Attributes to Override is turned on, this is replaced with any agentname string attributes on the input points.

The value of this parameter can be referenced via the $AGENT local variable.

Current Layers

The layer (or list of layers) to assign to the agent. When Allow Attributes to Override is turned on, this can be replaced with the currentlayers string array attribute (or currentlayer string attribute) on the input points.

By default, this parameter is empty, so the value of the Layer Name parameter is used. When loading from disk, the layer named default is used, if it exists. Otherwise, the first available layer in the agent definition is used.

Collision Layers

The collision layer (or list of collision layers) to assign to the agent. When Allow Attributes to Override is turned on, this can be replaced with the collisionlayers string array attribute (or collisionlayer string attribute) on the input points.

By default, this parameter is empty, so the value of the Collision Layer Name parameter is used. When loading from disk, the layer named collision is used, if it exists. Otherwise, the first available layer in the agent definition is used.

Current Clip

The name of the animation clip the agents run. When Allow Attributes to Override is turned on, this is replaced with any currentclip string attributes on the input points. By default, this parameter is empty, so the first available clip in the agent definition is used.

Clip Offset

The time into the current clip to begin playing (in seconds). When Allow Attributes to Override is turned on, and the input points contain the clipoffset float attribute, those values are added to this parameter value for each agent.

Apply Clip Locomotion

When turned on, applies the __locomotion__ transform from the agent rig so that you can easily previsualize locomotive clips.

Allow Attributes to Override

When turned on, replaces the values of Current Layer, Current Clip, and Clip Offset with values from the equivalent point attributes, if present.

Keep Primitives

Normally, primitives are deleted for the points that agents are created on. When Keep Primitives is turned on, the primitives are not deleted.

Reload

Reloads the agent definition.

Input

The source to create agents from. See input sources for details on the parameters of the sources:

Character Rig

Create the agent definition from an actual character subnetwork/asset in the scene. To share agent definitions between multiple scenes and reduce the size of caches, you may want to save the agent definition to disk.

Agent Definition Cache

Load the agent definition from disk (previously baked out using the Agent ROP or Agent Definition Cache SOP).

FBX

Get the information from an FBX file containing a character.

USD

Create the agent definition from a UsdSkel character (a USD SkelRoot primitive). The source USD stage can be a file on disk or a LOP node. The animation clip’s frame range is determined from the stage’s startTimeCode and endTimeCode metadata, which can be modified using the Configure Layer LOP.

Input sources ¶

Character Rig ¶

Character Rig

The path to the object subnetwork containing the character rig.

Traverse Outputs

When turned on, the Character Rig path is used to specify the nodes to import by traversing its outputs instead of its children.

Pattern

The pattern used to limit the nodes that should be imported. Patterns using usual opglob syntax along with @‹bundle› references are accepted.

Note

Relative paths specified here are relative to this node, not to the Character Rig.

Type

Optional mask to further restrict the object node types that are imported. Turn off the toggles to prevent baking particular types.

Minimal Nodes

When turned on, only imports objects whose display flags are on. When turned off, all the nodes in the character rig are imported into the animation clip.

Keep Transforms for Deforming Shapes

When Minimal Nodes is turned on, this specifies whether nodes containing deforming geometry are included in the agent’s rig and clips.

Shape Library

Convert to Polygon Soups

When turned on, combines polygon primitives into polygon soup primitives when creating the shape library. This can reduce memory usage, particularly when rendering with Mantra.

Layers

Layer Name

The default layer for the agent, created using the display flags of the objects. Every agent must have at least one layer.

Bounds Scale

The scale for the bounding box of each shape in the default layer. See the Agent Primitive help page for more information on how an agent’s bounding box is computed.

Generate Collision Layer

When turned on, generates a collision layer from geometry containing capture/deform weights. This generates capture region primitives and assigns them to the corresponding bones in the rig.

Collision Layer Name

When Generate Collision Layer is turned on, this is the name of the collision layer.

Clip

Clip Name

The name of the baked out clip (agent animation). The animation is taken from the current scene.

Additional Channels

Adds channels from the specified CHOP node to the agent’s clip.

Frame Range

Specifies whether to use the scene’s global frame range (Scene) or the Start/End/Inc parameters (Use Specified).

Start/End/Inc

When Frame Range is set to Use Specific, this is the start frame, end frame, and frame increment to bake out. All the values may be decimal (for example, start on frame 1.5).

Shift Clip to Frame 1

When turned on, shifts the output clips from the specified frame range to start at frame 1.

Locomotion

Create Locomotion Joint

When turned on, creates an extra joint named __locomotion__, which serves as a placeholder for factored out locomotion animation when Convert to In-Place Animation is turned on.

Convert to In-Place Animation

When turned on, converts a moving character animation to an in-place clip by subtracting the positions of the Locomotion Node (relative to the origin or where it was on the first frame depending on Use Pivot from First Frame parameter).

Locomotion Node

The object inside the Character Rig that controls the locomotion of the character (the node in the character rig that has translation channels that move it forward in space). If this parameter is empty, the Character Rig node is used. When Convert to In-Place Animation is turned on, Houdini uses Locomotion Node to remove the translation from the character animation to keep the character in place. (The crowd solver node assumes that the agent animation is in-place since it is attached to a moving particle.)

The locomotion animation is placed in a separate transform in the rig named __locomotion__.

Locomotion Orient

If this parameter and Locomotion Node are specified, the generated __locomotion__ transform also contains rotational information using the vector from the Locomotion Node to the Locomotion Orient node. If this transform is the same as the Locomotion Node, its orientation is directly extracted. This parameter has no effect if Locomotion Node is empty.

Project Positions on Dominant Axis

When creating the animation of the Locomotion Node, turning this on projects the positions along the dominant axis of motion in the XZ plane. If the clip is used as an in-place clip with the crowd solver, turning on this option can help to maintain hip swaying in the motion.

Use Pivot from First Frame

When creating the animation of the Locomotion Node, turning this on calculates the positions to be relative to the origin. If this option is turned off (the default), the positions are relative to where it was on the first frame.

Agent Definition Cache ¶

Cache Directory

The parent directory of the agent definition files. This parameter is provided for convenience so that its value can be referenced via the $CACHEDIR local variable in the other filename parameters.

Rig

The path to the agent’s rig file.

Agent Layers

The filename pattern of the agent layer files to load. The ${LAYER} local variable is used as a * placeholder here so that all the matching files are loaded for the agent.

Shape Library

The path to the agent’s shape library.

Clips

The filename pattern of the animation clips to load. The ${CLIP} local variable is used as a * placeholder here so that all the matching files are loaded for the agent. The actual name of the clip is inferred from the string matched by ${CLIP}, or the full filename without the extension if ${CLIP} is not used.

Transform Groups

The filename pattern of the transform group files to load. The ${TRANSFORM_GROUP} local variable is used as a * placeholder here so that all the matching files are loaded for the agent.

Metadata

The path to the agent’s optional metadata file.

Keep External References

When turned on, the .bgeo file stores the file paths to the agent definition components (for example, paths to the .bclip files for each animation clip) when saving agents to a geometry file. When turned off, the agent definition is embedded in the .bgeo file, which produces a self-contained, but larger, geometry file.

Delay Load Clips

When turned on, clips are only loaded from disk when their data is needed. This can improve load times and memory usage for large clip catalogs, but errors from loading clips may not be reported immediately.

FBX ¶

FBX File

The filename of the FBX file to generate agents from.

Import Principled Shader Values

When turned on, creates the material_override attribute inside the shape geometry, which imports the material values from the FBX that are suitable for use with Houdini’s Principled Shader material.

Note

In order to get accurate texture paths, this causes the FBX file to be imported with “Extract Embedded Data” enabled, which causes .fbm directories on disk to be created with the textures extracted within them.

Convert Units

When turned on, converts to Houdini units when importing the FBX file.

Remove Namespaces from Joint Names

When turned on, joint names imported from the FBX File are stripped of any namespace prefixes.

Minimal Nodes

When turned on, only imports objects whose display flags are on. When turned off, all the nodes in the character rig are imported into the animation clip.

Keep Transforms for Deforming Shapes

When Minimal Nodes is turned on, this specifies whether nodes containing deforming geometry are included in the agent’s rig and clips.

Shape Library

Load as Polygon Soups

When turned on, creates polygon soup primitives instead of polygon primitives when loading geometry from the FBX file. This can reduce memory usage, particularly when rendering with Mantra.

Include Unused Capture Regions

When importing a skinned mesh with this option turned on, additional capture regions with identity transforms are added to the boneCapture attribute for the ancestor joints of any captured joints. It is recommended to only turn on this option for compatibility with older scene files, as it can introduce issues with unpacking or merging the rest geometry of multiple skinned shapes.

Layers

Layer Name

The default layer for the agent, created using the display flags of the objects. Every agent must have at least one layer.

Bounds Scale

The scale for the bounding box of each shape in the default layer. See the Agent Primitive help page for more information on how an agent’s bounding box is computed.

Generate Collision Layer

When turned on, generates a collision layer from geometry containing capture/deform weights. This generates capture region primitives and assigns them to the corresponding bones in the rig.

Collision Layer Name

When Generate Collision Layer is turned on, this is the name of the collision layer.

Clip

Clip Name

The names of the animation clip(s). A clip is created for each take in the FBX file. The ${FBX_TAKE_NAME} and ${FBX_TAKE_INDEX} local variables can be used to generate clip names based on the take name and index from the FBX file.

Sample Rate

When turned on, uses the specified sample rate for the clip instead of the sample rate stored in the FBX file. This is useful if the application that exported the original FBX file did not set the sample rate correctly.

Locomotion

Create Locomotion Joint

When turned on, creates an extra joint named __locomotion__, which serves as a placeholder for factored out locomotion animation when Convert to In-Place Animation is turned on.

Convert to In-Place Animation

When turned on, converts a moving character animation to an in-place clip by subtracting the positions of the Locomotion Node relative to the origin.

Locomotion Node

The node inside the FBX scene that controls the locomotion of the character (the node in the character rig that has translation channels that move it forward in space). If this parameter is empty, the FBX scene’s root node is used. When Convert to In-Place Animation is turned on, Houdini uses this parameter to remove the translation from the character animation to keep the character in place. (The crowd solver node assumes that the agent animation is in-place since it is attached to a moving particle.)

The locomotion animation is placed in a separate transform in the rig named __locomotion__.

Locomotion Orient

Project Positions on Dominant Axis

USD ¶

Source

Specifies whether the source USD stage is from a LOP node or USD file on disk.

LOP Path

When Source is set to LOP, this is the path to a LOP node. The agent definition is constructed from a UsdSkel character in the USD stage output by this node.

USD File

When Source is set to File, this is the path to a USD file on disk.

SkelRoot Primitive Path

The path of a SkelRoot primitive in the USD stage. If the path is empty, the first SkelRoot prim in the stage is used.

Purpose

Sections of a USD hierarchy can be marked to be used for a specific purpose. Only sections marked as the default purpose or one of the specified purposes are traversed when unpacking the USD packed primitives.

Layers

Layer Name

The default layer for the agent, created using the display flags of the objects. Every agent must have at least one layer.

Bounds Scale

The scale for the bounding box of each shape in the default layer. See the Agent Primitive help page for more information on how an agent’s bounding box is computed.

Generate Collision Layer

When turned on, generates a collision layer from geometry containing capture/deform weights. This generates capture region primitives and assigns them to the corresponding bones in the rig.

Collision Layer Name

When Generate Collision Layer is turned on, this is the name of the collision layer.

Clip

Clip Name

The name of the baked out clip (agent animation). The animation is taken from the current scene.

Frame Range

Specifies whether to use the time code range from the stage’s metadata (Stage), the range of time samples from the SkelAnimation prim and the Skeleton prim’s transform (Skeleton Animation), or the Start/End/Inc parameters (Use Specific).

Start/End/Inc

When Frame Range is set to Use Specific, this is the start frame, end frame, and frame increment to bake out. All the values may be decimal (for example, start on frame 1.5).

Locomotion

Create Locomotion Joint

When turned on, creates an extra joint named __locomotion__, which serves as a placeholder for factored out locomotion animation when Convert to In-Place Animation is turned on.

Convert to In-Place Animation

When turned on, converts a moving character animation to an in-place clip by subtracting the positions of the Locomotion Node relative to the origin.

Locomotion Node

The name of the joint that controls the locomotion of the character (the joint in the skeleton that has translation channels that move it forward in space). When Convert to In-Place Animation is turned on, Houdini uses this parameter to remove the translation from the character animation to keep the character in place. (The crowd solver node assumes that the agent animation is in-place since it is attached to a moving particle.)

The locomotion animation is placed in a separate transform in the rig named __locomotion__.

Locomotion Orient

Locals ¶

AGENT

The name of agent. The value either comes from the agentname string attribute on the input points when Allow Attributes to Override is turned on, or from the value of the Agent Name parameter.

CACHEDIR

A local variable provided for convenience so that the value of the Cache Directory parameter can be easily referenced.

LAYER

Used as a wildcard in the Agent Layers parameter for specifying the layer files to load.

CLIP

Used as a wildcard in the Clips parameter for specifying the clip files to load.

TRANSFORM_GROUP

Used as a wildcard in the Transform Groups parameter for specifying the transform group files to load.

FBX_TAKE_NAME

Contains the name of the current take in the FBX file when evaluating the Clip Name parameter, and Input is set to FBX.

FBX_TAKE_INDEX

Contains the index of the current take in the FBX file when evaluating the Clip Name parameter, and Input is set to FBX.

Inputs ¶

Points to spawn agents

If provided, the input points are used to spawn the agents. These points may contain specific attributes that are used to control the properties of the created agents, allowing for multiple agent definitions to be used via the $AGENT local variable.

Outputs ¶

Output

The agent primitives that are created. If the optional input is provided, there is an agent primitive for each input point. Otherwise, a single agent is created.

Parameters ¶

Input sources ¶

Character Rig ¶

Agent Definition Cache ¶

FBX ¶

USD ¶

Locals ¶

Inputs ¶

Outputs ¶

Geometry nodes