instancer node

Go to: Related nodes. Attributes.

This class describes the instancer node. It takes a set of point data (including positions, rotations, scales, etc.) and instances hierarchies to that point data.

Node name	Parents	Classification	MFn type	Compatible function sets
instancer	transform	drawdb/geometry/transform	kInstancer	kBase kNamedObject kDependencyNode kDagNode kTransform kInstancer

Related nodes

particle

Attributes (11)

cycle, cycleStep, cycleStepUnit, fillArray, hierarchyCount, inputHierarchy, inputPoints, instanceCount, levelOfDetail, rotationAngleUnits, rotationOrder

Long name (short name) Type Default Flags

inputPoints (inp) genericArray NULL

Takes a single data object containing within it several arrays. Each array has a unique name and contains a separate element for each instance:

Name Type Default Description

position vector none The positions at which instances are to be placed. The number of elements in this array determines the number of instances which will be created.

id int32 instance's index in the arrays Unique identifier for the instance.

visibility boolean true Determines whether the corresponding instance is visible. Note that visibility settings higher up in the instance's hierarchy still apply in the usual way.

scale vector (1, 1, 1) XYZ scaling factors to be applied to the instance.

shear vector (0, 0, 0) Shear values to the applied to the instance.

rotationType int32 See description. Determines how the rotation of the instance should be determined:
0 = Use the corresponding rotation from the "rotation" array
1 = Aim the instance along the vector defined by the corresponding value from the "aimDirection" array.
2 = Aim the instance so that it points to the corresponding position from the "aimPosition" array.
For rotationTypes 1 and 2 additional orientation information can be supplied via the "aimAxis", "aimUpAxis" and "aimWorldUp" arrays.
If rotationType is not provided then the instancer node will look for the "rotation", "aimDirection" and "aimPosition" arrays in turn. The first one it finds will determine the rotationType. If none are present then a rotationType of 0 will be assumed.

rotation vector (0, 0, 0) The Euler rotation (XYZ) to be applied to the instance when the corresponding "rotationType" is 0. The rotation order is taken from the rotationOrder attribute.

aimDirection vector (1, 0, 0) The direction in which the instance should be aimed when its corresponding "rotationType" is 1.

aimPosition vector (0, 0, 0) The position at which the instance should be aimed when its corresponding "rotationType" is 2.

aimAxis vector (1, 0, 0) Determines the axis of the instance which is to be aligned with the aim direction when corresponding "rotationType" is 1 or 2.

aimUpAxis vector (0, 1, 0) The instance's up-vector. Used when the corresponding "rotationType" is 1 or 2.

aimWorldUp vector (0, 1, 0) The world up-vector to be used when the corresponding "rotationType" is 1 or 2.

objectIndex int32 0 When the 'cycle' attribute is set to 0, this determines which of the input hierarchies will be used for the corresponding instance.

cycleStartObject double 0.0 When the 'cycle' attribute is set to 1 (cycle each instance through several input hierarchies) this value determines which input hierarchy will be used to start the cycle for the corresponding instance.

age double current time in seconds When the 'cycle' attribute is set to 1 (cycle each instance through several input hierarchies) this value determines how far into the cycle the instance is and, in combination with the 'cycleStep' attribute, determines which of the input hierarchies should be used.

See MFnArrayAttrs in the API Reference for details on how to access this kind of attribute.

inputHierarchy (inh) matrix NULL

This is where all of the hierarchies that are to be instanced are connected with their local matrix attributes. We use the local matrix so that we can detect when the transformation of the hierachies change, because that would mean that we need to redraw the instances.

rotationOrder (ror) enum 0

When an instance's element in the "rotationType" array of the inputPoints attribute is set to 0 (rotation), this value is used to determine the order in which the X, Y and Z rotations are applied. For any other "rotationType" this value is ignored.

Valid values are:

"XYZ" (0)

"XZY" (1)

"YXZ" (2)

"YZX" (3)

"ZXY" (4)

"ZYX" (5)

rotationAngleUnits (rau) enum 0

Tells the instancer how to interpret the values in the "rotation" array of the inputPoints attribute when a point's "rotationType" array element is set to 0 (rotation). The valid options are "Degrees" (0) and "Radians" (1).

cycle (cyc) enum 0

Tells the instancer whether or not it should change the hierachy instanced to each point as time changes. If set to "None" (0) then there is no change and the hierarchy assigned to each instance remains the same throughout the animation. If set to "Sequential" (1) then each instance will start out with the hierarchy in the corresponding element of the "cycleStartObject" array of the inputPoints attribute, and will then advance sequentially through the other hierarchies based on its value of its element in the "age" array, in combination with the cycleStep attribute.

cycleStep (cs) double 1.0

Tells the instancer how often to change the hierarchy instanced to each point. The unit that this value is interpretted in is based on the value of the cycleStepUnit attribute.

cycleStepUnit (csu) enum 0

Tells the instancer how to interpret the value in the cycleStep attribute. Valid options are "Frames" (0) and "Seconds" (1).

levelOfDetail (lod) enum 0

Lets the user control the display of the instanced objects. Since there could be hundreds or thousands of points, the user may not want to draw them all interactively. If this attribute is set to "Geometry" (0), then the objects are drawn exactly as they would be in the current display mode. If the value is "BoundingBoxes" (1), then only the bounding box for each object is drawn. If the value is "BoundingBox" (2), then only the bounding box for the instancer is drawn.

instanceCount (ic) integer 0

This attribute will be set to the current number of instances being created. This number includes those whose "visibility" value is set to FALSE/0. It is the number of points coming into the instancer.

fillArray (fa) bool false

Used to trigger the action of getting all of the data from the inputPoint data. It is not used by the user at all.

hierarchyCount (hc) integer 0

A READ-ONLY attribute to allow the users to query the number of hierarchies being instanced by the node.