Specifying Scene References

 
 
 

Certain nodes can refer to elements in the scene using references. For example, references can specify things like:

References are resolved by name. Character strings are not case-sensitive. Object, property, and attribute names are separated by a period (.), for example, "grid.PointPosition" or "sphere.cls.WeightMapCls.Weight_Map.Weights".

TipIf you right-click over a Get Data node (not over a port), you can choose Select Object to select the referenced object or the object that owns the referenced attribute. This does not work with attributes of clusters, weight maps, or vertex clusters.

Specifying Scene References

You can specify a scene reference by using controls in a node's property editor, or by using Explore for Port Data on a node's context menu.

Specifying References in Property Editors

Nodes that use scene references have special controls in their property editors.

A

Type the reference. Use periods to separate objects, properties, and attributes. Strings are not case-sensitive. Use the token "self" to refer to the object on which the tree exists. You can also use the tokens "this" (same as "self") and "this_model" (the model that contains the object with the tree).

B

Click Explorer, expand the tree, and choose an element. The tree shows the attributes that you can get from the current element name path or location. This list includes predefined attributes and any custom attributes (including those defined in unconnected Set Data nodes).

C

Click Pick and then pick an element from a viewport, explorer, or schematic view.

D

You can combine methods A and B, for example, type "self", click Explorer, and then choose an attribute such as PointPosition.

Specifying References Using the Node Context Menu

Note that this procedure does not work for compounds, including Set Data.

  1. Right-click on a node with a scene reference (not over a port).

  2. Choose Explore for Port Data.

  3. Choose the reference from the explorer that pops up.

Daisy-chaining References

You can use the In Name and Out Name ports to connect references on Get Data and other nodes in sequence, like a daisy chain. For example, you can get "sphere" and then use that to get "sphere.PointPosition", "sphere.PointNormal", and so on. If you want to change "sphere" to "torus" later on, there's only one node that needs to be changed. This is particularly useful when creating compounds, because you only need to expose the leftmost reference.

References that are connected in this way are concatenated, so for example Get Data ("Self") plugged into Get Data ("PointPosition") results in "Self.PointPosition". You do not need to worry about periods at the beginning or end of the references — periods are automatically added or removed as necessary.

When a node has a reference connected to its In Name port, then the Explore button and Explore for Port Data command both start from the current path. For example, if you click Explore in the property editor of a leaf (left-most) Get Data, you can select anything starting from the scene root. However if a Get Data has a reference to a geometric object connected to its In Name, you can select properties and attributes on that object. Similarly if a node has a reference to a scene group connected, you can select any property or attribute that exists on all objects in that group (intersection).

If a Set Data compound has a string connected to its In Name port, the string is prepended to all attribute names that it sets. You can connect the object name, for example, "pointcloud", and then set any number of attributes such as PointPosition, PointVelocity, and so on. To add a new attribute when In Name is connected to a Set Data compound, you must first add a new port by right-clicking and choosing Insert Port Before or Insert Port After, then specify the attribute reference, and finally connect a value.

Tokens in References

The token "self" always refers to the object on which the ICE tree is directly applied. This token allows you to create trees that are easily reusable because they don't depend on specific object names.

The exact context of a reference using "self" depends on the attribute. For example, "Self.PointPosition" is per point, "Self.EdgeLength" is per edge, "Self.PolygonArea" is per polygon, and "Self.NbPoints" is per object.

Other tokens that you can use are "this" (same as "self") and "this_model" (refers to the model that contains the object with the ICE tree).

Replacing Object Names with "Self"

If you have built an ICE tree using specific object names and want to make it more generic so that you can make a compound to use on other objects, you can automatically replace the object name with "Self".

To replace the object name with "Self" in all nodes

  • Choose User Tools Replace Object Name with Self (Nested Compounds).

This affects all references to the name of the object on which the ICE tree is applied, including occurrences in nested compounds. It does not affect references to the names of other objects.

To replace the object name with "Self" in a specific node

  • Right-click on a Get Data or Set Data node and choose Replace Object Name with Self.

Replacing Model Names with "this_model"

Just as the keywords "self" and "this" refer to the object with the ICE tree, the keyword "this_model" refers to the model that contains the object with the ICE tree. By replacing references to a specific model name with "this_model", you can make a tree more generic and applicable to other objects.

To replace the model name with "this_model" in all nodes

  • Choose User Tools Replace Model Name with this_model (Nested Compounds).

Resolving Scene References

Scene references are automatically maintained as you modify the scene.

  • If you have an object called "sphere" and you rename it to "ball", references to "sphere" are automatically updated to "ball".

  • If you delete the object named "sphere" instead, any references to it are invalid and the affected nodes become red. If you later add another object named "sphere", or rename an existing object to "sphere", then the references become resolved again.

  • If you add the object named "sphere" to a model named "Fluffy", references to "sphere" are automatically updated to "Fluffy.sphere". If the ICE tree is on an object in the Fluffy model, the references are updated to "this_model.sphere" instead.