On this page | |
Since | 17.0 |
Overview ¶
This node is similar to the Attribute Wrangle SOP.
-
For each prim selected in the Primitives parameter, the node runs the VEX snippet.
-
You can read current attribute values using
@name
, and create/update attribute values by writing to an@
variable with the same name as the attribute. -
You can also use VEX USD functions to manipulate the primitive.
-
The Bindings tab lets you explicitly map VEX variable names to USD attributes.
-
This is useful when USD attributes have names that are not valid VEX variable names.
-
For attributes that don’t exist yet, you can specify an explicit USD type.
-
Syntax ¶
The VEX snippet parameter lets you enter a snippet of VEX code to run on the input geometry. See VEX snippets for basic information on the syntax available in the snippet parameter. See the VEX chapter for general information on the VEX language.
Built-in variables ¶
-
@primpath
is the scene graph path of the current prim. -
Normally,
elemnum
is the index of the current prim in the list of selected prims, andnumelem
is the total number of selected prims. However, the meanings of these variables are different when Run on elements of array attributes is on. -
The following “convenience” built-ins are available as well:
Name
Equivalent to
Content
primname
usd_name( 0, @primpath )
Current prim’s name
primtype
usd_typename(0, @primpath)
Current prim’s schema name
primkind
usd_kind(0, @primpath)
Current prim’s kind
primpurpose
usd_purpose(0, @primpath)
Current prim’s purpose
primdrawmode
usd_drawmode(0, @primpath)
Current prim’s draw mode
primactive
usd_isactive(0, @primpath)
1
if current prim is activeprimvisible
usd_isvisible(0, @primpath)
1
if primitive is visible -
The prim’s current variant doesn’t have a built-in, but you can get it using a function call:
usd_variantselection(0, @primpath, "variant_set_name")
Tips ¶
-
This node can run the snippet over each prim, or over each element in each array attribute on each prim. See the Run On Elements of Array Attributes parameter.
-
In VEX snippets, you can use
@
variable names containing colons (:
). This makes it easier to automatically bind certain USD attribute names (for examplei@primvars:foo
). (These names are not normally legal in names in VEX source code. The node automatically encodes these kinds of names when used in a snippet.)
Parameters ¶
Primitives
The primitive(s) the node should operate on. You can drag primitives from the scene graph tree pane into this textbox to add their paths, or click the Reselect button beside the text box to select the primitives in the viewer, or ⌃ Ctrl-click the Reselect button to choose prims from a pop-up tree window. You can also use primitive patterns for advanced matching, including matching all prims in a collection (using
/path/to/prim.collection:name
).
Allow Instance Proxy Primitives
When this is on, the pattern in the Primitives parameter will be allowed to match instance proxy primitives (instanced ancestors of a primitive marked as instanceable). Since instance proxy primitives cannot be directly modified in USD, this mode is primarily used to allow the VEX code to pull data from the instance proxy primitives, and apply values to some non-instanced ancestor primitive.
Run On Elements of Array Attributes
When this is on, the node evaluates the snippet for each array element of array attributes, on each prim. In this mode, the built-in elemnum
refers to the array index, and numelem
refers to the length of the largest array. (When this is off, array attributes are available in the snippet as array-type variables.)
If some array attributes have shorter length, their elements are padded with the last element.
This mode may be useful for running over geometry-related attributes such as points
.
Code ¶
Vexpression
In the snippet, the path to the current prim is available as @primpath
. You can read current attribute values using @name
, and create/update attribute values by writing to variables with the same name as the attribute. You can also use VEX USD functions to manipulate the primitive. See VEX snippets for more information.
Attributes to Create
When the snippet creates a new variable, only create a corresponding attribute if the variable name matches this pattern. The default is *
, which creates an attribute from any VEX variable created in the snippet.
Enforce Prototypes
Automatic creation of attributes from @
variables is convenience, but there’s a risk a type will bind or create the wrong attribute. When this is on, binding only works if you explicitly declare the @
variable before use.
Bindings ¶
Autobind by Name
Automatically create @
variables corresponding to existing attributes (default is on). If this is off, only attributes explicitly bound using the multi-parm below are available as @
variables in the snippet.
Number of Bindings
The number of USD attributes to bind to VEX variables.
Attribute Name
The name of the USD attribute to bind to a VEX variable. Note that this attribute does not need to exist yet. You can bind it to a VEX variable, and if the VEX writes to the variable, the node will create the attribute.
Attribute Type
The USD datatype of the attribute. You should usually leave this set to Auto
, so the node will use the known type of an existing attribute. If you are going to create the attribute, and node doesn’t translate the VEX type into the correct USD type (for example, it becomes string
but you want a token
), you can change this to the type you want.
VEX Parameter
The name of the VEX parameter bound to the attribute.
Evaluation Node Path
Certain VEX functions, like ch()
, evaluate parameters on this node.
In some cases you want these functions to be relative to a different node (for example, with nodes inside a digital asset, you often want to evaluate functions relative to the parent asset). This is a relative node path to the node to use as “the current node” in the program.
Export Parameters
When a VEX parameter is exported, the bound attribute will be created if it doesn’t exist. This pattern can be used to override this option to avoid writing to or creating certain attributes. The pattern matches the VEX parameter, not the bound attribute. The attribute will still be bound for reading.