API Guide > DAG Hierarchy >

# DAG paths

A path through the DAG is a set of nodes which uniquely identifies the location of a particular node or instance of a node in the graph. The path represents a graph ancestry beginning with the root node of the graph and containing, in succession, a particular child of the root node followed by a particular child of this child, etc., down to the node identified by the path. For instanced nodes, there are multiple paths which lead from the root node to the instanced node, one path for each instance. Paths are displayed in Maya by naming each node in the path starting with the root node and separated by the vertical line character, "|".

DAG paths and worldspace operations in the API

It is important to note that because the DAG path represents how a shape is inserted into the scene, a DAG path must be used when attempting any world space operation via the API. If one simply gets an "MObject" handle to a node and asks for the world space position of a component of that node, the API operation will fail. This is because without the DAG path Maya has no idea where in world space the object is. In fact, in the case of instanced objects, there can be multiple answers to that question, and only the DAG path will uniquely identify the particular instance of the node. Almost all of the classes that contains methods that will return an MObject for a node also contain methods that will return DAG paths so you can get an MDagPath handle to the desired node. As well, all the MFn classes can be constructed with either an MObject or an MDagPath. If an MObject is used, all world space operations attempted using methods of the MFn class will fail, if an MDagPath is used, they will succeed.

Adding or removing nodes from the representation

The MDagPath class builds a representation of a path and lets you examine and modify this representation. The MDagPath represents paths as a stack of nodes with the root node being on the bottom of the stack. The push() and pop() methods allow nodes along the path to be added or removed from the representation.

Note

These methods do not add and remove nodes from the actual DAG but only from the representation constructed by the MDagPath class. The comparison and assignment operators operate on the representations constructed by the MDagPath class and not on the graph itself. So assigning one path to another will not modify the graph but only the contents of the destination MDagPath instance.

Inclusive and exclusive matrices

Since the nodes in a path exist at different levels of the DAG hierarchy, there is a different transformation that may have accumulated at each node in the path. The MDagPath class allows these transformations to be returned using the inclusiveMatrix() and exclusiveMatrix() classes.

- An "inclusive matrix" represents the accumulated transformation to the last node stored in the DAG path taking into account the last node.
- An "exclusive matrix" represents the same accumulation with the exception that it does not take into account any transformation from the last node.

For example, if a path is defined as:

|RootTransform|Transform1|Transform2|Shape

the inclusive matrix down to Transform2 would be the accumulation of RootTransform, Transform1, and Transform2. The exclusive matrix would contain the accumulation of only RootTransform and Transform1.

Why add the shape node to a DAG path

In Maya, selection at the object level results in the selection of the transform node that is the parent node of the shape actually selected. When querying the selection using MGlobal::getActiveSelectionList(), the MDagPath returned to the caller only specifies the path to this transform and not down to the actual shape that was picked on the screen. A convenience method on MDagPath called extendToShape() can be called to add the shape node below the last transform to the path.

The valid function sets applicable to a particular MDagPath are determined by the last node on the path. If the last node is a transform node, then the function sets that can operate on transform nodes can be applied to the MDagPath instance. If a shape node is the last node of the path, then the applicable function sets for the MDagPath instance are those sets which can operate on the shape.

Unique Names

The use of the DAG path allows for object names to be reused. Object names can be reused as long as the same name does not appear on more than one DAG node with a common parent.