Toggle Video Safe Area Shelf Item

Creating a Video Safe Area Toggle Shelf Tool

Since my work is primarily for video and interactive domains, I have a need to check my video safe areas often. Not a big deal. Almost every animation application has the ability to toggle the safe area guides on or off. Houdini is no different, however, it takes a few steps. Enough to be a bit annoying. In this post I’m going to show how I went about creating a shelf tool that toggles the safe area guides on or off.

Shelf Sets, Tabs, & Tools

The shelf is the strip of icons along the top of the main window and is composed of a shelf set, tabs, and tools. The shelf set is a re-sizable area made up of a number of tabs with their tool items. For example, the Technical director shelf set has the Create, Modify, Model, and Polygon tabs. This is the shelf set you see on the left hand side of your default Houdini desktop install. There are others such as the Animation and Character shelf sets. This is what an empty shelf set looks like.

Empty Shelf
Empty shelf set


A tab contains tools or shelf items. So when you look at the Create tab, you see the Box tool, the Sphere tool, etc. The Grains tab contains Dry Sand, Wet Sand, and so forth. These tools are the ones you use to create a sphere or drop down a fluid sim network. It’s an icon that has a script hooked up to it to activate a tool or perform some action. You can have these actions appear in your Tab ⇥ menu or assign them a hotkey.

One important aspect of tabs and tools is that they can appear in different shelf sets. This is why the Technical Director shelf set has some of the same tools as the Create & Refine shelf set. Also, since these shelf sets are saved to an XML file, you can share them or transfer them around. So I think we are ready.

Creating a Shelf

The first thing we will do is create a shelf tab. For this you need to click on the small plus sign or the upside down triangle on the shelf. Once you click on New Shelf, a dialog window will pop up asking you to name your tab and the location where you want to save the shelf. By default it will save the .shelf file to your Houdini preferences folder. You can leave it as default.shelf or give it a more descriptive name.

There are two tabs in this windows. The Options Tab contains the Name and Label parameters. The Name parameter is a unique internal name used by Houdini. Make sure it does not contain any spaces. This is how the tool is accessed programmatically. The Label is the human-readable name. This is the front facing UI name. It does not have the be the same as the Name parameter but it’s a good idea that they match up or relate to each other.

Creating a New Shelf
Creating a New Shelf


The Tools Tab shows all the Houdini tools available to your script which you can add by selecting any one of them. We won’t worry about this because we are creating a custom tool. Click accept after filling in the parameters. Now we have a nice empty shelf we can populate with tools.

Adding A Tool

Now we begin the tool creation process. Right click on the empty area of the shelf tab that was just created. Another window will pop up and there are lot more tab options in this window. The Options tab contains the parameters we just discussed but now you have the ability to add a fancy icon. You can use the stock icons Houdini provides or you can create a custom square sized png, pic or svg graphic. As far as size, I think 256×256 or 512×512 would be good choice. Keep it nice and crisp like a piece of bacon.1 You can also add some keywords to aid in searches.2

Adding a new tool.
Adding a new tool.


The Scripts tab is the one we will use shortly to write our script.  The Help section I won’t cover since it has a syntax of its own and it’s better left for user research. The Context tab allows you to control on which tab menus (in which network contexts) your tool appears when the user opens the tab menu in the viewer or network editor. So your tool is not just confined to the shelves. The last tab is the Hotkeys and I think this one is self-explanatory but have a look at it because it has a great deal of flexibility built in. Switch over to the Script tab.


The Python code for our tool is fairly basic and only a few lines. The special thing about this Python script is we’re going to inject some Hscript in order to accomplish our task. It will show you how you can call HScript commands with Python. Let me show the code first and then I’ll explain.

# Toggle video safety guides

if not hasattr(hou.session, "safeArea"):
    print("Adding session attribute.")
    hou.session.safeArea = True
hou.hscript("viewdisplay -s {0} *".format("on" if hou.session.safeArea else "off"))
hou.ui.setStatusMessage("Video safe area {0}".format("ON" if hou.session.safeArea else "OFF"))
hou.session.safeArea = not hou.session.safeArea

The core of the script is accomplished in line seven. As far as I know, toggling the safe guides is not possible through Python, hence, the use of HScript. Let’s talk about this for a minute. We are using HScript’s viewdisplay command to turn the safe guides on or off. How did I know about viewdisplay? Simple, I looked it up in the docs. There are all kind of things you can do by passing in a different option flag. For example, instead of viewdisplay -s, you can do viewdisplay -k and toggle the camera mask on or off. Let’s do an example to show you what is going on.

Make sure the safe guides are off. Open a Houdini Textport and type in the following command:

viewdisplay -s on *
Textport code completion
Textport code completion


As you type, you should see the code completion helper pop up. The viewdisplay takes an option flag and the viewports you want to affect. We provide the -s option to target our safe guides, whether we want them on or off, and the viewports we want to affect. You can target specific viewports but for now, just use an * which means it will affect all the viewports. After pressing enter, you should see the safe guides turn on. Now hit the up arrow key ↑ and change the on to off. The guides should turn off. Nifty! This going to be the base of our tool. Now we just need to introduce some more code to create the toggle functionality.

