Constraint Network dynamics node

Constrains pairs of RBD objects together according to a polygon network.

On this page	Breaking Constraints Anchor Types Attributes Constraint Attributes Feedback Attributes Anchor Attributes Parameters Data Options Guide Options Relationship Inputs Outputs Locals Examples
Since	13.0

Note

This DOP is currently only supported by the Bullet Solver and the Wire Solver.

The constraint network defines pairs of RBD objects that should be constrained together.

With the constraint network, SOP Geometry is specified which defines what objects should be constrained. This makes it easy to procedurally generate a set of constraint relationships, including constraints of different types. Each point in the geometry represents a constraint anchor, according to the name and P attributes. Each two-point polygon represents a constraint, according to the constraint data specified by the constraint_name attribute.

Tip

Advanced users can use the constraint_name and constraint_type attributes to dynamically change constraint types with animation or a SOP Solver.

Breaking Constraints ¶

If a constraint is broken by a solver (such as when sufficient force is applied to break a glue bond), the primitive will be placed into a primitive group named broken. That primitive group can be used in a SOP Solver to trigger events such as emitting debris when a constraint breaks. Any constraints that are in the broken primitive group will be ignored by solvers on subsequent frames. Currently, only glue constraints will be broken by the Bullet Solver.

Constraints can also be broken by using a SOP Solver to delete primitives from the constraint network’s geometry. For linear constraints, the force and distance primitive attributes are updated by the solver to contain the force applied to satisfy the constraint and the distance between the anchors, respectively. For angular constraints, the torque and angle primitive attributes are updated by the solver to contain the torque applied to satisfy the constraint and the angle (in radians) between the anchors. For glue constraints, the impact primitive attribute is updated by the solver to contain the accumulated impulses for the glue bond. These attributes can be used to remove a constraint when certain conditions are met.

Anchor Types ¶

Each point in the constraint geometry represents an anchor. All constraints are made up of two anchors. Currently there are 4 different types of anchors, specified by the name, anchor_type and anchor_id point attributes.

A World Space Anchor is an anchor that is simply placed at a static world space position, specified by the P attribute on the anchor. If an anchor has an empty value for the name attribute, then the anchor is treated as a World Space Anchor. If the name attribute specifies an invalid name, the constraint is skipped.

A Relative Offset Anchor is an anchor that is placed at specific position relative to a simulated object. This position is fixed to the object’s initial rotation, so if the object is rotated during the simulation the anchor rotates with it. If the name attribute specifies a valid object, and the anchor_id attribute is set to -1 (or is not defined), then the anchor is treated as a Relative Offset Anchor, with the P attribute specifying the offset from the object’s centroid.

A Point Anchor is an anchor whose position is bound to that of a certain point on the geometry of a simulated object. When the name attribute is valid and the anchor_id attribute is a valid point index, then the anchor will be placed at the specified point. Alternatively, if the anchor_type attribute is set to vertex (the default is point) then the anchor will be placed at the point referred to by the vertex with the index in anchor_id.

Note

In cases where the geometry of a simulated object changes over the course of a simulation, anchoring to a point by specifying a point (or vertex) index in the anchor_id attribute may not yield correct results. This is because as the geometry changes, point and vertex indices may also change, meaning the Point Anchors could end up referring to different points than at the beginning of the simulation.

To fix this, add the integer point attribute anchor_pid or the integer vertex attribute anchor_vid to the simulated object whose geometry may change. If either of these attributes exist, then the anchor_id specified on the anchor will match to the first point (or vertex) with the same anchor_pid (or anchor_vid) value on the simulated geometry. This way as the geometry changes, the attributes will stay the same.

An Agent Anchor is an anchor that is attached to a transform in an agent’s rig. The transform does not need to be associated with a simulated object (i.e. the agent’s collision layer does not need to have a shape attached to the transform). When the anchor_type is agent and the name attribute references an agent’s transform (e.g. agent1/head), the local_P and local_orient attributes can be used to specify the local transform of the anchor.

Attributes ¶

Constraint Attributes ¶

You can create attributes on the geometry to customize each constraint’s behavior and type. If a primitive attribute with the same name as a constraint property (such as damping) is present, the attribute value will be multiplied with the value from the constraint sub-data if the data type is float. For other data types, a primitive attribute will override the value from the constraint sub-data.

The following attributes can be used to control the type of constraint described by each primitive.

