dagNode node

DAG object node. Base class for all objects in the 3D transformation hierarchy or DAG.

Transformation Hierarchy (DAG)

The transformation hierarchy or DAG (Directed Acyclic Graph) is a hierarchy where objects are defined relative to the transformations on their parent objects. These objects are dependency nodes and are referred to as dag nodes. There are basically two types of dag nodes: transforms and shapes. Transform nodes are grouping nodes which can have any number of other dag nodes below it. Transform nodes have affine transformation information which is applied to nodes below them. Shape nodes are leaf level nodes and cannot have any other nodes below them. Shape nodes must have at least one transform node as a parent. Dag nodes can have more than one parent. That is, they can be in more than one hierarchy. This makes the transformation hierarchy a graph instead of a tree. Dag nodes that are in more than one hierarchy are said to be "instanced".

Names

Dag nodes have names. There can be more than one dag node in the dag with the same name. However, a transform grouping node cannot have two child nodes with the same name.

Paths

Since there may be multiple ways to reach an instanced dag node when traversing down from the root of the hierarchy, all dag nodes are identified by a "path" which uniquely identifies a particular instance of an object. Paths define the traversal path from the root of the hierarchy down to the node. A dag node may have multiple paths to it. Paths have an associated number which corresponds to their position in the list of paths to the node at the end of the path. DAG Traversal is depth first so the first time a node is visited, the path traversed is path 0. The second time the dag node is visited, this different path traversed is path 1, and so on. Each path to a dag node also defines how the node is to be transformed. Instanced dag nodes will appear multiple times in the scene (once for each unique path from the root of the hierarchy to the object).

Transformations

All transformations in the DAG are affine transformations. All dag node transformations can be represented by a 4x4 transformation matrix where the fourth column contains the vector (0,0,0,1), the fourth row contains the vector (tx, ty, tz, 1) and represents a translational component. This implies objects are transformed by post multiplying their position by the transformation matrix.

Transformation Spaces

When dealing with dag nodes there is the concept of "transformation space". Common transformation spaces include "world-space", "object-space" and "parent-space". "world-space" is the space in which the objects appear in the scene, after all the hierarchical transformations have been applied. "object-space" is defined as the space in which the geometry of the object is defined before any transformations have been applied. Finally, "parent-space" is the transformation space that includes the matrices of the parents above the object but not the object's transformation matrix.

These transformation spaces are essential when dealing with attributes from different nodes to ensure consistent behaviour. For example, to compare the positions of vertices on two different objects in the scene, the vertices must first be transformed to a common transformation space. One way this can be accomplished is to transform the vertices using the worldMatrix attribute before doing the comparison.

Note: certain attributes like the transformation channels defined in a transform node do not correspond to any of the transformation spaces described above because they are used to construct the transformation matrix. Therefore, the order in which they are applied within the transformation matrix defines a unique transformation space for each of these attributes.

Instanced Attributes

Additionally, dag nodes can contain a special type of attribute called an "instanced attribute". Instanced attributes are array attributes where the array attribute at index 'i' corresponds to instance number 'i' for this object in the transformation hierarchy. Instances are mapped to array indices according to their relative ordering when traversing the DAG depth first. (in ascending child order) When specifying instanced attributes it is not necessary to give the array index because the system will infer this information from the path. Therefore, the attribute "ball.worldMatrix" corresponds to the array attribute "ball.worldMatrix[0]". From this definition it follows that all instanced attributes must contain at least one array item.

Matrix Attributes and MEL

Some attributes represent transformation matrixes. Although these attributes are represented internally as 4x4 matrices, unfortunately, matrix attributes are not returned as MEL 4x4 matrix types. Instead, they are returned as an array of floats where the elements of the matrix are listed in row major order. For instance, "matrix $m[4][4] = `getAttr ball.worldMatrix`;" will not work. To obtain the value of a matrix attribute, you need something like "float $m[16] = `getAttr ball.worldMatrix`;".

This node is abstract

Node name	Parents	MFn type	Compatible function sets
dagNode	entity	kDagNode	kBase kNamedObject kDependencyNode kDagNode

Attributes (87)

The following quick index only shows top-level attributes (too many attributes to show them all): boundingBox (12), center (3), drawOverride (15), ghostColorPost (3), ghostColorPre (3), ghostCustomSteps (3), ghostDriver, ghostFrames, ghostOpacityRange (2), ghostUseDriver, ghosting, ghostingMode, instObjGroups (4), intermediateObject, inverseMatrix, lodVisibility, matrix, objectColor, objectColorRGB (3), parentInverseMatrix, parentMatrix, renderInfo (3), renderLayerInfo (3), selectionChildHighlighting, template, useObjectColor, visibility, wireColorRGB (3), worldInverseMatrix, worldMatrix

Long name (short name) Type Default Flags

boundingBox (bb) compound n/a

Bounding box. The bounding box of a dagNode includes the bounding boxes of all its children and is transformed by the matrix attribute.

boundingBoxMin (bbmn) double3

Bounding box minimum.

boundingBoxMinX (bbnx) distance (double) 0.0cm

