hou.Parm class

Methods

alias(self) → str

Returns the parameter’s channel alias name. Returns an empty string if no such name exists.

appendToScope(self)

This feature is not yet implemented

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’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’s value. 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’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’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’s channel alias. 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. For symmetry, the function also returns the parameter 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.
p = hou.parm("/obj/geo1/tx")

# Execute asCode and write the output script to file.
script = p.asCode()
f = open("set_parm_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 tx parameter.  It will
# also store a reference to the tx parameter into a variable
# named 'hou_parm'.
execfile("set_parm_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.
node = hou.parm("/obj/geo1/tx")

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

# Call the function definition to set the properties on another
# parameter.
import parmlib
hou_parm = parmlib.setParmProperties(node.parm("ty"))

componentIndex(self) → int

Returns the component index of this parameter.

For example, the translation parameter along the x-axis, “tx”, would return a component index of 0, while the translation parameter along the y-axis, “ty” would return a component index of 1.

containingFolders(self) → tuple of str

Returns a tuple of strings corresponding to the names of the folders containing this parameter.

For example, if this parameter is in the Shading folder and the Shading folder is inside the Render folder, this method will return (“Render”, “Shading”).

Returns an empty tuple if this parameter is not inside a folder.

Note that calling this method on many parameters may be slow. For a faster alternative, see hou.Node.parmsInFolder.

See also the containingFolderSetParmTuples method, and hou.Node.parmTuplesInFolder.

containingFolderSetParmTuples(self) → tuple of hou.ParmTuple

Return a tuple of ParmTuples corresponding to the folders containing this parameter.

For example, if this parameter is in the Shading folder and the Shading folder is inside the Render folder, this method will return a tuple containing the Render parm tuple and the Shading parm tuple. Any parm tuples returned will be folder sets.

If this parameter is not inside a folder, an empty tuple is returned.

See also the containingFolders() method, and hou.Node.parmsInFolder and hou.Node.parmTuplesInFolder.

containingFolderIndices(self) → tuple of int

Return a tuple of indices corresponding to the folders containing this parameter. Each index refers to a folder in the corresponding folder set parameter.

This method can be implemented as follows:

def containingFolderIndices(self):
    return tuple(
        list(folder_set_parm_tuple.parmTemplate().folderNames()).index(
            folder_name)
        for folder_set_parm_tuple, folder_name in zip(
            parm.containingFolderSetParmTuples(), parm.containingFolders()))

This example makes a parameter visible in the parameter pane by opening all the folders containing it.

def makeParmVisible(parm):
    for folder_set_parm_tuple, folder_index in zip(
            parm.containingFolderSetParmTuples(),
            parm.containingFolderIndices()):
        folder_set_parm_tuple[0].set(folder_index)

copyToParmClipboard(self)

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

curKeyframe(self) → BaseKeyframe

This feature is not yet implemented

deleteAllKeyframes(self)

Removes all keyframes from this parameter.

This has no effect if there are no keyframes to delete. The value of the parameter after all keyframes are removed will be the one it evaluated to at the current frame.

This function will raise a hou.ObjectWasDeleted exception if it is invoked on a parameter that does not exist in Houdini.

This function will raise a hou.PermissionError exception if writing to the specified parameter is impossible.

See also hou.ParmTuple.deleteAllKeyframes.

description(self) → str

Returns this parameter’s label.

effectiveKeyframeAtFrame(self, frame)

This feature is not yet implemented

eval(self) → int , float , or str

Evaluates this parameter at the current frame and returns the result. See also the evalAtFrame and evalAtTime methods.

evalAsFloat(self) → float

Evaluates this parameter at the current frame and returns the result as a float.

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

evalAsFloatAtFrame(self, frame) → float

Evaluates this parameter at a certain frame and returns the result as a float.

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

evalAsInt(self) → int

Evalutes this parameter at the current frame and returns the result as an integer.

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

evalAsIntAtFrame(self, frame) → int

Evaluates this parameter at a certain frame and returns the result as an integer.

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

evalAsString(self) → str

Evalutes this parameter at the current frame and returns the result as a string.

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

evalAsStringAtFrame(self, frame) → str

Evaluates this parameter at a certain frame and returns the result as a string.

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

evalAtTime(self, time) → int , float , or str

Evalute this parameter at a given time and return the result as an integer, float or string.

See also evalAtFrame.

evalAtFrame(self, frame) → int , float , or str

Evalute this parameter at a given frame and return the result as an integer, float or string.

See also evalAtTime.

evalAsRamp(self) → hou.Ramp

Evalutes this parameter at the current frame and returns the result as a ramp.

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

evalAsRampAtFrame(self, frame) → hou.Ramp

Evalutes this parameter at a certain frame and returns the result as a ramp.

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

executeCallbacks(self)

This feature is not yet implemented

TODO: Do we need executeCallbacks now that we have pressButton?

pressButton(self)

Emulates clicking a button parameter to trigger its callback script. Raises hou.OperationFailed if the callback script could not be run.

expression(self) → str

Returns this parameter’s expression.

For example, a parameter might contain the Python expression “frame() 2”. In this case [Hom:hou.Parm#eval] at frame 2 would return the value 4, while calling expression() would return the string “frame() 2”.

If the parameter does not contain an expression, this method will raise hou.OperationFailed. Also, if the parameter contains more than one keyframe then it could contain multiple different expressions, so it also raises hou.OperationFailed in that case.

This method is roughly equivalent to...

parm.keyframes()[0].expression()

See also the setExpression(), expressionLanguage(), keyframes(), and eval() methods.

expressionLanguage(self) → hou.exprLanguage enum value

Returns the parameter’s expression’s language.

If the parameter does not contain an expression, this method will raise hou.OperationFailed. Also, if the parameter contains more than one keyframe then it could contain multiple different expressions, so it also raises hou.OperationFailed in that case.

To change the expression language, use hou.Parm.setExpression and explicitly specify the language: parm.setExpression(parm.expression(), language).

This method is roughly equivalent to...

parm.keyframes()[0].expressionLanguage()

See also the expression(), setExpression(), keyframes(), and setExpressionLanguage() methods.

getReferencedParm(self) → hou.Parm

Returns the referenced parameter. If no parameter is referenced, returns this parameter.

hasTemporaryDefaults(self) → bool

Returns whether a default has been explicitly set on the parameter.

See also the revertToDefaults() and revertToAndRestorePermanentDefaults()methods.

isAutoscoped(self) → bool

Returns whether this parameter’s autoscope property is on.

isLocked(self) → bool

Returns whether this parameter is locked (uneditable).

isParmReference(self)

This feature is not yet implemented

isPending(self)

This feature is not yet implemented

isSpare(self) → bool

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

isTimeDependent(self) → bool

Returns whether this parameter is time dependent, that is, its value changes depending on the point on the timeline at which it’s evaluated. For example the parameter has an expression containing the $F (current frame number) variable.

isMultiParmInstance(self) → bool

Return whether this parameter is an instance of a multi parm. For example, the pt0x, pt1x, pt2x, etc. parameters in an add SOP are instances of a multiparm.

multiParmInstances(self) → tuple of hou.Parm

If this parameter corresponds to the number of instances for a multiparm, return all the parameters corresponding to all instances of this multiparm.

Returns an empty tuple if this parameter is not for a multiparm.

disable(self, on)

Sets the UI disable state of this parameter 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, 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 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.

isHidden(self) → bool

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

keyCurValueAtFrame(self, frame)

This feature is not yet implemented

keyframeForCurTime(self) → Keyframe

This feature is not yet implemented

keyframes(self) → tuple of hou.BaseKeyframe

Returns the keyframes on this parameter.

keyframesInRange(self, start_frame, end_frame) → tuple of hou.BaseKeyframe

This feature is not yet implemented

language(self)

This feature is not yet implemented

lock(self, on)

Locks (lock(True)) or unlocks (lock(False)) this parameter (this is, makes the value uneditable).

Raises hou.PermissionError if this parameter is part of a locked digital asset.

menuLabels(self) → tuple of str

Returns a list of labels for all possible menu items (for a menu parameter). Raises hou.OperationFailed if this parameter is not a menu.

menuItems(self) → tuple of str

Returns a list of all possible menu items (for a menu parameter). Raises hou.OperationFailed if this parameter is not a menu.

moveToIntegerKeyframes(self, mode)

This feature is not yet implemented

name(self) → str

Returns this parameter’s name.

node(self) → hou.Node

Returns the node on which this parameter exists.

overrideTrack(self) → hou.Track or None

Returns the CHOP track overriding this parameter, if any.

parmTemplate(self) → hou.ParmTemplate

Returns the template for this parameter.

path(self) → str

Returns the full path to this parameter.

pendingValue(self)

This feature is not yet implemented

refit(self, tolerance = 0.01)

This feature is not yet implemented

removeFromScope(self)

This feature is not yet implemented

reverse(self)

This feature is not yet implemented

reverseForRange(self, start_frame, end_frame)

This feature is not yet implemented

revertToAndRestorePermanentDefaults(self)

Changes the value back to the default that ships with Houdini, and restores that default.

See also the revertToDefaults() method, and hou.ParmTuple.revertToAndRestorePermanentDefaults

revertToDefaults(self)

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

set(self, value, language=None)

Sets the parameter value at the current frame.

If this parm currently contains a channel reference to another parameter, this method will follow channel references and change the value of the referenced parameter. If this is not the desired behavior, first delete the channel reference with deleteAllKeyframes.

Pass in a hou.Ramp object, as the parameter value, to set the value of a ramp parameter. The ramp object’s type needs to match the target ramp’s type.

Raises hou.TypeError if the type of value does not match the type of this parameter. Raises hou.PermissionError if this parameter is not writable.

See also hou.Node.setParms.

setAlias(self, alias_name)

Gives the parameter another name by which it can be referenced in channels. You can pass in an empty string to remove an existing alias name.

setAsScope(self)

This feature is not yet implemented

setAutoscope(self, on)

Changes the autoscope property of the parameter. If this property is on, this parameter is automatically scoped when the object is selected.

setExpression(self, expression, language=None, replace_expression=True)

Sets this parameter’s expression.

expression	A string containing the expression that will go inside the parameter.
language	Either a hou.exprLanguage enumeration value or None. If language is None and the parameter does not already contain an expression, the language will be the node’s expression language. (See hou.Node.expressionLanguage.) Otherwise, if language is None and the parameter already has an expression, the expression language will not change.
replace_expression	This parameter only has effect if the parameter already contains keyframes. If it is True, Houdini will replace the keyframe before the current time with one containing the new expression. Otherwise, it will always add a keyframe at the current time. Note that this behavior matches what happens when you edit an expression from Houdini’s parameter dialog.

Unlike hou.Parm.set, this method does not follow channel references. That is, if this parameter is referencing another parameter and you call setExpression(), it change the channel reference expression into the specified expression.

If the parameter does not already contain any keyframes, this method is roughly equivalent to setting a keyframe at frame 1, where the keyframe’s expression and language are the ones specified.

This method can be approximately implemented as follows:

def setExpression(self, expression, language=None, replace_expression=None)
    if self.template().type() == hou.parmTemplateType.String:
        k = hou.StringKeyframe()
    else:
        k = hou.Keyframe()

    k.setExpression(expression, language)

    if len(self.keyframes()):
        if replace_expression:
            k.setTime(self.effectiveKeyframeAtFrame(hou.frame()).time())
        else:
            k.setTime(hou.time())
    else
        k.setTime(0.0)

    self.setKeyframe(k)

See also the expression, expressionLanguage, and setKeyframe methods, hou.Node.expressionLanguage, and hou.Node.setExpressions.

setKeyframe(self, keyframe)

Sets a keyframe on this parameter.

Raises hou.TypeError if keyframe is not of type hou.BaseKeyframe. Raises hou.PermissionError if this parameter is not writable.

setLanguage(self, language)

This feature is not yet implemented

setPending(self, value)

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

Raises hou.TypeError if the type of value does not match this parameter’s type. Raises hou.PermissionError if this parameter is 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.

See also hou.Node.findOrCreateMotionEffectsNetwork.

stretch(self, num_frames_to_add)

This feature is not yet implemented

stretchSubrange(self, source_start_frame, source_end_frame, num_frames_to_add)

This feature is not yet implemented

tuple(self) → hou.ParmTuple

Returns the hou.ParmTuple associated with this parameter.

For example, calling this method on the Parm object for the translation parameter “tx”, would return a ParmTuple that contains Parm objects for the three translation parameters “tx”, “ty” and “tz”. If no tuple is associated with the parameter, then the parameter itself is returned in a tuple of size 1.

type(self) → parmTemplateType

This feature is not yet implemented

unexpandedString(self) → str

Returns the contents of the parameter before dollar sign and back-tick expansion.

Examples of unexpanded strings would be “image$F.pic”, “$HIP/split.otl”, or “chs('../font1/text')”. If you were to call eval() on them, Houdini would perform variable expansion and back-tick expression evaluation, so you would get back something like “image1.pic” instead of “image$F.pic”.

Because only string parameters will attempt to do dollar sign and string expansion, this method will raise hou.OperationFailed if called from a non-string parameter.

Suppose a string parameter contains keyframes. In this situation, Houdini will not attempt to do string expansion on the parameter’s value, so calling this method will raise hou.OperationFailed. Instead of calling this method, you can call expression() to access the first Keyframe’s expression. If there are multiple keyframes, you can call keyframes() to get a list of hou.StringKeyframe objects and call expression() on those objects to retrieve the expression.