Houdini 11 Houdini Object Model hou

An instance of this class corresponds to exactly one instance of an object node in Houdini.

In Houdini, each object has a transformation (or transform) that translates, rotates, scales, etc. the geometry inside the object into its final position in world space. If the object is a subnet, so it contains other objects instead of geometry, that world transform is applied to the transforms of the objects inside it.

An object’s world transform is the combination of multiple transforms. One of these transforms is the parameter, or local, transform defined by its translate, rotate, and scale parameters. Objects may be connected together to form a scene graph, where each object inherits the transform of its inputs. The following transforms are applied sequentially to determine an object’s final transform in world space, `W`:

• `L`, The transform defined by the node’s parameters

• `P`, The object’s pre-transform (stored in the object as a matrix)

• `O`, The input, or parent, node’s world space transform (if there is an input connected), combined with the world space transform of the containing subnet object (if there is one)

The pre-transform, as you can see, allows you to apply a transform after the parameter transform but before input and containing object transforms.

Often times, you want to move move an object to an absolute position in world space by changing parameters on the object. In other words, you often want to solve for `L` given `W`. If `O^` is the inverse of `O` then

Use hou.ObjNode.setWorldTransform to automatically set the object’s parameters controlling `L` to achieve a given world transform.

Note that objects do not currently contain shear parameters. As a result, when you try to set a the object’s parameter transform to something containing shears, Houdini will remove those shears. Also note that the pre-transform may contain shears, and it is possible to introduce shears by combining individual transforms that do not contain shears.

## Methods

```worldTransform(self) ```hou.Matrix4

Return the matrix that transforms this object’s geometry into world space.

The world transform matrix contains the cumulative transforms of:

• The node’s pre-transform

• The transform defined by the node’s parameters

• The transforms of parent nodes or containing networks

This method can approximately be implemented as follows:

```    def worldTransform(self):
return (self.parmTransform() * self.preTransform() *
self.parentAndSubnetTransform())
```

```setWorldTransform(self, matrix, fail_on_locked_parms=False) ```

Adjust this object’s parameters to achieve the desired world tranformation.

This method will adjust the translate, rotate, and scale values of this object to achieve the desired final world transform. It accounts for the transforms of containing networks, parent transforms, and pre-transforms.

If `fail_on_locked_parms` is `True`, and any of the translate, rotate, or scale parameters of the object are locked, this method raises hou.OperationFailed. If it is `False` and any of those parameters are locked, this method will change their values but leave them locked.

Suppose:

• `W` is the desired new world transform,

• `W'` is the existing world transform,

• `L` is the desired transform defined by the node’s parameters,

• `L'` is the existing parm transform,

• `P` is the object’s pre-transform,

• `O` is the parent transform combined with the containing subnet's, transform

Then, since `W = L * P * O` we have `P = W * O^ * R^`. So, this method could be implemented as follows:

```def setWorldTransform(self):
self.setParmTransform(
matrix * self.parentAndSubnetTransform().inverted() * self.preTransform().inverted(),
fail_on_locked_parms)
```

Alernately, we can derive L from W' and L' as follows:

• `W' = L' * P * O`

• so `P * O = L^' * W'`

• and `(P * O)^ = W^' * L'`

and

• `W = L * P * O`

• so `L = W * (P * O)^`

• giving `L = W * W'^ * L'`

Thus, this method could also be implemented using the current world and parm transforms as follows:

```def setWorldTransform(self):
self.setParmTransform(
matrix * self.worldTransform().inverted() * self.parmTransform(),
fail_on_locked_parms)
```

Note that, because parm transforms cannot contain shears, it is possible that the resulting world transform will not match the desired transform. If `r` is a function that removes shears from a transform then the new world transform will actually be `L * P * O = r(W * O^ * P^) * P * O`.

```parmTransform(self) ```hou.Matrix4

Return the transform defined by the parameters on this node.

This method can approximately be implemented as follows:

```def parmTransform(self):
pivot_transform = hou.hmath.buildTranslate(self.evalParmTuple("p"))
return (
pivot_transform.inverted() *
hou.hmath.buildTransform({
"translate": self.evalParmTuple("t"),
"rotate": self.evalParmTuple("r"),
"scale": [self.evalParm("scale") * s
for s in self.evalParmTuple("s")],
"shear": (0.0, 0.0, 0.0)},
transform_order=self.parm("xOrd").evalAsString(),
rotate_order=self.parm("rOrd").evalAsString()) *
pivot_transform)
```

See the class documentation for the relation between this transform and the world space transform. See also hou.ObjNode.worldTransform.

```setParmTransform(self, matrix, fail_on_locked_parms=False) ```