Bounding box minimum X value

boundingBoxMinY (bbny) distance (double) 0.0cm

Bounding box minimum Y value

boundingBoxMinZ (bbnz) distance (double) 0.0cm

Bounding box minimum Z value

boundingBoxMax (bbmx) double3

Bounding box maximum.

boundingBoxMaxX (bbxx) distance (double) 0.0cm

Bounding box maximum X value.

boundingBoxMaxY (bbxy) distance (double) 0.0cm

Bounding box maximum Y value.

boundingBoxMaxZ (bbxz) distance (double) 0.0cm

Bounding box maximum Z value.

boundingBoxSize (bbsi) double3

Bounding box extents. (boundingBoxMax - boundingBoxMin)

boundingBoxSizeX (bbsx) distance (double) 0.0cm

Bounding box extent in X.

boundingBoxSizeY (bbsy) distance (double) 0.0cm

Bounding box extent in Y.

boundingBoxSizeZ (bbsz) distance (double) 0.0cm

Bounding box extent in Z.

center (c) double3

Center of the boundingBox. Note: like the boundingBox attribute, this attribute is also transformed by the matrix attribute.

boundingBoxCenterX (bcx) distance (double) 0.0cm

Center X value.

boundingBoxCenterY (bcy) distance (double) 0.0cm

Center Y value.

boundingBoxCenterZ (bcz) distance (double) 0.0cm

Center Z value.

drawOverride (do) compound n/a

Parent attribute encapsulating all draw override information

overrideDisplayType (ovdt) enum 0

Override for the method of drawing. 0=Normal, 1=Template, 2=Reference

overrideLevelOfDetail (ovlod) enum 0

Override for the amount of detail to be drawn. 0=Full, 1=Bounding Box

overrideShading (ovs) bool true

Override of shading state when in shaded display

overrideTexturing (ovt) bool true

Override of texturing state when in shaded display

overridePlayback (ovp) bool true

Override of ability to animate

overrideEnabled (ove) bool false

Turn on/off the effect of the sibling attributes

overrideVisibility (ovv) bool true

Override of the object visibility

hideOnPlayback (hpb) bool false

Turn on/off the ability to hide during playback

overrideRGBColors (ovrgbf) bool false

Override flag to use RGB colors

overrideColor (ovc) unsigned char 0

Override of the object color. Valid range is [0-31]. A value of zero disables the override.

overrideColorRGB (ovrgb) float3

The floating point override color.

overrideColorR (ovcr) float 0.0

The red component of override color.

overrideColorG (ovcg) float 0.0

The green component of override color.

overrideColorB (ovcb) float 0.0

The blue component of override color.

overrideColorA (ovca) float 1.0

The alpha component of override color, if supported.

ghosting (gh) bool false

Boolean attribute controls whether ghosts of the object are displayed.

ghostColorPost (gac) float3 0.878, 0.678, 0.663

Color for the ghost frames after current frame.

ghostColorPostR (gar) float 0.0

Red color channel for the ghost frames after current frame.

ghostColorPostG (gag) float 0.0

Green color channel for the ghost frames after current frame.

ghostColorPostB (gab) float 0.0

Blue color channel for the ghost frames after current frame.

ghostColorPre (gcp) float3 0.447, 1.0, 1.0

Color for the ghost frames before current frame.

ghostColorPreR (grr) float 0.0

Red color channel for the ghost frames before current frame.

ghostColorPreG (gpg) float 0.0

Green color channel for the ghost frames before current frame.

ghostColorPreB (gpb) float 0.0

Blue color channel for the ghost frames before current frame.

ghostCustomSteps (gcs) compound n/a

Attribute which stores the step information for ghosting. This value is only used if the ghostingMode is set to preAndPost, pre, post, or customKeyframes.

ghostPreFrames (gprf) integer 3

The number of ghost steps before the current frame. This value is only used if the ghostingMode is set to customPrePost.

ghostPostFrames (gpof) integer 3

The number of ghost steps after the current frame. This value is only used if the ghostingMode is set to customPrePost.

ghostsStep (gstp) integer 1

The number of frames per ghosting step. This value is only used if the ghostingMode is set to customFramePrePost or customKeyPrePost.

ghostDriver (gdr) Message n/a

The message attribute determines which dag object's keys will be used to display ghosting for this object

ghostFrames (gf) intArray empty

Specific frames where the ghost will apear. This value is only used if the ghostingMode is set to customFrames.

ghostingMode (gm) enum 0

This attribute specifies how the user wants to specify the frames where the ghosts appear. The settings have the following meanings:

Pre And Post Frames: ghosts are drawn at the frame steps before and after the current one as specified in the ghostCustomSteps attribute
Pre Frames: ghosts are drawn at the frame steps before the current one as specified in the ghostCustomSteps attribute
Post Frames: ghosts are drawn at the frame steps after the current one as specified in the ghostCustomSteps attribute
Custom Frames: ghosts are drawn at the frames specified in the ghostFrames attribute
Pre And Post Keyframes: ghosts are drawn at the keyframe steps before and after the current frame as specified in the ghostCustomSteps attribute
All Keyframes: ghosts are drawn at all keyframes in the current playback time range

