Houdini 20.5 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 and creates the attributes necessary for the interactive tools in KineFX to recognize these primitives as selectors for the points they are attached to.

If you want to provide a library of control shapes to choose from, the second input (Shape Library input) on this node 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 out 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 Geometry SOP.

Note

Controls inherit the 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

You can use the following as alternatives to creating control geometry directly in your scene:

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

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

State

Attach Joint Geometry viewport state toolbar
Attach Joint Geometry viewport state toolbar, Assign Shapes mode

Create New Group

  • If no points are selected in the viewport, then this button creates a new empty Assign Shapes multiparm.

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

Mode

Assign Shapes

In this mode, 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 automatically added to its Group parameter field. You can then assign any of the control shapes in the shape library (on Input 2) as the Shape Name for the multiparm with .

Tweak Shapes

In this mode, when you select a point or ⇧ Shift click multiple points in the viewport and then 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 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.

Offset Mode

Determines how the specified local transform offset will behave in relation to the other offset values supplied by a shape template and/or an offset attribute.

Pre-Multiply

The specified local transform offset will be pre-multiplied with the existing offset and thus will be applied additively to the existing offset.

Override

The specified offset will override the existing offset and completely replace it.

Attach Joint Geometry handle 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 or group of points.

  • When in Tweak Shapes mode, creates a new Tweaks multiparm for the selected point or group of points.

⌃ Ctrl + G

  • When in Assign Shapes mode, removes the selected the point or group of points from their current Assign Shapes multiparm.

  • When in Tweak Shapes mode, removes the selected point or group of points from their current Tweaks multiparm.

When in Assign Shapes mode, lets you scroll through the list of available library shapes and then choose one to add to the current Assign Shapes multiparm.
Attach Joint Geometry handle viewport state right-click menu
Attach Joint Geometry viewport state right-click menu

Create new Group

Creates a new Assign Shapes multiparm for the selected point or group of points.

Remove Joints from Groups

Removes the selected point or points from their current Assign Shapes multiparm Group assignment.

Attach Joint Geometry handle viewport state visualizations
A selected unassigned point and a selected assigned point (blue ring) in the viewport state
A selected point that has a Tweaks multiparm (green ring) in the viewport state
Unassigned world space shapes in the viewport state (Assign in World Space = on)

Parameters

Add Shapes

Role

Defines the function within the rig setup of the attached geometry.

Control

The attached geometry is used as control geometry that eases the joint selection for viewport interactions with the skeleton.

Capture Geo

The attached geometry is used to manipulate the result of the Joint Capture Biharmonic SOP. The points of the geometry attached to a specific joint strengthen the influence of the given joint in that region of the geometry to be captured.

Rest Pose Attribute

When on, specifies the name of the matrix4 point attribute (by default, rest_transform) that contains the rest pose for the skeleton. When off, the input character’s pose (first frame) is used as the rest pose for the skeleton. Use Rest Pose Attribute is on by default.

Note

We highly recommend that you use a rest pose attribute when attaching control shapes to your character’s skeleton.

Attaching controls to an animated skeleton can cause problems (like affecting performance) 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 your skeleton in Assign Shapes mode is not time dependent.

Advanced Shape Settings

Has Input Worldspace Shape Group

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

Group

If your shape library contains a mixture of control shapes modeled in local space and control shapes modeled in world space, then add the primitives built in world space to a geometry group and specify the name of that group in this Group field. By default, the name of the world space shapes group is world_shapes.

Note

Using Group is not mandatory. The node works internally completely fine without it. This parameter is used to separate between local and world space shapes in the viewport assignment modes.

Create Missing Shape Names by Connectivity

When on, if all or just a selection of the control shapes in your shape library are missing names, then the unnamed control shapes are automatically assigned proper primitive names based on shape connectivity.

Use Lighting

When on, the control shapes are rendered in the viewport using your scene’s current lighting set-up.

Output Joint Geo Group

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

Assign Shapes

Create or remove multiparms that create the links between the control shapes and their target skeleton points.

Group

Specifies the names of the points to attach the control shapes to. This parameter accepts point names specified with the @name syntax. For example, @name=head for one point, @name=hand_l @name=hand_r for two points, and so on. The select geometry arrow icon located next to this parameter also allows you to select the skeleton points for the Group from the viewport.

Shape Name

