Houdini 22.0 Nodes Geometry nodes

Attach Joint Geometry geometry node

Creates control geometry for SOP-based KineFX rigs.

On this page
Since 19.0

This node attaches control geometry in the form of packed or unpacked geometry primitives to the points (most often joints) on the first input without modifying their hierarchy. It creates the necessary attributes for KineFX’s interactive tools to recognize these geometry primitives as selectors for their associated points.

If you want to provide a library of control shapes to choose from, the second input (Shape Library input) can take multiple primitives. This geometry can be packed or unpacked primitives, but the primitives must have name attributes in order to be attached as controls.

If you want to reuse a series of shape assignments that you have already defined, you can save the existing shape assignments as a shape template. You can then use this shape template by connecting it to the third input (Shape Template input) of any Attach Joint Geo SOP.

Note

Controls inherit their transforms from the points they are attached to. If you cannot see the control geometry in the viewport, check the skeleton’s joint scales, as they may have caused the controls to be scaled down.

For more information about working with controls in KineFX, see setting up control shapes.

Tip

As an alternative to creating control geometry directly in the scene, you can also use the following:

  • A File SOP to reference a .bgeo file on disk that contains all the primitives you want to use as controls.

  • A Skeleton SOP to create the KineFX points you can use as controls.

State

Attach Joint Geo viewport state toolbar

The top toolbar of the Attach Joint Geo viewport state has the following options:

Create New Group

If no points are selected in the viewport, this button creates an empty Assign Shapes multiparm.

If there are points selected in the viewport, this button creates a new Assign Shapes multiparm and adds the @names of the seleted points to its Group parameter field.

Mode

Assign Shapes

When you select a point or ⇧ Shift click multiple points in the viewport, a new Assign Shapes multiparm is automatically created for those points and their @names are added to its Group parameter field. You can then use to assign any of the control shapes in the shape library (on the second input) as the Shape Name for the multiparm.

Tweak Shapes

When you select a point or ⇧ Shift click multiple points in the viewport and press G, a new Tweaks multiparm is created for the points and their @names are automatically added to its Group parameter field.

Assign in World Space

When turned on, allows you to see and select unassigned world space control shapes in the viewport. Unassigned world space control shapes appear light blue in the viewport state. This option is available when Mode is set to Assign Shapes.

Offset Mode

Determines how the specified local transform offset behaves in relation to the other offset values supplied by a shape template and/or offset attribute. This option is available when Mode is set to Tweak Shapes.

Override

The specified offset overrides the existing offset, replacing it.

Pre-Multiply

The specified local transform offset is applied additively to the existing offset.

Attach Joint Geo viewport state hotkeys

Hotkeys

Action

click

Selects a point in the input skeleton.

G

When in Assign Shapes mode, creates a new Assign Shapes multiparm for the selected point(s).

When in Tweak Shapes mode, creates a new Tweaks multiparm for the selected point(s).

⌃ Ctrl + G

When in Assign Shapes mode, removes the selected point(s) from their current Assign Shapes multiparm.

When in Tweak Shapes mode, removes the selected point(s) from their current Tweaks multiparm.

When in Assign Shapes mode, allows you to scroll through the list of available library shapes and select one to add to the Assign Shapes multiparm.
Attach Joint Geo viewport state right-click menu

click in the Attach Joint Geo viewport state to see the following options:

Create New Group

Creates a new Assign Shapes multiparm for the selected point(s).

Remove Joints from Groups

Removes the selected point(s) from their current Assign Shapes multiparm Group assignment.

Display Joints

When turned on, displays the skeleton joints.

Display Joint Axes

When turned on, displays the X, Y, and Z axes for each joint.

Display Links

When turned on, displays a visual representation of the parent-child relationships between the joints.

Solid Links

When turned on, the links appear shaded. When turned off, the links appear as wireframes. This option is available when Display Links is turned on.

Show Geometry

When turned on, displays the poly lines that connect the joints into a hierarchy.

Attach Joint Geo viewport state visualizations

A select point is highlighted in yellow, and a selected point that has been assigned is further highlighted with a blue ring:

Selected points in the viewport state

A selected point with a Tweaks multiparm is highlighted with a green ring:

Selected point with a Tweaks multiparm