Name	Class	Type	Description
`constraint_name`	Primitive	String	Specifies the Data Name of the constraint to create. If this attribute is not present or the name is invalid, no constraint will be created from the primitive. This attribute can be modified in a SOP Solver to change the constraint’s type during the simulation.
`constraint_type`	Primitive	String	Specifies whether the constraint affects `position`, `rotation` or `all` degrees of freedom. If this attribute is not present or has an invalid value, the default value will be `position`.
`next_constraint_name`	Primitive	String	Specifies a new value for the `constraint_name` attribute to switch to if the constraint is broken by the solver. This is simpler than using a SOP Solver and allows the transition to take place at the instant the constraint breaks. Currently, only glue constraints may be broken during the timestep by the Bullet Solver.
`next_constraint_type`	Primitive	String	Specifies a new value for the `constraint_type` attribute to switch to if the constraint is broken by the solver and the `next_constraint_name` attribute is valid.
`propagate_iteration`	Detail	Integer	Specifies the number of impact propagations for all glue bonds in the constraint network. Note In Houdini 17, the number of propagation iterations can instead be varied per glue constraint with the `propagationiterations` primitive attribute (corresponding to the Propagation Iterations parameter of the Glue Constraint Relationship), so this detail attribute is deprecated.

Feedback Attributes ¶

The following attributes are created by the solver to provide information about how the constraints behaved during the previous timestep. These attributes can be used to control when constraints are broken.

Name	Class	Type	Description
`angle`	Primitive	Float	The current angle (in radians) between the two anchors.
`distance`	Primitive	Float	The current distance between the two anchors.
`force`	Primitive	Float	This attribute stores the magnitude of the force that was applied to satisfy the constraint during the previous timestep.
`impact`	Primitive	Float	For glue constraints, this attribute is updated by the solver with the accumulated impulses for the glue bond, as impacts occur and propagate through the network.
`torque`	Primitive	Float	This attribute stores the magnitude of the torque that was applied to satisfy the constraint during the previous timestep.

Anchor Attributes ¶

The following attributes can be used to control how the anchor points are attached to objects.

Name Class Type Description

anchor_id

Point

Integer

If this attribute is defined and refers to a valid point (or vertex depending on the value of anchor_type), then this anchor’s position will be bound to the specified point (or vertex) on the simulated geometry specified by the name attribute.

If the value is set to -1, then the anchor is treated as a relative offset from the object specified by the name attribute (where the P attribute defines the offset). If the value does not refer to a valid point (or vertex), then the constraint is not created.

anchor_type

Point

Integer

Specifies if the anchor is attached to a point, vertex or agent transform. If no anchor_id attribute is defined and the anchor type is point or vertex, then this attribute has no effect. If this attribute is not defined, then anchor_id will refer to a point.

condir

Point

Vector

If the number of constrained degrees of freedom is 1, this value defines the normal of a plane that the object can move along or rotate about any axis in. If the number of constrained degrees of freedom is 2, this value defines an axis that the object can move or rotate about.

condof

Point

Integer

Identifies the number of constrained degrees of freedom for an anchor:

Constraint type	condof value	Behaviour
Position	`0`	Free motion
	`1`	Free to move on plane. `condir` defines the plane’s normal vector.
	`2`	Free to move along a line. `condir` defines the line’s direction.
	`3`	No translation.
Rotation	`0`	Free rotation
	`1`	Free to rotate around 2 axes. `condir` defines the inactive axis.
	`2`	Free to rotate around 1 axis. `condir` defines the active axis.
	`3`	No rotation.

local_orient

Point

Quaternion

If the anchor_type is agent, specifies the anchor’s orientation in the local space of the transform referenced by the name.

local_P

Point

Vector

If the anchor_type is agent, specifies the anchor’s position in the local space of the transform referenced by the name.

name

Point

String

Identifies the object to which the constraint is attached. An empty name indicates that the constraint is attached to a world space position.

Note

For the Bullet solver’s glue constraints, attaching to a world space position is not supported.

For RBD Packed Objects, the name point attribute from the DOP object’s geometry is used to identify which object to attach the constraint to. If Attach Internal Constraints to Object is not enabled, this name can be prefixed by the DOP Object name (e.g. object2/piece3) to uniquely identify the object. For agent primitives, a transform name can be appended to the anchor name (e.g. agent2/head) to attach the constraint to a specific transform in the agent’s rig. For all other types of objects, the DOP object name is used.

orient

Point

Quaternion

