hou.ParmTuple class

A tuple of one or more node parameters. Each parameter tuple has a unique name within its node.

The ParmTuple class behaves like a Python sequence, so you can index into it using square brackets, iterate over it, call len on it, etc. The elements inside the parameter tuple are hou.Parm objects.

A parameter tuple’s name may only contain letters, numbers, and underscores. For example, objects contain a parameter tuple named "t" that contains three integer parameters. The names of the parameters inside the tuple are determined from the parameter tuple’s name and its naming scheme. For example, the "t" parameter uses the XYZW naming scheme, so the three parameters inside it are named "tx", "ty", and "tz". Note that if the parameter tuple only contains one parameter, the tuple and the parameter inside it may have the same name.

In addition to a name, a parameter tuple also has a label that is displayed to the user in the parameter dialog. For example, the "t" parameter’s label is "Translate". The label may contain spaces and punctuation characters.

Each parameter in a tuple stores a value. Different instances of parm tuples in different nodes will store their own set of parameter values. The value in a parameter may be animated, in which case the parameter evaluates to a different result depending on the current time on the playbar. See hou.Keyframe for more information about animated parameters.

Each hou.NodeType has a set of parameter tuple descriptions associated with it, and each instance of a hou.Node has a corresponding set of parameter tuple instances. The parameter tuples store specific values that are saved with the node. The descriptions of the parameter tuples, however, are represented by a hou.ParmTemplate. A parameter template describes the type, default values, ranges, etc. of a parameter tuple.

See also hou.parmTuple_ and hou.Node.parmTuple.

Methods

__getitem__(self, index) → hou.Parm

Return the Parm object for the specified component of this parameter tuple. Negative indices will index from the end.

This method makes instances of this class appear like a tuple, and lets you iterate over the parms in a ParmTuple.

Raises IndexError if the index is not valid.

>>> parm_tuple = hou.node("/obj").createNode("geo").parmTuple("t")
>>> for parm in parm_tuple:
...     print parm.name(),
tx ty tz
>>> tuple(parm_tuple)
(<hou.Parm tx in /obj/geo1>, <hou.Parm ty in /obj/geo1>, <hou.Parm tz in /obj/geo1>)

__len__(self) → int

Return the number of hou.Parms in this parameter tuple.

name(self) → str

Return the name of this parameter tuple. Note that the parameter tuple’s name and its naming scheme determine the names of the parameters inside it.

>>> node = hou.node("/obj").createNode("geo")
>>> node.parmTuple("t").parmTemplate().namingScheme()
parmNamingScheme.XYZW
>>> [parm.name() for parm in node.parmTuple("t")]
['tx', 'ty', 'tz']

>>> parm_tuple = node.parent().createNode("cam").parmTuple("dcolor")
>>> parm_tuple.parmTemplate().namingScheme()
parmNamingScheme.RGBA
>>> [parm.name() for parm in parm_tuple]
['dcolorr', 'dcolorg', 'dcolorb']

description(self) → str

Return this parameter tuple’s label that is displayed in the parameter dialog.

node(self) → hou.Node

Return the node containing this parameter tuple.

parmTemplate(self) → hou.ParmTemplate

Return this parameter tuple’s template.

eval(self) → tuple of int, float, str, or hou.Ramp

Evalute this parameter tuple at the current frame and returns the result as a tuple of integers, floats or strings, or a hou.Ramp object, depending on the type of the parameter.

See also hou.ParmTuple.evalAtFrame.

evalAtFrame(self, frame) → tuple of int, float, str, or hou.Ramp

Evalutes the parameter tuple at a certain frame and returns the result as a tuple of integers, floats, strings, or a Ramp object, depending on the type of the parameter.

evalAsFloats(self) → tuple of float

Evaluates this parameter tuple at the current frame and returns the result as a tuple of floats.

Raises hou.TypeError if a value cannot be converted to a float.

evalAsFloatsAtFrame(self, frame) → tuple of float

Evaluates this parameter tuple at a certain frame and returns the result as a tuple of floats.

Raises hou.TypeError if a value cannot be converted to a float.