The image below shows unassigned world space shapes (Assign in World Space on the viewport state toolbar is turned on):

Unassigned world space shapes

Parameters

Add Shapes

Role

The function of the attached geometry within the rig setup.

Control

The attached geometry is used as control geometry. In viewport interactions with the skeleton, control geometry aids in selecting skeleton joints.

Capture Geo

The attached geometry is used to influence the result of the Joint Capture Biharmonic SOP. See modifying capture weights with geometry shapes for more information.

Rest Pose Attribute

When turned on, this is the name of the Matrix4 point attribute (by default, rest_transform) that contains the rest pose for the skeleton. When turned off, the input character’s pose (first frame) is used as the rest pose.

Note

We recommend that you use a rest pose attribute when attaching control shapes to a character’s skeleton. Attaching controls to an animated skeleton can cause problems (like performance issues) when assigning shapes in world space since the assignment relationships are not clear. Using the rest_transform attribute is a good way to ensure that the skeleton in Assign Shapes mode is not time dependent.

Advanced Shape Settings

Has Input World Space Shape Group

When turned on, the geometry in the Group parameter is used to group control shapes that have been modeled in world space.

Group

If the shape library contains control shapes modeled in both local and world space, add the world space primitives to a geometry group and specify the name of that group in this field. This parameter is available when Has Input World Space Shape Group is turned on.

Note

Using Group is not mandatory. This parameter is used to separate local and world space shapes in the viewport assignment modes.

Create Missing Shape Names by Connectivity

When turned on, unnamed control shapes in the shape library are assigned primitive names based on shape connectivity. This parameter is available when Role is set to Control.

Use Lighting

When turned on, renders the control shapes in the viewport using the scene’s current lighting setup. This parameter is available when Role is set to Control.

Output Joint Geo Group

The name of the primitive group to add the control shapes to. If the specified group already exists, the control shapes are appended to the existing group. By default, the primitive group is kinefx_controls.

Assign Shapes

A multiparm that creates links between the control shapes and their target skeleton points. This multiparm is available when the second input (Shape Library input) is connected.

Group

The names of the points to attach the control shapes to. This parameter accepts point names specified with the @name syntax, for example, “@name=hand_l @name=hand_r”. You can also click to select the skeleton points from the viewport, which automatically populates this parameter.

Shape Name

The name of the geometry primitive to use as the control shape for the points in Group. The names of the geometry primitives connected to the second input (Shape Library input) appear in the drop-down list.

Keep Shape World Transform

When turned on, the control shape specified in Shape Name retains its world space position and doesn’t inherit the local space positioning of the point it is assigned to. As a result, you can change the rest position of the input skeleton without affecting the control shape’s position.

Tweak

Use Joint Offset Attribute

When turned on, the local transform offsets for the control shapes per point are provided by the Offset Attribute on the first input (Skeleton input).

Offset Attribute

When Use Joint Offset Attribute is turned on, this is the name of the point matrix attribute on the first input (Skeleton input) that represents a local transform offset for the control shapes per point.

Use Joint Color Attribute

When turned on, the color value for the control shapes are provided by the Color Attribute on the first input (Skeleton input).

Color Attribute

When Use Joint Color Attribute is turned on, this is the name of the vector point attribute on the first input (Skeleton input) that represents a color value for the shapes.

Multiply Shape Scale

Uniformly multiplies the scale of all the assigned control shapes by this value.

Tweaks

A multiparm that lets you specify local transform offsets for the points, which are inherited by their assigned control shapes.

Mode

Specifies how the local transform offset behaves in relation to other offset values supplied by a shape template and/or offset attribute.

Override

The specified offset overrides the existing offset, replacing it.

Pre-Multiply

The specified local transform offset is applied additively to the existing offset.

Group

The names of the points the local offset is applied to. This parameter accepts point names specified with the @name syntax, for example, “@name=hand_l @name=hand_r”. You can also click to select the skeleton points from the viewport, which automatically populates this parameter.

Translate

The translation offset.

Rotate

The rotation offset.

Scale

The scale offset.

Pivot

Pivot Translate

The translation offset for the pivot.

Pivot Rotation

The rotation offset for the pivot.

Change Color

When turned on, overrides the color of the Group's control shapes with Color.

Color