ghostOpacityRange (golr) float2 0.15, 0.5

Opacity range for the ghost drawing.

ghostFarOpacity (gfro) float 0.0

Opacity value of the ghost frames furthest away from the current frame.

ghostNearOpacity (gnro) float 0.0

Opacity value of the ghost frames closest to the current frame.

ghostUseDriver (gud) bool false

Flag indicating whether the connection on the ghostDriver attribute should be used for keyframes or not

instObjGroups (iog) compound n/a

An instanced attribute array of compound attributes used to represent "set" membership information. Connections are made to this attribute if the entire instance is in a set and connections are made to the children of this attribute if portions of this attribute are in sets.

objectGroups (og) compound n/a

An array of compound attributes used to identify the parts of the object that are in various sets. Each element in the array refers to the membership in one set.

objectGrpCompList (gcl) componentList nullptr

Specifies the portion of the object that is in the set.

objectGroupId (gid) integer 0

Group Id Integer that identifies the object group in the object.

objectGrpColor (gco) short -1

Integer representing the user-defined color index assigned to the set this that this object group is a part of. A value of -1 turns off this attribute. Warning, setting this value to anything outside the range -1..7 will cause unpredictable results.

intermediateObject (io) bool false

Boolean attribute that specifies whether the dagNode is an intermediate object resulting from a construction history operation. dagNodes with this attribute set to true are not visible and/or rendered. This attribute is automatically set so changing this value may cause unpredictable results.

template (tmp) bool false

Boolean attribute that specifies whether the object is templated. Templated objects are objects in the scene that are not rendered, always drawn in wireframe mode, and can only be selected using "template" selection mode. Note: template state is inherited by children of a dagNode.

lodVisibility (lodv) bool true

Override of the object visibility. Used to control visibility of objects for level of detail.

matrix (m) matrix identity

Local transformation matrix for the dagNode.

inverseMatrix (im) matrix identity

Inverse of matrix attribute.

objectColor (oc) short 0

Integer representing a user-defined color index to use as the dormant color for this dagNode in wireframe mode. Warning, setting this value to anything outside the range 0..7 will cause unpredictable results.

objectColorRGB (obcc) float3

The floating point object color.

objectColorR (obcr) float 0.0

The red component of object color.

objectColorG (obcg) float 0.0

The green component of object color.

objectColorB (obcb) float 0.0

The blue component of object color.

parentMatrix (pm) matrix identity

The parentMatrix instanced attribute represents the world-space transformation matrix for the parents of this dagNode. If the dagNode is a transform node and its inheritTransform attribute is false, then the parentMatrix is identity.

parentInverseMatrix (pim) matrix identity

Inverse of parentMatrix instanced attribute.

renderInfo (ri) compound n/a

Maya V7 obsolete

identification (rlid) short 0

Maya V7 obsolete

layerRenderable (rndr) bool true

Maya V7 obsolete

layerOverrideColor (lovc) unsigned char 0

Maya V7 Obsolete

renderLayerInfo (rlio) compound n/a

Parent attribute encapsulating all render override information.

renderLayerId (rli) short 0

Render layer identification number

renderLayerRenderable (rlr) bool true

Specifies whether the layer is visible when rendered.

renderLayerColor (rlc) unsigned char 0

Color with which to draw.

selectionChildHighlighting (sech) bool true

When the global selection preference for "Selection Child Highlight Mode" is set to "Use object highlight setting", this attribute will control the highlighting of children of this node. This control is inherited by this node's descendants, so if a root level node has this disabled any selected node in that hierarchy will not highlight its children.

useObjectColor (uoc) enum 0

If set to 1, the dormant wireframe color of the dagNode is controlled by the aObjectColor attribute. If set to 2, the dormant wireframe color of the dagNode is controlled by aWireColorRGB. Otherwise, the dormant color is determined by the type of object and the color preferences.

visibility (v) bool true

Boolean attribute that is set to false for invisible objects in the scene. Note: visibility is inherited by children of a dagNode.

wireColorRGB (wfcc) float3

The floating point wireframe color.

wireColorR (wfcr) float 0.0

The red component of wireframe color.

wireColorG (wfcg) float 0.0

The green component of wireframe color.

wireColorB (wfcb) float 0.0

The blue component of wireframe color.

worldMatrix (wm) matrix identity

The worldMatrix instanced attribute is the 4x4 transformation matrix that transforms the object to world-space. There is a world-space matrix for each unique path to the object. Eg. 'ball.worldMatrix[0]' identifies the world-space transformation matrix for the first instance of the object 'ball'. Each world-space transformation matrix is the result of post multiplying the 'matrix' attribute by corresponding 'parentMatrix' instanced attribute (i.e. worldMatrix[i] == matrix x parentMatrix[i]). Thus, the worldMatrix is the concatenation of the 'matrix' attribute of all the dagNodes along the path from the node up to the root of the dag hierarchy.

worldInverseMatrix (wim) matrix identity

Inverse of worldMatrix instanced attribute.