Houdini 18.0 Reference

Context options

Context options are similar to environment variables, except they are stored with the HIP file and it’s easy to use them in expressions.

On this page

Overview

Context options are useful for scene-specific variables. For example, you can create a render_quality variable, and reference it in all your render nodes, and a shot_name string that you overlay on all non-final renders.

You can create context options using the context option editor or Python scripting, and then use them in expressions or in Python.

This can be particularly useful when you're using the same HIP file to render multiple shots. You can set up variables with shot-specific values, and change the variables when you change which shot you're working on.

Internally, context options can store either floating point number or string values, keyed to an internal name string. However, they also let you associate a "configuration string" with each option. The context option editor uses this string to store extra information such as a human-readable label, an order, and a user interface type.

You can reference context option values in expressions using @name. For example, if you create an option with the internal name render_quality, you could set the Quality parameter of your main render node to @render_quality and the Quality of a preview render node to @render_quality / 2.

You can also create and read context option values in Python scripts.

Context options are saved with the HIP file. A newly created HIP file has no context options. If you always want to start new files with a default set of context options, you can export|#hom] the context options as a JSON file and import them in the 456.py HIP file creation script.

Context option editor

To...Do this

Open the context option editor window

Choose Edit ▸ Context Options.

Open the context option editor as a pane tab

In the pane where you want the editor, click the New Tab button and choose Context Option Editor.

Add a new context option

Click the Add icon in the top left corner and choose the type of option to add. (See option configuration below for information about option types.)

Delete an option

Select the option and then click the Remove icon in the top left corner, or press Delete.

Edit an option’s configuration

  • Select the option and click the Edit icon in the top right corner to show the edit panel.

  • You can continue to work with the options with the edit panel shown. The editing interface updates to always show the selected option.

  • To hide the edit panel, click the Edit icon again.

Edit an option’s label

Select the option, then click the label or just start typing.

Note

When you edit a label, if the option still has a generic internal name, the editor automatically changes the option’s internal name to match the label (it converts the label to lowercase and replaces spaces with underscores). This only happens once. After that, if you want to change an option’s internal name, you can use the edit panel.

Edit an option’s internal name

Select the option and click the Edit icon in the top right corner to show the edit panel. Change the internal name field.

Edit an option’s value

Use the editor on the right side of the option row.

Change the order of options in the editor interface

Drag the option’s row up or down in the table.

Update the editor with changes made outside the editor

Click the Reload icon in the top left corner.

For example, if you create a new context option using hou.setContextOption(), you will need to reload the editor to show the new option.

Export the current context options (including configuration) to a JSON file

Click the Export button in the lower right corner, then choose the file you want to export to.

Import context options from a JSON file

Click the Import button in the lower right corner, then choose the file you want to import.

If the scene file already has context options, Houdini will ask you if you want to clear them before importing, or merge the imported options over the existing options.

Using context options

  • In parameter expressions, you can use the value of a context option with @name.

  • In a Python script, you can get the value of a context option with hou.contextOption().

Option configuration

Similar to other elements in Houdini such as parameters, context options have an internal name (the name you use in @name expressions and scripting) and a label (the human-readable name that appears in the option editor user interface).

Internal Name

The name you use for this option in @name expressions and scripting.

Label

The human-readable label for this option when it appears in the context option editor.

Tooltip

A tooltip that appears if the user hovers over this option in the option editor table. You can use this to display additional help for each option to the user.

Type

Text

A freeform string. The interface is a plain text box.

Number

A freeform number. The interface is a plain text box.

File Path

A (platform-native) file path string. The interface is a text box with inline auto-completion, and a file chooser button.

Node Path

A Houdini node path string. The interface is a text box with inline auto-completion, and a node chooser button.

Float Slider

A number within a range. The interface is a text box and slider. You can choose whether the user can enter values outside the range’s minimum and/or maximum.

Int Slider