Sets the transform controlled by this object’s parameters.

This method will adjust the translate, rotate, and scale values of this object to achieve the desired parameter, or local, transform. It will account for the existing pivot position, transformation order, and rotation order, and will leave them unchanged.

Note that object nodes do not currently have shears parameters, so any shears in the matrix will be discarded.

If `fail_on_locked_parms` is `True`, and any of the translate, rotate, or scale parameters of the object are locked, this method will raise hou.OperationFailed. If it is `False` and any of those parameters are locked, this method will change their values but leave them locked.

This method can be approximately implemented as follows, ignoring locked parameters:

```def setParmTransform(self, matrix):
parm_values = matrix.explode(
transform_order=self.parm('xOrd').evalAsString(),
rotate_order=self.parm('rOrd').evalAsString(),
pivot=hou.Vector3(self.evalParmTuple('p')))

for parm_name, key in ('t', 'translate'), ('r', 'rotate'), ('s', 'scale'):
self.parmTuple(parm_name).set(parm_values[key])
```

```preTransform(self) ```hou.Matrix4

Return this object’s pretransform.

The pre-transform allows you to apply a transform after the parameter transform but before input and containing object transforms. See the class documentation for more details.

Unlike the parameter transform, the pretransform is not stored using any parameters on the node. Instead, Houdini stores the pretransform as a matrix. Because it is directly as a matrix, the pretransform may contain shears.

```setPreTransform(self, matrix) ```

```moveParmRotateIntoPreTransform(self) ```

Set this object’s rotate values to zero and adjust the pre-transform so that the object’s world transform does not change.

Suppose:

• `W` is the world transform,

• `L` is the parameter transform without any rotate component,

• `L'` is the existing parm transform,

• `P` is the desired new pre-transform,

• `P'` is the current pre-transform,

• `O` is the parent transform combined with the containing subnet's, transform

Then,

• `W = L * P * O` and `W = L' * P' * O`

• `L * P = L' * P'`

• `P = L^ * L' * P'`

So, this method is implemented approximately as follows:

```def moveParmRotateIntoPreTransform(self):
old_parm_transform = self.parmTransform()
self.parmTuple("r").set((0.0, 0.0, 0.0))
self.setPreTransform(
self.parmTransform() * old_parm_transform * self.preTransform())
```

```moveParmScaleIntoPreTransform(self) ```

Set this object’s scale values to one and adjust the pre-transform so that the world transform does not change.

```moveParmTranslateIntoPreTransform(self) ```

Set this object’s translate values to zero and adjust the pre-transform so that the world transform does not change.

```moveParmTransformIntoPreTransform(self) ```

Set this object’s parm transform to the identity and adjust the pre-transform so that the world transform does not change.

This method is implemented approximately as follows:

```def moveParmTransformIntoPreTransform(self):
self.setPreTransform(self.parmTransform() * self.preTransform())
self.setParmTransform(hou.hmath.identityTransform())
```

```movePreTransformIntoParmTransform(self) ```

Set this object’s pre-transform to the identity and adjust the parm transform so that the world transform does not change.

This method is implemented approximately as follows:

```def movePreTransformIntoParmTransform(self):
self.setParmTransform(self.parmTransform() * self.preTransform())
self.setPreTransform(hou.hmath.identityTransform())
```

```parentAndSubnetTransform(self) ```hou.Matrix4

Return the input node’s world space transform (if there is an input connected), combined with the world space transform of the containing subnet object (if there is one). See the class documentation for more information.

This method can approximately be implemented as follows:

```def parentAndSubnetTransform(self):
if len(self.inputConnectors()[0]) != 0:
return self.inputs()[0].worldTransform()

containing_subnet = self.parent()
if containing_subnet.type().category() == hou.objNodeTypeCategory():
return containing_subnet.worldTransform()

return hou.hmath.identityMatrix()
```

```getTransformToNode(self, obj_node) ```hou.Matrix4

TODO: Document the relationship with vtorigin.

Return a matrix that transforms this node to line up with the other node.

The following invariant is true: ```node1.worldTransform() * node1.getTransformToNode(node2) == node2.worldTransform()```.

This method can be implemented as follows:

```def getTransformToNode(self, obj_node):
self.worldTransform().inverted() * obj_node.worldTransform()
```

To align node1 (an ObjNode object) with node2 (another ObjNode object), you don’t need to use `getTransformToNode()`. You can simply write: `node1.setWorldTransform(node2.worldTransform())`.

```getTransformFromPointToPoint(self, pos3, other_node, other_pos3) ```hou.Matrix4

Return the transform matrix that rotates the point pos3 (in this object node’s transform space) to the point other_pos3 (in another object node’s transform space).

