hou.ParmTuple

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__	Return the Parm object for the specified component of this parameter tuple. Negative indices will index from the end.
__len__	Return the number of hou.Parms in this parameter tuple.
asCode	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.
copyToParmClipboard	Copies this to the parameter clipboard. See also hou.parmClipboardContents.
createClip	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.
deleteAllKeyframes	Remove all the keyframes from this parameter tuple.
description	Return this parameter tuple’s label that is displayed in the parameter dialog.
disable	Sets the UI disable state of this parameter tuple in its node. This is not the same as locking a parameter, as the underlying value can still be modified. It’s closer to what a disable-when conditional does, when a parameter is disabled automatically by it.
eval	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.
evalAsFloats	Evaluates this parameter tuple at the current frame and returns the result as a tuple of floats.
evalAsFloatsAtFrame	Evaluates this parameter tuple at a certain frame and returns the result as a tuple of floats.
evalAsInts	Evaluates this parameter tuple at the current frame and returns the result as a tuple of integers.
evalAsIntsAtFrame	Evaluates this parameter tuple at a certain frame and returns the result as a tuple of integers.
evalAsRamps	Evaluates this parameter tuple at the current frame and returns the result as a tuple containing a hou.Ramp object.
evalAsRampsAtFrame	Evaluates this parameter tuple at a certain frame and returns the result as a tuple containing a hou.Ramp object.
evalAsStrings	Evaluates this parameter tuple at the current frame and returns the result as a tuple of strings.
evalAsStringsAtFrame	Evaluates the parameter tuple at a frame and returns the result as a tuple of strings.
evalAtFrame	Evalute the parameter tuple at a given frame and return the result as a tuple of integers, floats, strings, or a Ramp object, depending on the type of the parameter.
evalAtTime	Evalute the parameter tuple at a given time and return the result as a tuple of integers, floats, strings, or a Ramp object, depending on the type of the parameter.
hide	Sets the UI hidden state of this parameter tuple in its node. Calling this method is equivalent to changing the Invisible checkbox on the Edit Parameter Interface dialog, or hiding the parameter with a hide-when conditional.
isDisabled	Returns the disable state of the parameter tuple, ignoring the lock state. This can be used to read the result of a disable-when conditional.
isHidden	Returns the hidden state of the parameter tuple. This can be used to read the result of a hide-when conditional.
isMultiParmInstance	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.
isSpare	Returns whether the parameter is a “spare” (user-defined) parameter.
lock	Lock or unlock all the parameters in this tuple. Houdini displays locked parameters as disabled and does not let you change their values.
name	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	Return the node containing this parameter tuple.
parmTemplate	Return this parameter tuple’s template.
revertToAndRestorePermanentDefaults	Changes the value back to the defaults that ship with Houdini, and restore those defaults.
revertToDefaults	Changes the value back to the default(s). See also the revertToAndRestoreFactoryDefaults() method.
set	Sets the value of a parameter in the tuple at the current frame.
setAutoscope	Changes the autoscope property of components of this parameter tuple.
setPending	Sets the value of a parameter in the tuple at the current frame and marks it as pending if the parameter is keyed.

__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.

Note that a folder parameter will have a hou.FolderSetParmTemplate template and a multiparm parameter will have a hou.FolderParmTemplate 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 the evalAtFrame and evalAtTime methods.

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

Evalute the parameter tuple at a given time and return the result as a tuple of integers, floats, strings, or a Ramp object, depending on the type of the parameter.

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.

disable(self, on)

Sets the UI disable state of this parameter tuple in its node. This is not the same as locking a parameter, as the underlying value can still be modified. It’s closer to what a disable-when conditional does, when a parameter is disabled automatically by it.

isDisabled(self) → bool

Returns the disable state of the parameter tuple, ignoring the lock state. This can be used to read the result of a disable-when conditional.

hide(self, on)

Sets the UI hidden state of this parameter tuple in its node. Calling this method is equivalent to changing the Invisible checkbox on the Edit Parameter Interface dialog, or hiding the parameter with a hide-when conditional.

To hide a folder, use hou.Node.setParmTemplateGroup. This method cannot be used to hide a folder because a parm tuple corresponds to a set of folders, not an individual folder.

To change the visibility of all new instances of the node type defined by a digital asset, use hou.HDADefinition.setParmTemplateGroup as in the following example:

def showParmTupleInDefinition(parm_tuple, visible):
    '''parm_tuple is a hou.ParmTuple on an instance of the digital asset.'''
    definition = parm_tuple.node().type().definition()
    parm_template_group = definition.parmTemplateGroup()
    parm_template = parm_template_group.find(parm_tuple.name())
    parm_template.hide(not visible)
    parm_template_group.replace(parm_tuple.name(), parm_template)
    definition.setParmTemplateGroup(parm_template_group)

isHidden(self) → bool

Returns the hidden state of the parameter tuple. This can be used to read the result of a hide-when conditional.

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"))

copyToParmClipboard(self)

Copies this to the parameter clipboard. See also hou.parmClipboardContents.

hou.ParmTuple class

Methods