guide::FindOrAddGuide

Finds or adds guide geometry.

On this page	Inputs Outputs
Since	20.5

Finds or adds a joint on a guide skeleton, and updates the properties dictionary of the found/added joint. If the joint already exists in the graph as a TransformObject node, only its properties dictionary is updated.

The properties dictionary on a joint stores information that is used later to configure the controls that are created on the joint, including its scale inheritance, rotation order, transformation order, control shape, control shape color, and the transform components to promote.

The shape that is set on this node is the shape of the control in the animate state. If shape data already exists on a joint, override the existing shape by setting overridecontrol and setshapedata to True.

We refer to the joints on the guide skeleton as guide joints.

The geo ports of this node are in-place ports, which means that the geometry is updated without creating a copy.

Inputs ¶


                *geo:
                    Geometry

Required

The guide skeleton.


                name:
                    String

The name of the guide joint to find or add.


                xform:
                    Matrix4

The transform to use when creating a new guide joint. This is only applicable for new joints.


                scaleinheritance:
                    Int

Sets the scaleinheritance property on the guide joint.


                rord:
                    Int

Sets the rord (rotation order) property on the guide joint.


                xord:
                    Int

Sets the xord (transformation order) property on the guide joint.


                parent:
                    String

Sets the parent of the guide joint.


                promote:
                    String

Sets the promote property on the guide joint. To promote all the transform components, set this to “t r s”. To promote individual components, set this to “t”, “r”, or “s” (for translate, rotate, or scale).


                shape:
                    String

Sets the shape property on the guide joint.


                shapetranslate:
                    Vector3

Sets the shapetranslate property on the guide joint.


                shaperotate:
                    Vector3

Sets the shaperotate property on the guide joint.


                shapescale:
                    Vector3

Sets the shapescale property on the guide joint.


                shapecolor:
                    Vector3

Sets the shapecolor property on the guide joint. This overrides the Cd value on the guide joint.


                overridecontrol:
                    Bool

If set to True, overrides the control on the guide joint if it already has an associated TransformObject node - the existing TransformObject node is updated with the data defined in this node. To apply the shape data (defined in this node) to the control, setshapedata must also be set to True.


                setshapedata:
                    Bool

If set to True, this sets the shape data (shape*) in the properties dictionary on the guide joint. However, this does not change the shape data on the TransformObject node. To do this, also set overridecontrol to True.

Note

overridecontrol and setshapedata work together to set and apply the shape data. setshapedata sets the shape data (defined in this node) in the properties dictionary of the guide joint. overridecontrol tells guide::ControlsFromGuides to apply this new shape data to the TransformObject control that is associated with the guide joint.

setshapedata	overridecontrol	Result
True	True	The new shape data defined in this node is set in the guide joint’s `properties` dictionary, and the new data is applied to the control.
True	False	The new shape data is set in the guide joint’s `properties` dictionary, but is not applied to the control.
False	True	The new shape data is not set in the guide joint’s `properties` dictionary, so the control applies the previous shape data.
False	False	The new shape data is not set in the guide joint’s `properties` dictionary, and the shape data is also not applied to the control (the control uses the previous shape data).

Outputs ¶


                *geo:
                    Geometry

The updated guide skeleton/geometry.


                xform:
                    Matrix4

The transform data from the found/created guide joint.


                ptnum:
                    Int

The point number of the found/created guide joint.


                name:
                    String

The name of the found/created guide joint.

Inputs ¶

Outputs ¶

APEX nodes