# Instance

## Overview

The Instance node is a way of creating controlled duplicates of geometry, whether mesh or fibres, connected to Input 1 at every point or element in Input 0.

## Inputs

Input | Description
--- | ---
0 Data Flow | Fibres, Particles and Meshes
1 Data Flow | Fibres, Particles and Meshes

## Instance

Parameter | Description
--- | ---
Instance To | in most cases you want to have an instance per input point, but if you’re input is fibres you may want to limit the instance to one per fibre - Elements tells the node to instance on a per element ( fibre ) basis where as Points will instance to all the incoming points.
Alignment | Either a variable or static expression used to align the instance.
Alignment Variation | Means of introducing random variation into the resulting alignment.
Offset | Per instance offset, a possible value may be “$N * 0.1” to shift all of the instances 0.1 units away from the surface.
Scale | Per instance scale, this could be an expression, eg. “noise($id * 10)”
Scale Variation | Used to randomize the resulting scale.
Twist | Twists the new instance around the resulting axis.
Twist Variation | Varies each instances twist value.
Up Vector | either a variable or static expression used as an up vector in determining the instances orientation.
Axis Of Alignment | defines what axis in the input object will be aligned to the Alignment vector.

## Objects

Parameter | Description
--- | ---
Source Objects | in the case where Input1 has multiple input objects you may limit it to just the first, or all of them.
Object Expression | if Input1 contains multiple objects this is an expression used to determine which object to use for the current instance. For multiple objects a cycle expression can be used to cycle through the multiple inputs, eg. “cycle($id, 0, 5 )”
Inherit Attributes | defines a list of attributes, each separated by a space, that will be inherited from the geometry the instances are assigned too.
Deform | if toggled on instances will deform to the shape of the fibres being instanced too. This requires input fibres, and the mode set to Elements.
Generate As | As Input will reuse as much data to create a completely new geometric representation of the object ( original method ), As Instance will try and use the rendering engines instancing implementation.

## Selection

Parameter | Description
--- | ---
Point Selection | Allows the user to write a boolean based selection to define which points are instanced too in an element.
Element Point Index | Used to define which point in an element is used for an instance.

## Local Variables

Variable | Description
--- | ---
instanceNum | The instance index for the current fibre.
instanceCount | The number of instances for the current fibre.
vertexNum | The vertex index for the current instance in the fibre.
vertexCount | Number of vertices in the fibre.

## Example

Maya File: `examples/yeti_instanceExample.ma`

This is a basic example of how one might go about making Feathers with the Instance node.

As always we will start with a Sphere and a Plane, set the Planes X & Y subdivisions to 1 and scale it in Z.

The Sphere will be the surface we will be used to instance the Plane object too. Select the Sphere and press the CRM ( Create on Mesh ) icon in the Yeti shelf, this will create a new Yeti node and assign the Sphere as an input. In the Yeti nodes Graph palette add the Plane as an Input Object.

Open the Graph Editor and create an Import node selecting the Sphere as the input, and append a Scatter node to it with a Density Multiplier of 20. Now create a second Import node and selected the Plane.

Append an Instance node to the Scatter node ( as we’ll be instancing onto the newly created points ) and add the Plane’s Import node as the second input then turn on the Display toggle for the instance node.

As you can see, the plane has been instanced - but it looks wrong. If you recall the initial plane was created in the X/Z plane and scaled in Z - to correct the alignment of the Plane open the Attribute Inspector for the Instance node and set the Axis of Alignment to X.

The keen observer may also notice that the Plane is centred on the point, where we’d really want to pivot to be at the base of the plane - this is easy to correct by adding a Transform node between the Plane’s Import node and the Instance and Translating the Plane in X by 0.5 units.

Voila! That’s better. As far as instancing goes that’s a great start, but it doesn’t look very appealing. We’ll now use a Groom node to groom the instances to make them look more like feathers. First step is to select the Sphere and use the GRG ( Create Groom ) icon in the Yeti shelf to create a new Groom. All grooms are empty by default, so once created used the Add tool ( pressing the + button ) and Flood Fill strands on the surface ( with the bucket ). By default the Groom is set to Populate at Mesh Points which will create strands at vertex locations - this isn’t a requirement but is generally a good place to start.

Once created we’ll add it to the Yeti node in the Graph->Input Grooms palette.

With the Groom created and assigned we can Import it into our graph using the Import node, setting it to Groom and select our newly created Groom object. Once Imported we’ll want to use the Groom to set the direction of the instances, this can be done with the Comb node by specifying a Comb Attribute. If the attribute already exists in the Flow it will be set ( like N ) or you can specify a new attribute to be created. We’ll use feather_dir.

With the Comb node created and a new attribute being set we can replace the Scatter Node with the Comb Node as the first input to the Instance node. At this stage the Instance node still won’t change it’s output - we need to tell it what to do with the new attribute. By default the Instance node will have it’s Alignment set to the surface normal ( $N ) and the up vector set to Y ( [0 1 0] ). As we want our feathers to follow the direction of feather_dir we’ll replace the Alignment parameter with $feather_dir and make sure the Up Vector is now set to $N - this defines a nice coordinate system for the feathers. The Instance will change but may not look much different as we haven’t Groomed anything $feather_dir and $N are pointing in the same direction.

Now the fun part, close the Graph editor and start grooming!

Dynamics and other deformers/nodes can be used to tweak the look and the Attribute node ( Tutorial coming soon... ) can be used to paint Scale and other parameters for the instance.