Instancing

There are three methods of instancing in Katana, described in more detail below.

  1. instance.ID attributes
  2. instance source and instance locations.
  3. instance source and instance array locations.

Using Instance IDs

When several copies of the same geometry are already present in the Katana project, they can be annotated with the instance.ID attribute. When cooking the scene, the renderer typically takes the first location with a previously unseen instance.ID value as the instance source for further locations with the same ID.

Attribute Description
string instance.ID A user-chosen string that uniquely identifies the geometry. Other locations with the same ID are considered instances of each other by the renderer.

Using Instance Sources

Instances can also be created when geometry is imported into Katana.

To define the source, import the geometry into an empty group and set the group’s type attribute to instance source. Instance sources are not rendered.

To define an instance, create an empty location and set its geometry.instanceSource attribute to the path of the scene graph location of the instance source. For clarity, the location’s type can be changed to instance. Instances can be shaded and transformed as usual.

Attribute Description
string geometry.instanceSource Path of scene graph location of the instance source.

Using Instance Arrays

Instance arrays are useful when instances are positioned programmatically and do not need to be interactively transformed.

Instance sources are defined as above.

An instance array is a scene graph location declaring multiple instances of one or more instance sources. Its type must be instance array.

Attribute Description
string[n] geometry.instanceSource Array of paths of scene graph locations of instance sources.
int[n] geometry.instanceIndex

Per-instance index into the instanceSource array, to determine which source location to use for each instance.

In other words, instanceIndex constitutes a mapping from instance index to instance source index.

Optional if instanceSource contains a single path only, in which case that instance source is used for all instances in the instance array.
int[] geometry.instanceSkipIndex Optional. Sparse array of indices of instances to skip.
double[16n] geometry.instanceMatrix double[3n] geometry.instanceTranslate double[4n] geometry.instanceRotateX double[4n] geometry.instanceRotateY double[4n] geometry.instanceRotateZ double[3n] 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.
group geometry.arbitrary Optional - see Arbitrary Attributes. The value or index attributes must contain data for every instance.