Instancer

Copies from an input scene onto the vertices of a target object, making one copy per vertex. Additional vertex primitive variables on the target object can be used to choose between multiple prototypes, to specify their orientation, scale and attributes, and to modify the context in which the prototypes are evaluated.

Note

The target object will be removed from the scene.

Tip

Primitive variables with Varying interpolation are supported wherever a variable with Vertex interpolation is expected, provided that the primitive variable has the same size as the equivalent Vertex variable.

user

Container for user-defined plugs. Nodes should never make their own plugs here, so users are free to do as they wish.

out

The processed output scene.

enabled

The on/off state of the node. When it is off, the node outputs the input scene unchanged.

in

The input scene

filter

The filter used to control which parts of the scene are processed. A Filter node should be connected here.

parent

The object on which to make the instances. The position, orientation and scale of the instances are taken from per-vertex primitive variables on this object. This is ignored when a filter is connected, in which case the filter specifies multiple objects to make the instances from.

name

The name of the location the instances will be generated below. This will be parented directly under the parent location.

prototypes

The scene containing the prototypes to be applied to each vertex. Use the prototypeMode and associated plugs to control the mapping between prototypes and instances.

Note that the prototypes are not limited to being a single object - they can have arbitrary child hierarchies.

prototypeMode

The method used to define how the prototypes map onto each instance.

• In “Indexed (Roots List)” mode, the prototypeIndex primitive variable must be an integer per-vertex. Optionally, a path in the prototypes scene corresponding to each index can be specified via the prototypeRootsList plug. If no roots are specified, an index of 0 applies the first location from the prototypes scene, an index of 1 applies the second, and so on.

• In “Indexed (Roots Variable)” mode, the prototypeIndex primitive variable must be an integer per-vertex, and the prototypeRoots primitive variable must be a separate constant string array specifying a path in the prototypes scene corresponding to each index.

• In “Root per Vertex” mode, the prototypeRoots primitive variable must be a string per-vertex which will be used to specify a path in the prototypes scene for each instance.

  Note

  it is advisable to provide an indexed string array in order to limit the number of unique prototypes.

prototypeIndex

The name of a per-vertex integer primitive variable used to determine which prototype is applied to the vertex. This plug is used in “Indexed (Roots List)” mode as well as “Indexed (Roots Variable)” mode.

prototypeRoots

If prototypeMode is set to “Indexed (Roots Variable)”, then this should specify the name of a constant string array primitive variable used to map between prototypeIndex and paths in the prototypes scene.

If prototypeMode is set to “Root per Vertex”, then this should specify the name of a per-vertex string primitive variable used to specify a path in the prototypes scene for each instance.

This plug is not used in “Indexed (Roots List)” mode.

prototypeRootsList

An explicit list of paths used to map between prototypeIndex and paths in the prototypes scene. This plug is only used in “Indexed (Roots List)” mode.

id

The name of a per-vertex integer primitive variable used to give each instance a unique identity. This is useful when points are added and removed over time, as is often the case in a particle simulation. The id is used to name the instance in the output scene.

omitDuplicateIds

When off, having the same ids on multiple points is considered an error. Setting on will allow a render to proceed, with all instances that share an id being omitted.

position

The name of the per-vertex primitive variable used to specify the position of each instance.

orientation

The name of the per-vertex primitive variable used to specify the orientation of each instance. This must be provided as a quaternion : use an upstream Orientation node to convert from other representations before instancing.

scale

The name of the per-vertex primitive variable used to specify the scale of each instance. Scale can be provided as a float for uniform scaling, or as a vector to define different scaling in each axis.

attributes

The names of per-vertex primitive variables to be turned into per-instance attributes. Names should be separated by spaces and can use Gaffer’s standard wildcards.

attributePrefix

A prefix added to all per-instance attributes specified via the “attributes” plug.

encapsulateInstanceGroups

Converts each group of instances into a capsule, which won’t be expanded until you Unencapsulate or render. When keeping these locations encapsulated, downstream nodes can’t see the instance locations, which prevents editing but improves performance. This option should be preferred to a downstream Encapsulate node because it has the following benefits :

• Substantially improved performance when the prototypes define sets.

• Fewer unnecessary updates during interactive rendering.

seedEnabled

Creates a seed context variable based on a hash of the instance ID, which could come from the primitive varable specified in the id plug or otherwise the point index. This integer is available to the upstream prototypes network, and might typically be used with a Random node to randomise properties of the prototype.

seedVariable

Name of the context variable to put the seed value in.

seeds

The number of possible seed values. Increasing this allows for more different variations to be driven by the seed, increasing the total number of variations required.

seedPermutation

Changing the seedPermutation changes the mapping of ids to seeds. This results in a different grouping of which instances end up with the same seed.

rawSeed

Enable this in rare cases when it is required to pass through every single id directly into the seed context variable. This is very expensive, because every single instance will need a separate context, but is sometimes useful, and may be an acceptable cost if there isn’t a huge number of total instances.

contextVariables

Specifies context variables to be created from primitive variables. These variables are available to upstream prototypes network, allowing the prototypes scene to be generated differently depending on the source point. Supports quantization to avoid re-evaluating the prototypes scene too many times.

timeOffset

Modify the current time when evaluating the prototypes network, by adding a primvar.

variations

This special output plug returns an CompoundData dictionary with counts about how many variations are being created. For each context variable variable being set ( including “frame” when using Time Offset ), there is an entry with the name of the context variable, with an IntData containing the number of unique values of that context variable. There is also an entry for “”, with an IntData for the total number of unique contexts, considering all the context variables being created.

Extracting the dictionary values and displaying them to users is handled by _VariationsPlugValueWidget.

This information is important to display to users because varying the context requires extra evaluations of the prototypes scene, and can dramatically increase the cost of the Instancer.

Note that variations are measured across all locations in the scene where the instancer is filtered.