```obj1.getTransformFromPointToPoint(pos1, obj2, pos2)
```

...is equivalent to...

```(obj1.worldTransform().inverted() *
hou.hmath.buildTranslate(-pos1) *
hou.hmath.buildTranslate(pos2) *
obj2.worldTransform())
```

See also the hou.ObjNode.getTransformToNode and hou.ObjNode.worldTransform methods, and the functions in the hou.hmath module.

```origin(self) ```hou.Vector3

Return the object’s origin position, in world space.

`obj.origin()` is equivalent to `obj.Vector3(0, 0, 0) * obj.worldTransform()`.

```# To compute the world space vector from obj1's origin to obj2's origin, you
# can write:
obj2.origin() - obj1.origin()

# To compute the distance, in world space, between the origins of two
# objects, simply take the length of this vector:
(obj2.origin() - obj1.origin()).length()

# If there are no rotations or scales, the vtorigin() hscript expression
# function will return the same result as obj2.origin() - obj1.origin().
# If there are rotations or scales, though, it won't.  A Python equivalent
# of vtorigin() is defined by:
def vtorigin(obj1, obj2):
return (obj2.worldTransform() * obj1.worldTransform().inverted()).extractTranslates()
```

```buildLookatRotation(self, to_node, up_vector=None) ```hou.Matrix4

Return a matrix that will rotate this object to look at the specified object.

The returned hou.Matrix4 object transforms this object from its current position in world space so that its negative z axis points at the origin of the `to_node` object.

`up_vector` can either be a hou.Vector3 object or None. If it is None, this method uses an up vector of hou.Vector3(0, 1, 0).

You can extract the rotation values from the return value with hou.Matrix4.extractRotates. You can set an object’s transform with hou.ObjNode.setWorldTransform.

```# Set the cam1 object's transform so it points at geo1.
cam1 = hou.node("/obj/cam1")
lookat_obj = hou.node("/obj/geo1")
cam1.setWorldTransform(cam1.buildLookatRotation(lookat_obj))
```

```setInputAndNeverKeepPosition(self, input_index, node_to_become_input, output_index=0) ```

This feature is not yet implemented

```setCookTransform(self, matrix) ```

Set the parameter transform for the Python object that’s cooking. Call this method from objects implemented in Python to set the result of the cook.

Note that an object implemented in Python controls the parameter transform (i.e. the result of hou.ObjNode.parmTransform). The world transform (i.e. the result of hou.ObjNode.worldTransform) is still affected by parent node’s transforms, pre-transforms, etc.

This method raises hou.OperationFailed if you call it on an object that is not implemented in Python or if you call it from outside that object’s Python cook code.

See the Transforms from Disk example.

```combine(self, nodes) ```

Combine the geometry from the given list of hou.ObjNode’s into this object. After this operation, the old objects will be deleted.

Raises hou.ObjectWasDeleted if any of the nodes no longer exist in Houdini. Raises `TypeError` if any of the nodes are not of type hou.ObjNode. These exceptions are raised prior to performing the combine operation to avoid partial results.

```displayNode(self) ```hou.Node or ```None ```

If this object contains SOPs or DOPs, return the one that has its display flag on. Otherwise, return None.

```renderNode(self) ```hou.Node or ```None ```

If this object contains SOPs or DOPs, return the one that has its render flag on. Otherwise, return None.

```isObjectDisplayed(self) ``` → bool

Return whether or not this object is displayed. This method takes into account both the display flag and the `display` parameter. If the `display` parameter is enabled, because the `tdisplay` parameter is set, this parameter overrides the flag.

```isDisplayFlagSet(self) ``````bool ```

Return whether or not this object’s display flag is turned on. Note that the display flag and the `display` parameter both determine whether the object is actually displayed.

Use hou.ObjNode.isObjectDisplayed to determine if the object is actually displayed.

```setDisplayFlag(self, on) ```

```isSelectableInViewport(self) ``` → bool

Return whether or not the selectable flag is set. When it is not set, it is not possible to select this object or any of its geometry interactively in the viewport.

```setSelectableInViewport(self, on) ```

```isShowingOrigin(self) ``` → bool

Return whether or not this object displays its local origin gnomon in the viewport.

Note that you can change this setting by right-clicking on the node.

```showOrigin(self, on) ```

Show or hide this object’s local origin gnomon in the viewport. See also hou.ObjNode.isShowingOrigin.

```isUsingXray(self) ``` → bool

Return whether or not this object displays its geometry in xray mode. Houdini displays xrayed geometry in wireframe and makes it visible even when it is hidden behind another surface.

Note that you can change this setting by right-clicking on the node.

```useXray(self, on) ```