Search Tips

Search is based on keyword.

`Ex: "Procedures"`

Do not search with natural language

`Ex: "How do I write a new procedure?"`

Give Feedback Support Portal

# Q100518: Instancing Overview

Warning: This article contains links to external websites

SUMMARY

This article provides an overview of instancing in Katana. In any scene with repeating geometry, instancing can be used for the benefit of a reduced memory footprint and increased scene graph cook performance. Typically, instancing works well when the geometry is the same across many copies and the only required modifications are transformations.

For advanced topics on each instancing method such as instancing to a point cloud and varying materials or attributes per instance, see the resource links at the bottom of this article.

INSTANCING REVIEW

The following is a brief overview of three instancing techniques: Hierarchical instancing (Instance Sources), leaf-level instancing (Instance IDs), and instance arrays. For an in-depth discussion to instancing, the Renderman Documentation: RenderMan 22 Docs - Instancing in Katana article demonstrates how to set up all three instancing methods as an introduction to instancing.

Hierarchical Instancing

In hierarchical instancing, entire hierarchies of scene graph locations can be instanced. Instance locations are the scene graph locations that will contain the instance, and the instance is defined by the geometry under the source location in the scene graph. An instance source is declared by setting a scene graph location's type attribute to “instance source”. Instance locations themselves are declared by setting their type attribute to “instance”.

The instance source is declared by setting the type of the group location representing the top-level location of the hierarchy to be instanced to “instance source”.

The instance locations need to be type “instance”. A geometry.instanceSource attribute should be a st r ing pointing to the source location.

Leaf-level instancing

In leaf-level instancing, pre-existing repeating geometry can be instanced, meaning that geometry that already exists multiple times in the scene will only be loaded once and any additional occurrences of the geometry will reference the same set of geometry data in memory. Existing Katana projects with repeating geometry that would benefit from instancing can be easily modified by adding an instance.ID attribute to repeating geometry locations in the scene graph. A draw-back, however, is that only locations with no children can be instanced.

All locations should have a matching instance.ID attribute. One location is selected as an instance source by the renderer, then all other locations are treated as instances locations.

NOTE: Understanding how geometry is selected as the instance source is crucial to decide if all locations need to contain geometry or if only the highest location in the scene graph needs geometry.

Please refer to the renderer documentation to understand how the instance source is selected. For example, both RenderMan and Arnold will pick the first location they see with an instance.ID that hasn't been previously encountered as the instance source; RenderMan will go through the scene graph from the top so will pick the topmost location with a new instance.ID as the source; while Arnold has multi-threaded scene graph expansion so will look at the locations in an arbitrary order and will use whichever location with a new instance.ID as the source.

Instance Arrays

In instance arrays, instance locations are mapped to instance sources by a single location of the type “instance array”. Instance arrays are similar to hierarchical instancing, with the added benefit of supporting multiple instance sources. One drawback is that materials cannot be varied per instance.

The instance array location needs to contain the geometry.instanceSource and at least one transformation attribute. The geometry.instanceIndex is optional if instanceSource contains a single path only, in which case, that instance source is used for all instances in the instance array.

geometry.instanceSource | String or string array attribute containing scene graph location paths of one or more instance sources
geometry.instanceIndex | Array attribute with the same number of elements as instances required. The values stored in this array indicate the index of the desired instance source in the geometry.instanceSource array. In other words, instanceIndex constitutes a mapping from instance index to instance source index.
geometry.instanceMatrix geometry.instanceTranslate geometry.instanceRotateX geometry.instanceRotateY geometry.instanceRotateZ geometry.instanceScale | Each attribute is a flat array of per-instance transformations. The meaning of each attribute is the same as for conventional transformation attributes. Can be multi-sampled to support animation.

For more information on instance array attributes, please visit Katana Developer Documentation: Instancing.

Further Reading

The following resources go in-depth on more advanced topics on each instancing method, such as instancing to a pointcloud and varying materials or attributes per instance.

- Q100517: Leaf-level (Instance ID) Instancing
- Q100508: Hierarchical (Instance Source) Instancing
- Q100514: Instance Array Instancing
- Renderman Documentation: RenderMan 22 Docs: Instancing in Katana