Session Module

The first line in the script is a comment. Comments are just notes for yourself or others and trust me, you want to comment your code. In Python, the hashtag or pound sign at the beginning of line denotes a comment. They are great for short reference notes or to mute a line of code that you may want to reference or execute later.

The block of code starting on line three needs some explanation. In order to create the toggle, we need a way of knowing if the guides are on or off between each tool click. Houdini has a module called hou.session that allows you to define custom classes, functions and variables that can be called from within the current Houdini session. This is handy because we are going to create an attribute that we can assign a True or False value to and check if our safety guides are on or off. One important thing to keep in mind is that anything you add to this module is only available for the current Houdini session.

Let’s do a quick example by opening up a Python shell in Houdini and typing in the following:

hou.session.myValue = "Houdini"

Here, we are assigning the String value “Houdini” to the myValue attribute. The name myValue is arbitrary. You can use “guides”, “safeGuides” or “cat”. Let’s inspect the module and print out our new attribute value.

Setting a value in hou.session
Setting a value in hou.session


As you can see, or value is indeed tucked away in our session module and it holds the value we assigned to it. Getting back to our code, we first we want to check if the “safeArea” attribute exists. We do this by using Python’s built-in hasattr() function. This function takes and objet and the String name of the attribute you want to check for. If the name of that attribute exists, we get back True otherwise we get False. This line says, if the “safeArea” attribute does not exist in the session module — i.e we get back False — execute the code block and add the attribute.

The fourth line is just printing out some information. This is an optional line. The fifth line is where we add the “safeArea” to the session module and assign it the Boolean value True. Now we are ready to use the viewdisplay command through Python.

Python & HScript

The seventh line in our script is where we are going to inject the HScript we previously discussed. To do this, we will use the hou.hscript() function. This function allows us to execute an HScript command through Python. It also expects the command to be a String. In other words, the whole command needs to be wrapped around quote marks. This is important as you will see next.

So what exactly is going on here? What is the extra fluff? Jump over to a Python shell and lets try our function out. Again, make sure your guides are off.

hou.hscript("viewdisplay -s on *")

This works exactly the same as before but within a Python context. Again, notice we are wrapping our command within quotes. There is one issue that we need to address. That is, how do we pass in a dynamic on or off value to our command? Look at the command again. It expects an on or off String value. If you thought to yourself, “Hey! Let’s use the “safeArea” attribute to get our value.” it would be clever but it would not work because Python does not use on or off. You need to use True or False and these are not String types, they are Boolean values. One way around this is through a String format.

Python’s built-in format() function can called on our string and allows us to perform formatting operations. The string we call the function on has replacement fields delimited by braces {}. Each replacement field contains either the numeric index of a positional argument, or the name of a keyword argument. The replacement field is then replaced with the string value of the corresponding argument.

# str.format(*args, **kwargs)

hou.hscript("viewdisplay -s {0} *".format("on" if hou.session.safeArea else "off"))

Since we want to determine the value of “safeArea” at the time of execution, we do an if/else on “safeArea” within the format() function. If the “safeArea” is True, then the value within the curly braces is on, otherwise it’s off. It may look odd to you because it’s on one line but it is basically the following:

if hou.session.safeArea:

The eight line is adding a message to the status bar which is on the bottom left side of the Houdini interface. This is also an optional line but it helps give the script a bit of polish. Finally, the last line is setting our “safeArea” attribute to the opposite of its original value. But why do we do this? Let’s run through the code as if we were the script.

Code Execution

Clicking our button for the first time, we check to see if the “safeArea” attribute exists. If it does not exist, which it doesn’t since this is the first time we are executing the script, let’s create it and set its value to True. Depending on whether the “safeArea” session value was True or False, we set the options for the viewdisplay command. Since the value is True, we set viewdiplay to on. Now our safe guides are active. What happens when we click the button again?

This time, we start over and check to see if our attribute exists. The if block is not executed because the attribute does exist. Once we get to the hscript() command, what do you suppose the value we pass to viewdisplay is going to be? On or off? Remember the safe guides are on. This time, we want to turn them off so the value needs to be off or False. This is the reason we reversed its value in the last line of code. Otherwise, “safeArea” would still be True and nothing would ever change. Our guides are now disabled. Finally, we reverse the value again to True so on the next trip the viewdisplay command receives an on value.

Wrapping up

There you have it! A basic shelf tool to toggle the safe areas on or off. All done with a bit of Python magic and HScript. The script is basic but it’s a good start to writing more complex tools. You can use this as a template if you want to manipulate other areas of the viewports. Hopefully this all made sense to you.

Houdini shelf tools
Houdini shelf tools

1. I don’t eat bacon. Sorry.
2. I may be wrong on this.



I am a motion designer & developer based out of South Florida. When not designing or animating pixels, I wrangle some code. If all else fails, I watch Twilight Zone, I Love Lucy, or Three's Company reruns.