A whole number within a range. The interface is a text box and slider. You can choose whether the user can enter values outside the range’s minimum and/or maximum.

(Note that the value is not really an integer: number values in context options are always stored as floating point. The user interface of this type restricts its values to whole numbers, but that number is still stored internally as a float.)

String Menu

A string, chosen from a menu. You can set up the contents of the menu using the context editor’s edit panel.

Int Menu

A number, chosen from a menu. You can set up the contents of the menu using the context editor’s edit panel.

(Note that the value is not really an integer: number values in context options are always stored as floating point. The user interface of this type restricts its values to whole numbers, but that number is still stored internally as a float.)

Python Menu

A string, chosen from a menu that is generated by a Python snippet. You can write/paste the Python snippet in the context editor’s edit panel.

Checkbox

A value of either 1.0 (on) or 0.0 (off). The interface is a checkbox.

Heading

Shows its label in large type that spans both columns. This can be useful for organizing your context options into sections.

Slider types

Normally Minimum and Maximum set the slider range, but the user can still manually enter values less than the minimum or greater than the maximum. You can turn on Min locked and/or Max locked to enforce the minimum/maximum even on values the user enters manually.

Min Locked

Prevent the user from entering a value less than the Minimum.

Minimum

The minimum end of the slider range.

Maximum

The maximum end of the slider range.

Max Locked

Prevent the user from entering a value greater than the Maximum.

String/Int menu types

Automatically generate values

If this is on, the "value" associated with each menu item is created automatically. For string menus, the value is the same as the label. For integer menus, the value is the index of the chosen item, starting at 0.

For example, say you turn on Automatically generate values and set up a menu with three items, Apple, Bear, and Cactus. If the option is a String Menu and the user chooses Bear, the variable will be set to Bear. If the option is an Int Menu and the user chooses Cactus, the variable will be set to 2.

Menu items

  • Click Add to add a menu item.

  • To remove a menu item, select the item and click Remove.

  • To edit a label, select the row and click the label.

  • To edit a value, select the row and click the value.

  • To re-order the menu, drag items up or down in the table.

Python menu types

Menu Generation Script

Type some Python that generates a list of (name, value) pairs.

  • If the Python is an expression (it evaluates to a value), Houdini will evaluate it as an expression and expect the value to be a list of (name, value) pairs.

  • If the Python is a statement or set of statements, Houdini will act as if it’s the body of a function. This means you have to use the return keyword in your Python script to return a list of (name, value) pairs.

For example, here’s some Python that builds a menu where the item labels are environment variable names and the item values are the environment variable values:

import os
menu = []
for name, value in os.environ.items():
    if not name.startswith("HOUDINI"):
        continue
    item = ("$" + name, value)
    menu.append(item)
return menu

Scripting context options

The following HOM functions let you script the values of context options:

You can also script the Export and Import functions from the context option editor:

import contextoptions

# Export all context options in this scene to a JSON file
contextoptions.exportJson("options.json")

# Import context options from a JSON file and merge them over
# any existing options in this scene
contextoptions.importJson("options.json")

To clear any existing options before importing, you can just iterate over all existing options and delete them:

for name in hou.contextOptionNames():
    hou.removeContextOption(name)

Reference

User interface

  • Menus

    Explains each of the items in the main menus.

  • Viewers

    Viewer pane types.

  • Panes

    Documents the options in various panes.

  • Windows

    Documents the options in various user interface windows.

Programming

  • Expression functions

    Expression functions let you compute the value of parameters.

  • Expression cookbook

    Tips and tricks for writing expressions to accomplish various effects.

  • Python Scripting

    How to script Houdini using Python and the Houdini Object Model.

  • VEX

    VEX is a high-performance expression language used in many places in Houdini, such as writing shaders.

  • HScript commands

    HScript is Houdini’s legacy scripting language.

Command line

Guru level

Plugin installation

  • Houdini Packages

    How to write and combine multiple environment variable definition files for different plug-ins, tools, and add-ons.