evalAsInts(self) → tuple of int

Evaluates this parameter tuple at the current frame and returns the result as a tuple of integers.

Raises hou.TypeError if a value cannot be converted to an integer.

evalAsIntsAtFrame(self, frame) → tuple of int

Evaluates this parameter tuple at a certain frame and returns the result as a tuple of integers.

Raises hou.TypeError if a value cannot be converted to an integer.

evalAsRamps(self) → hou.Ramp

Evaluates this parameter tuple at the current frame and returns the result as a tuple containing a hou.Ramp object.

Raises hou.TypeError if this is not a ramp parameter.

evalAsRampsAtFrame(self, frame) → hou.Ramp

Evaluates this parameter tuple at a certain frame and returns the result as a tuple containing a hou.Ramp object.

Raises hou.TypeError if this is not a ramp parameter.

evalAsStrings(self) → tuple of str

Evaluates this parameter tuple at the current frame and returns the result as a tuple of strings.

Raises hou.TypeError if a value cannot be converted to a string.

evalAsStringsAtFrame(self, frame) → tuple of str

Evaluates the parameter tuple at a frame and returns the result as a tuple of strings.

Raises hou.TypeError if a value cannot be converted to a string.

set(self, values)

Sets the value of a parameter in the tuple at the current frame.

values

A sequence of floats or strings, corresponding to the components of this parameter tuple.

For example, the parameter tuple for “translation” contains Parm objects for translation along each of the axes, “tx”, “ty” and “tz”. If set is called with following tuple of floats, (2.5, 4.0, 5.5), then the parameter “tx” with be set to 2.5, “ty” will be set to 4.0 and “tz” will be set to 5.5.

Raises hou.InvalidSize if values has a different length than this parameter tuple. Raises hou.PermissionError if any of the parameters in this parameter tuple are not writable.

setPending(self, values)

Sets the value of a parameter in the tuple at the current frame and marks it as pending if the parameter is keyed.

values

A sequence of floats or strings, corresponding to the components of this parameter tuple.

Raises hou.InvalidSize if values has a different length than this parameter tuple. Raises hou.PermissionError if any of the parameters in this parameter tuple are not writable.

deleteAllKeyframes(self)

Remove all the keyframes from this parameter tuple.

This method be approximately implemented as follows:

def deleteAllKeyframes(self):
    for parm in self:
        parm.deleteAllKeyframes()

See also hou.Parm.deleteAllKeyframes.

revertToAndRestorePermanentDefaults(self)

Changes the value back to the defaults that ship with Houdini, and restore those defaults.

See also the revertToDefaults() method.

revertToDefaults(self)

Changes the value back to the default(s). See also the revertToAndRestoreFactoryDefaults() method.

isSpare(self) → bool

Returns whether the parameter is a “spare” (user-defined) parameter.

isMultiParmInstance(self) → bool

Return whether this parameter is an instance of a multi parm. For example, the pt0, pt1, pt2, etc. parameter tuples in an add SOP are instances of a multiparm.

lock(self, bool_values)

Lock or unlock all the parameters in this tuple. Houdini displays locked parameters as disabled and does not let you change their values.

bool_values

A sequence of True or False values, where each value corresponds to a component of this parameter. Where an element of bool_values is True, that component will be locked (uneditable), and where an element is False, the corresponding component will be unlocked (editable).

For example, the parameter tuple for “translation” contains Parm objects for translation along each of the axes, “tx”, “ty” and “tz”. If lock is called with the following tuple of boolean values, (True, True, False), then the parameter “tx” and “ty” will be locked and made non-editable, while “tz” will be unlocked and made editable.

Raises hou.InvalidSize if bool_values has a different length than this parameter tuple. Raises hou.PermissionError if any of the parameters in this parameter tuple are not writable.

hide(self, on)

Show or hide this parameter tuple in its node. Calling this method is equivalent to changing the Invisible checkbox on the Edit Parameter Interface dialog.

To change the visibility of all new instances of the node type, use hou.HDADefinition.replaceParmTuple.

setAutoscope(self, bool_values)