Identifies the initial world space orientation of the anchor. If the r point attribute also exists on the geometry, this attribute will take precedence.

P Point Vector Identifies the initial world space position of the anchor.

r

Point

Vector

Identifies the initial world space orientation of the anchor as Euler angles.

v Point Vector Identifies the velocity of the world space position to which the constraint is attached.

w

Point

Vector

Identifies the angular velocity of the world space position to which the constraint is attached.

Note

For RBD Packed Objects, the name point attribute from the DOP object’s geometry is used to identify which object to attach the constraint to. Since multiple RBD Packed Objects may contain packed primitives with the same names, the identifier can optionally be prefixed by the DOP Object name (e.g. object2/piece3) to avoid name conflicts and uniquely identify the object. For all other types of objects, the DOP object name is used as the identifier.

When switching a setup from using an RBD Packed Object to an RBD Fractured Object, ensure that the anchor names are not prefixed with the DOP Object name so that the constraint network is compatible with both object representations.

Parameters ¶

Data Options ¶

Geometry Source

Specifies the source of the constraint network geometry.

SOP

Use the SOP specified by the SOP Path parameter.

First Context Geometry

Use the SOP connected to the DOP network’s first input.

Second Context Geometry

Use the SOP connected to the DOP network’s second input.

Third Context Geometry

Use the SOP connected to the DOP network’s third input.

Fourth Context Geometry

Use the SOP connected to the DOP network’s fourth input.

SOP Path

The SOP geometry to use to determine the constraints.

Use Object Transform

Turn on this option to embed the transform from the parent object of the SOP along with the geometry.

Match by Attribute

Specifies an integer primitive attribute which can be used to match constraints from different time steps. This is used by the Bullet solver to interpolate the transforms of world space anchors.

Overwrite with SOP

This flag will re-import the network whenever it is set, allowing a completely animated constraint behavior.

Guide Options ¶

Show Guide Geometry

Turning on this option causes guide geometry to be displayed in the viewport representing this constraint.

Show Object Link

This parameter controls the display of guide geometry connecting the constraint to the constrained object.

Relationship ¶

Attach Internal Constraints to Object

The default behavior is to attach the constraint geometry to a relationship between the objects, which allows constraints to be anchored to multiple DOP objects. If constraints only need to be between packed primitives in a single DOP object, this option allows the constraint geometry to be attached to the DOP object’s ConstraintGeometry subdata instead of a relationship. In this mode, constraints can be modified during the timestep with a SOP solver that processes the object’s ConstraintGeometry subdata (for relationships, any attached solvers are run at the beginning of the timestep before solving any objects).

Constrained Objects

Specifies the affected DOP objects in the created relationship.

Relationship Name

A unique name that will identify the relationship.

Activation

Determines if this node should do anything on a given timestep and for a particular object. If this parameter is an expression, it is evaluated for each object (even if data sharing is turned on).

If it evaluates to a non-zero value, then the data is attached to that object. If it evaluates to zero, no data is attached, and data previously attached by this node is removed.

Inputs ¶

Objects To Be Processed

The objects to apply this relationship to, that will be eligible for being constrained by the object name attribute.

Constraints To Create

The constraints that can be created using the primitives in the SOP geometry.

Constraint Solvers

SOP solvers may be attached to update the constraint network dynamically in response to events. Only a single geometry is shared by all the objects, so this solver is executed once per relationship, not per object.

Outputs ¶

First Output

The operation of this output depends on what inputs are connected to this node. If an object stream is input to this node, the output is also an object stream containing the same objects as the input (but with the data from this node attached).

If no object stream is connected to this node, the output is a data output. This data output can be connected to an Apply Data DOP, or connected directly to a data input of another data node, to attach the data from this node to an object or another piece of data.

Locals ¶

The simulation time for which the node is being evaluated.

Depending on the settings of the DOP Network Offset Time and Scale Time parameters, this value may not be equal to the current Houdini time represented by the variable T.

ST is guaranteed to have a value of zero at the start of a simulation, so when testing for the first timestep of a simulation, it is best to use a test like $ST == 0, rather than $T == 0 or $FF == 1.

The simulation frame (or more accurately, the simulation time step number) for which the node is being evaluated.

Depending on the settings of the DOP Network parameters, this value may not be equal to the current Houdini frame number represented by the variable F. Instead, it is equal to the simulation time (ST) divided by the simulation timestep size (TIMESTEP).

