All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
OBJ Concepts

Scene Hierarchy

In Houdini, the scene consists of a number of objects defined by an OBJ_Node. Each scene object specifies own position and orientation with respect to its scene parent, if it has one. If the object does not have any parent, the position and orientation is defined with respect to the world origin. The parent of a scene object is usually equivalent to the input node of the network OBJ_Node defining that scene object. Thus, connecting several nodes in the network will produce a hierarchy of objects in the scene, where each object lives in the space of its parent. And, changing the position or orientation of the root object will affect the position and orientation of all the object in the hierarchy.

As we can see, the primary purpose of an OBJ_Node is to define a position of an object in a scene. The position in space is determined by a transformation matrix that moves the origin and orients the axes of the local reference frame. So, in case of object nodes, cooking a node means evaluating its local transformation matrix, based on the translation, rotation, and scale parameters. First, the node obtains a transformation matrix of its input node (i.e., cooking its parent) and then it combines that matrix with its own local matrix to form the final transformation from its local space to the global world reference frame of the scene. For cooking, the operator input and dependency structure are being used to efficiently manage the generation of object transformations.

Considering how the transformation matrix flows from an input node to an output node in the network and how it relates to the position hierarchy in the scene, it becomes clear why an input node in the network corresponds to a parent in the scene object hierarchy. The scene hierarchy parent object, however, should not be confused with the network parent node, which is the node that contains the OBJ_Node child (see Architectural Overview). Rather, in the scene hierarchy, the parent object is the input of the OBJ_Node. The accessor methods are equally easy to confuse. The OBJ_Node::getParentObject() returns the parent in the scene hierarchy, whereas the inherited OP_Node::getParent() returns the containing parent node (usually a node named "/obj").


The relative position of an object in the scene with respect to its parent is defined by a transformation matrix OBJ_Node::myXform and the position of an object with respect to the world origin is defined by the OBJ_Node::myWorldXform matrix. The OBJ_Node calculates these two matrices during its cook process, and it also dirties an inverse world transformation matrix OBJ_Node::myIWorldXform. When writing a new object operator, usually the objective is to implement a new technique for calculating these these transformation matrices.

Once the object node has cooked and evaluated its transformations, it is safe to retrieve them, since they are all up-to-date. There are several methods that will first cook the node, if necessary, and then return the transform matrix. For example, OBJ_Node::getLocalToWorldTransform() method will return the global transform matrix OBJ_Node::myWorldXform, while OBJ_Node::getLocalTransform() will return the local OBJ_Node::myXform matrix. You can also obtain the inverse of the global matrix with OBJ_Node::getInverseLocalToWorldTransform(). The following code fragment illustrates how to obtain these three matrices.

OBJ_Node * obj_node;
UT_DMatrix4 local_xform;
UT_DMatrix4 world_xform;
UT_DMatrix4 inverse_world_xform;
obj_node = findOBJNode( "/obj/mynode" );
obj_node->getLocalTransform( context, local_xform );
obj_node->getLocalToWorldTransform( context, world_xform );
obj_node->getInverseLocalToWorldTransform( context, inverse_world_xform );
See Also
Object Transform Model


While, OBJ_Node transformation matrix determines the position in space, it is the contents of the OBJ_Node that determines what appears at that location. In other words, an OBJ_Node is a sub-network that contains SOP_Node nodes, and these SOP_Nodes define geometry that appears at the OBJ_Node position. In the network sense, the OBJ_Node is a parent of the SOP_Nodes, which again, should be kept distinct from the scene transform hierarchy of objects.

The purpose of SOP_Node nodes is to create and modify geometry, such as points, lines, and polygon meshes. The coordinates used to define the geometry denote the point positions in the OBJ_Node frame of reference, and are then transformed to the world space using the transformations of the object hierarchy above the given OBJ_Node, including the OBJ_Node itself.

There are two methods that return the display and render pointers to the SOP_Node responsible for cooking the final geometry: OBJ_Node::getDisplaySopPtr() and OBJ_Node::getRenderSopPtr().


Another role for OBJ_Nodes is to provide information about rendering properties of the object. For instance, geometry objects have parameters which control the materials and shaders used for ray-tracing the object. As an another example, camera objects have parameters that specify a viewing frustum that can be used in specifying the viewpoint to be rendered. In general, an output driver node (ROP) will inspect the object node's parameters and will generate appropriate IFD or RIB output that describes the given object to the rendering engine.