Changes the autoscope property of components of this parameter tuple.

bool_values

A sequence of True or False values, where each value corresponds to a component of this parameter. Where an element of bool_values is True, that component will be autoscope.

For example, the parameter tuple for “translation” contains Parm objects for translation along each of the axes, “tx”, “ty” and “tz”. If setAutoscope is called with the following tuple of boolean values, (True, True, False), then the parameter “tx” and “ty” will be automatically scoped, while “tz” will not.

Raises hou.InvalidSize if values has a different length than this parameter tuple. Raises hou.PermissionError if any of the parameters in this parameter tuple are not writable.

createClip(self, parent_node, name, create_new, apply_immediately, current_value_only) → hou.ChopNode

Creates a Channel CHOP representing this parameter. The Channel CHOP is created with the given name as a child of the given parent node. The parent_node is typically created via hou.Node.findOrCreateMotionEffectsNetwork.

create_new	Always create a new Channel CHOP. If set to False, then if a Channel CHOP already exists with the same name, it will be re-used. If the parameter already exists on the Channel CHOP, the older parameter will be removed first.
apply_immediately	If set to True, then the export flag on the Channel CHOP will be set.
current_value_only	If set to True, then only the current value of the parameter will be stored.

asCode(self, brief=False, save_values=True, save_keyframes=True, save_keys_in_frames=False, save_flag_values=True, save_aliases=True, function_name=None) → str

Returns a script of Python statements that can be executed to set the parameter tuple’s values, flags and other properties. To run the script, use either Python’s exec or execfile functions.

`brief`	When `brief` is True, the output script omits commands for setting values and flags that are set to the factory defaults. The script also omits keyframe commands that set unused values, slopes and accelerations. The value of `brief` must be either True or False.
`save_values`	When `save_values` is True, `asCode` outputs commands for setting the parameter tuple’s values. The value of `save_values` must be either True or False.
`save_keyframes`	When `save_keyframes` is True, `asCode` outputs commands for creating the parameter tuple’s keyframes (if any). The value of `save_keyframes` must be either True or False.
`save_keys_in_frames`	When `save_keys_in_frames` is True, `asCode` outputs commands for setting channel and key times in samples (frames) instead of seconds. This parameter has no effect if `save_keyframes` is set to False. The value of `save_keys_in_frames` must be either True or False.
`save_flag_values`	When `save_flag_values` is True, `asCode` outputs commands for setting the parameter tuple’s flag values. The value of `save_flag_values` must be either True or False.
`save_aliases`	When `save_aliases` is True, `asCode` outputs commands for setting the parameter tuple’s channel aliases. The value of `save_aliases` must be either True or False.
`function_name`	If `function_name` is specified, then the output script is wrapped in a Python function definition with the given name. `function_name` must be a non-zero length string consisting of only alphanumeric and underscore characters. Any invalid characters are internally converted to underscores. The wrapper function takes in a single argument which must be a reference to an existing node parameter tuple. For symmetry, the function also returns the parameter tuple reference.

Here is an example of saving the output to a file and then loading it back into Houdini:

# Get a reference to the target parameter tuple.
pt = hou.parmTuple("/obj/geo1/t")

# Execute asCode and write the output script to file.
script = pt.asCode()
f = open("set_parm_tuple_properties.py", "w")
f.write(script)
f.close()

# Execute the script.  This will set the values, flag values
# and other properties on /obj/geo1's t parameter tuple.  It will
# also store a reference to the t parameter tuple into a variable
# named 'hou_parm_tuple'.
execfile("set_parm_tuple_properties.py")

Here is an example of saving the output into a function and then calling it in Houdini:

# Get a reference to the target parameter tuple.
node = hou.parmTuple("/obj/geo1/t")

# Execute asCode and write the function definition to file.
func = p.asCode(function_name="setParmTupleProperties")
f = open("parmtuplelib.py", "w")
f.write(func)
f.close()

# Call the function definition to set the properties on another
# parameter tuple.
import parmtuplelib
hou_parm_tuple = parmtuplelib.setParmTupleProperties(node.parm("t"))