When Change Color is turned on, this is the color override for the Group's control shapes. The color is applied as a primitive attribute to the control shapes.

Shape Template

These parameters determine the settings for the shape template file provided on the third input (Shape Template input). The shape template is an external file that contains the controls shapes you want to use with the input skeleton.

Target Joints

The target points to apply the shape template to. The default * value selects all the points in the input skeleton.

Template Joints

The template points (and therefore, their assigned control shapes) to transfer to your input skeleton (first input) or Target Joints. The default * value selects all the template points in the supplied shape template.

Match By

Specifies how you want to match the shape template to the input skeleton.

Attribute Value

Matches based on point attribute values on the skeleton and shape template.

Point Number

Matches based on point number values from the skeleton and shape template.

Mapping Attribute

Matches using a dictionary attribute based on the structure of the mapping attribute from the Map Points SOP and the mirror attribute from the Rig Mirror Pose SOP. This mode is useful in that it can be used to map the template to a skeleton with a different name, or mirror a supplied template.

Example:

{
    `reference`: "ptnum" or the name of the 
                 attribute to reference (for example, "name"),
    `value`: The value of the attribute specified in the 
             `reference` key or the point number of the
              mirrored point if `reference` is "ptnum",
    `flipaxes`: An integer value that stores how the points
                were mirrored (By Scale or By Rotation)
}

Attribute to Match

When Match By is set to Attribute Value, this is the name of the point attribute that is used for matching between the input skeleton and template. This attribute can either be a string or integer type. Multiple matches are allowed, for example, the template shape box can be applied to several input points if more than one point has the same matching point value.

Note

The default attribute to match is the point name. This is useful, as KineFX shape templates are usually based on skeletons with point names.

Keep Template Joint Offsets

When turned on, the local tweak offsets from the supplied shape template are applied to the input skeleton.

Keep Template World Transform

When turned on, the world positions of the template shapes are used. This parameter is available when Keep Template Joint Offsets is turned off.

Inputs

Skeleton

The SOP skeleton to attach shapes to.

Shape Library

The packed or unpacked geometry primitives (with name attributes) to use as control shapes with the input skeleton.

These primitives can be modeled in local space or world space. In local space, the primitives are modeled at the origin and the shapes are automatically positioned at the local space of their assigned points. This is a convenient way to model and manage simple control shapes like spheres and boxes. In world space, the primitives are modeled in context at their correct positions on the character. This is convenient when you have complex shapes that you want to match with the outline of a character model since you don’t need to model them with an offset.

Shape Template

Contains information about existing shape assignments and/or shape offsets that can be transferred to the input skeleton. Having a shape template is a great starting point that can save you a lot of time when setting up control shapes for your characters. You can apply additional shape assignments and tweak changes on top of the template in the same Attach Joint Geo SOP. The tweak data is stored in the jointgeo primitive attribute.

The template consists of points with packed primitives that have a point attribute for matching and optional metadata for offsets. These are stored on the packedgeo primitive attribute. The default matching attribute, Attribute to Match, is set to the joint name attribute.

If you have already created shape assignments and want to reuse them as a starting point for other rigs, you can save them as a shape template. Store a .bgeo file from the output of this Attach Joint Geo SOP with the complete skeleton, and use it as a template.

Outputs

Skeleton

The input skeleton with the control shapes attached.

Examples

capturegeoexample Example for Attach Joint Geometry geometry node

The example demonstrates using attached joint geometry to influence the capture result of biharmonic capturing. This method can be more efficient then purely painting weights and gives you more control over influence areas per joint in comparison to purely joint position based biharmic capturing.

  1. Created the capture geo shapes with common SOP nodes and use the Merge Packed SOP node to bundle and pack them

  2. Connect the output of the Merge Packed SOP node to the second input of the Attach Joint Geo node

  3. Enter the viewport state, click the joint in your skeleton that you want to assign the world space shape to as a control, press-hold G, and then -click the world space shape that you want to assign to the joint.

  4. Connect the output of the Attach Joint Geo SOP node to the second input of the Joint Capture Biharmonic node

  5. In the Parameter Editor, set the Role to the role set by the Attach Capture Geo SOP node. The capture geometry will be automatically used for the solve of the biharmonic capturing. You can bypass it via the Use Capture Geo Joints toggle

See also

Geometry nodes