The name of the geometry primitive to use as the control shape for the points listed in the Group. All the names of the geometry primitives connected to this node’s second input (shape library input) also appear in this parameter’s drop-down list.

Keep Shape World Transform

When on, the control shape specified by Shape Name retains its world space position and does not inherit the local space positioning of the point it is assigned to. As a result, this also means that you can change the rest position of your input skeleton without affecting the control shape’s position.

Tweak

Use Joint Offset Attribute

When on, the local transform offsets for the control shapes per point are provided by the point matrix attribute on this node’s first input (skeleton input).

Offset Attribute

Specifies the name of the point matrix attribute on this node’s first input (skeleton input) that represents a local transform offset for the control shapes per point.

This parameter is only available when Use Joint Offset Attribute is turned on.

Use Joint Color Attribute

When on, the color value for the control shapes are provided by the vector point attribute on this node’s first input (skeleton input).

Color Attribute

Specifies the name of the vector point attribute on this node’s first input skeleton input that represents a color value for the shapes.

This parameter is only available when Use Joint Color Attribute is turned on.

Multiply Shape Scale

Multiplies the scale of all assigned control shapes uniformly by the specified factor.

Tweaks

Tweaks are multiparms that let you specify local transform offsets for the specified points, which their assigned control shapes then inherit.

Mode

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

Pre-Multiply

The specified local transform offset will be pre-multiplied with the existing offset and thus will be applied additively to the existing offset.

Override

The specified offset will override the existing offset and completely replace it.

Group

Specifies the names of the points the given local offset will be applied. This parameter accepts point names specified with the @name syntax. For example, @name=head for one point, @name=hand_l @name=hand_r for two points, and so on. The select geometry arrow icon located next to this parameter also allows you to select the skeleton points for the Group from the viewport.

Translate

Specifies the translation offset.

Rotate

Specifies the rotation offset.

Scale

Specifies the scale offset.

Pivot

Pivot Translate

Specifies the translation offset for the pivot.

Pivot Rotation

Specifies the rotation offset for the pivot.

Change Color

When on, overrides the current color of the specified point or points' control shapes with the new specified Color.

Color

Defines the vector color override for the specified Group's control shapes. The color is applied as a primitive attribute to the control shapes.

Shape Template

Determines the settings for the shape template file supplied on the third input (shape template input) on this node. The shape template is an external file that contains the controls shapes you want to use with your input skeleton. These parameters are only available when there is a third input detected.

Target Joints

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

Template Joints

Specifies the template points (and therefore their assigned control shapes) that you want to transfer to your input skeleton (input 1) or specified Target Joints. The default * value selects all the template points in the supplied shape template.

Match By

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

Attribute Value

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

Point Number

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

Mapping Attribute

Matches using a dictionary attribute that is based on the structure of the mapping attribute from the Map Points SOP and the mirror attribute from the Rig Mirror Pose SOP.

For 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__)
}

This Match By mode is incredibly useful since you can use it to map your template to a differently named skeleton or to mirror a supplied template.

Attribute to Match

Specifies the name of the point attribute that will be used for matching between the input skeleton and the template. The attribute can either be type string or integer, and multiple matches are also allowed. For example, the template shape box could be applied to several input points if more than one point has the same matching point value.

This parameter is only available when Match By is set to Attribute Value

Note

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

Keep Template Joint Offsets

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

Keep Template World Transform

When on, the world positions of the template shapes are used.

Inputs

Skeleton

The SOP skeleton to attach shapes to.

Shape Library

Packed or unpacked geometry primitives with name attributes to use as control shapes with the input skeleton. The primitives can be modeled in local space or world space.

Local space means that the primitives were all modeled at the origin and the shapes are then automatically positioned at the local space of their assigned points. This is a very convenient way to model and manage simple control shapes like spheres, boxes, and so on.

World space means that the primitives were all modeled in context at their correct positions on the character. This is very convenient when you have complex shapes that should match the outline of a character model since you do not 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. A shape template is a great starting point that can save you a lot of time when settings up the control shapes for your characters. And you can always apply additional shape assignments and tweak changes on top of the template in the same Attach Joint Geo SOP node. 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 optionally have metadata for offsets stored on the packedgeo primitive attribute. The default matching attribute (Attribute to Match) in the very convenient joint name attribute.

If you have already created a series of shape assignments and you want to reuse them as the starting point for other rigs, then you can save them as a shape template. This means that you can store a .bgeo file from the output of this Attach Joint Geo SOP node 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