Chris Sprance

Character Technical Director

Dynamic Descriptive Parms in Houdini

Dynamic descriptive parms can be super helpful indicators of what an hda is doing without having to dive in to a node. Think about how handy the little blue text on the group node can be and try and think of ways to use that in your next hda. This guide will teach you what a descriptive parm is, how to use a descriptive parm, and how to create a dynamically updating descriptive parm using a little bit of python and a callback script. We'll learn about all of those things and how they work together.

What is a Descriptive Parm?

Descriptive Parm Example

A Descriptive parm is a parameter you can define on a HDA in the Nodes tab of the HDA Type Properties window. The descriptive parm shows up on the node in the network view to the right and below the node name in blue text, just like the group node.

The houdini docs on Descriptive Parm here describe the Descriptive Parm as follows:

Descriptive Parm

If this contains the internal name of a parameter on this asset, Houdini will display the value of the parameter as the descriptive text badge in the network editor.

This should be a parameter whose value tells the user at-a-glance the most important thing about the node’s current settings. For example, on a File node this is the file path.

How to use Descriptive Parms.

To use a descriptive parm you can define which parm on the HDA should show up by opening the Type Properties window of the HDA, selecting the Node tab and typing the name of the parm in the descriptive parm input.

Descriptive Parm

This parm will now always show whatever it contains in the blue text. This is very hand by itself for lot's of things but sometimes we want multiple values to effect it or maybe generate some values based on some geometry data. This is when you want to use a little python magic.

How to Dynamically Update a Descriptive Parm

In order to create a dynamically updating descriptive parm we need to keep a few things in mind:

  • We need a parm of the data type we want to use defined in the parameters section.
  • Sometimes it makes sense to have this parameter be invisible.
  • Sometimes maybe we want to generate a value and then allow the user to tweak it themselves after the fact.

To dynamically set a parm I created a string parm and marked it as invisible. It doesn't have to be marked as invisible but unless you want the user to be able to see it and edit, then this is the best way. This parm will serve as a string we can set and store on the HDA with python that will be used to construct the descriptive parm.

Once you create the invisible parm (as a string or whatever data type you need it as), don't forget to jump in to the node section and set the correct parm in the descriptive parm.

Invisible Parm


In order to update our invisible parm with the text we want to show we first need to create a Python Module and a function that can handle the updating of the HDA for us.

Create a Python Module Script by Clicking on the Scripts tab and select the Python Module item from the Event Handle dropdown list.

Python Module

The code for the update function could look something like this:

def update_descriptive_parm(hda):
    # Grab our values from our HDA parms
    min_h = hda.parm('min_height').eval()
    max_h = hda.parm('max_height').eval()
    min_a = hda.parm('min_area').eval()
    max_a = hda.parm('max_area').eval()
    # Use those values to assemble the string we want to show in the descriptive parm
    text = """@height: {0}-{1}
              @area: {2}-{3}""".format(
        min_h, max_h, min_a, max_a
    # Set that parm which will then show up on the node itself in the Network View

Python Module Code

What does the script do?

Notice in the script we pass it in an HDA. This HDA will be the root HDA node that we will pass in from the callback script from kwargs['node'] (More on that below).

We can then grab specific parms from the hda that we want to show in the descriptive parm. In this case we are grabbing each of the parms of min/max height, min/max area and then constructing a string from those parms and finally setting the invisible parm we created that is being referenced in the descriptive parm input under the HDA's Type Properties window in the Node Tab. I have named that invisible parm descriptive_parm to be explicit.

Now that we have the script written let's figure out how to run it. We do this using callback scripts.

Callback Scripts

Add a callback script to each parm you want to have update the descriptive parm.


Each time one of these parms is changed it will fire off the script we created in the Python Module section passing the current kwargs'node' (Which is the HDA itself).

Notice as well that you can change the language to python or hscript. In this instance we want to use Python so make sure that is set correctly.

The callback script does a few things here.

  • kwargs['node'].hm() Grabs the HDA node and returns us the Python Module defined inside of Scripts/Python Module in the HDA's Type Properties Window
  • Calls the function update_descriptive_parm. Remember when we defined this method earlier? This is how you call those functions.
  • Notice here how we pass in the HDA node to the function using kwargs['node'] again.
  • There are other interesting things inside of kwargs[] that you may want to know about at some point check it out some time with dir().

This means each times this input is changed, it will go and update the descriptive_parm parm and you will see that value reflected in the network view.

That's the whole process, you can get as creative as you need.