TIMESTEP

The size of a simulation timestep. This value is useful for scaling values that are expressed in units per second, but are applied on each timestep.

SFPS

The inverse of the TIMESTEP value. It is the number of timesteps per second of simulation time.

SNOBJ

The number of objects in the simulation. For nodes that create objects such as the Empty Object DOP, SNOBJ increases for each object that is evaluated.

A good way to guarantee unique object names is to use an expression like object_$SNOBJ.

NOBJ

The number of objects that are evaluated by the current node during this timestep. This value is often different from SNOBJ, as many nodes do not process all the objects in a simulation.

NOBJ may return 0 if the node does not process each object sequentially (such as the Group DOP).

OBJ

The index of the specific object being processed by the node. This value always runs from zero to NOBJ-1 in a given timestep. It does not identify the current object within the simulation like OBJID or OBJNAME; it only identifies the object’s position in the current order of processing.

This value is useful for generating a random number for each object, or simply splitting the objects into two or more groups to be processed in different ways. This value is -1 if the node does not process objects sequentially (such as the Group DOP).

OBJID

The unique identifier for the object being processed. Every object is assigned an integer value that is unique among all objects in the simulation for all time. Even if an object is deleted, its identifier is never reused. This is very useful in situations where each object needs to be treated differently, for example, to produce a unique random number for each object.

This value is also the best way to look up information on an object using the dopfield expression function.

OBJID is -1 if the node does not process objects sequentially (such as the Group DOP).

ALLOBJIDS

This string contains a space-separated list of the unique object identifiers for every object being processed by the current node.

ALLOBJNAMES

This string contains a space-separated list of the names of every object being processed by the current node.

OBJCT

The simulation time (see variable ST) at which the current object was created.

To check if an object was created on the current timestep, the expression $ST == $OBJCT should always be used.

This value is zero if the node does not process objects sequentially (such as the Group DOP).

OBJCF

The simulation frame (see variable SF) at which the current object was created. It is equivalent to using the dopsttoframe expression on the OBJCT variable.

This value is zero if the node does not process objects sequentially (such as the Group DOP).

OBJNAME

A string value containing the name of the object being processed.

Object names are not guaranteed to be unique within a simulation. However, if you name your objects carefully so that they are unique, the object name can be a much easier way to identify an object than the unique object identifier, OBJID.

The object name can also be used to treat a number of similar objects (with the same name) as a virtual group. If there are 20 objects named “myobject”, specifying strcmp($OBJNAME, "myobject") == 0 in the activation field of a DOP will cause that DOP to operate on only those 20 objects.

This value is the empty string if the node does not process objects sequentially (such as the Group DOP).

DOPNET

A string value containing the full path of the current DOP network. This value is most useful in DOP subnet digital assets where you want to know the path to the DOP network that contains the node.

Note

Most dynamics nodes have local variables with the same names as the node’s parameters. For example, in a Position DOP, you could write the expression:

$tx + 0.1

…to make the object move 0.1 units along the X axis at each timestep.

Examples ¶

AnchorPins Example for Constraint Network dynamics node

This example demonstrates how different anchor positions can affect pin constraints.

AngularMotorDenting Example for Constraint Network dynamics node

This example demonstrates how angular motors can be used with pin constraints to create a denting effect.

BreakingSprings Example for Constraint Network dynamics node

This example shows how to use a SOP Solver to break spring constraints in a constraint network that have stretched too far.

Chains Example for Constraint Network dynamics node

This example shows how to create a chain of objects that are connected together by pin constraints.

ControlledGlueBreaking Example for Constraint Network dynamics node

This example shows how to gradually remove glue bonds from a constraint network and control the crumbling of a building.

GlueConstraintNetwork Example for Constraint Network dynamics node

This example shows how to create a constraint network to glue together adjacent pieces of a fractured object. It also shows how primitive attributes such as 'strength' can be used to modify properties of individual constraints in the network.

Hinges Example for Constraint Network dynamics node

This example demonstrates how to use pin constraints to create hinges between objects.

PointAnchors Example for Constraint Network dynamics node

This example shows how to create a basic constraint network with point anchors.

SoftConstraintNetwork Example for Constraint Network dynamics node

This example shows how to create a simple network of soft constraints, which are used to allow an object to bend before breaking.

SpringToGlue Example for Constraint Network dynamics node

This example shows how to create spring constraints between nearby objects, and then change those constraints to glue constraints during the simulation.