• Currently Python states are available in the following contexts: SOP (geometry), OBJ, DOP and LOP levels.

• Handles cannot be bound to nodeless states.

For creating HDA viewer states, use the code generator available in the Viewer State Editor tab of the Operator Type Properties window.

The following instructions create an asset and a minimal state so you can try out the code.

1. Start with an asset you want to add a state to. To simplify the example, let’s start by using an OBJ asset.

   Note

   If you just want to start with a blank asset, you can follow these steps¹ to create a SOP asset or these steps² for an OBJ asset. The viewer state created with the code generator should work for both asset types.

   1

   To quickly create a “blank” SOP asset to experiment with:

   1. At the Object level, use the ⇥ Tab menu to create a Geo object.

   2. Double-click the geo1 node to dive into the Geometry network inside.

   3. Use the ⇥ Tab menu to create a Subnetwork node.

   4. Right-click the subnet1 node and choose Digital Asset → Create New.

   5. Set the Type Name to statedemo, the Asset Label to State Demo, and Library Path to Embedded in .hip File.

      Setting the library location to Embedded saves the asset with the current scene file instead of in an asset library.

   6. Uncheck the Author, Branch and Version check box controls.

   2

   To quickly create a “blank” OBJ asset to experiment with:

   1. At the Object level, use the ⇥ Tab menu to create a Subnetwork node.

   2. Right-click the subnet1 node and choose Digital Asset → Create New.

   3. Set the Type Name to statedemo, the Asset Label to State Demo, and Library Path to Embedded in .hip File.

      Setting the library location to Embedded saves the asset with the current scene file instead of in an asset library.

   4. Uncheck the Author, Branch and Version check box controls.

2. Open the type properties window for the asset. (Right click an instance of the asset type and choose Type properties).

3. Click the Interactive|State Script tab.

4. Click the New… button to generate the state code.

5. Select the onMouseEvent event handler and click Accept.

You should now have a functional state listed in the Viewer State Browser tree as Statedemo.

import hou
import viewerstate.utils as su

class State(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer


    def onMouseEvent(self, kwargs):
        """ Process mouse events
        """
        ui_event = kwargs["ui_event"]
        dev = ui_event.device()
        self.log("Mouse:", dev.mouseX(), dev.mouseY(), dev.isLeftButton())

        # Must return True to consume the event
        return False


def createViewerStateTemplate():
    """ Mandatory entry point to create and return the viewer state 
        template to register. """

    state_typename = kwargs["type"].definition().sections()["DefaultState"].contents()
    state_label = "Statedemo"
    state_cat = hou.objNodeTypeCategory()

    template = hou.ViewerStateTemplate(state_typename, state_label, state_cat)
    template.bindFactory(State)
    template.bindIcon(kwargs["type"].icon())

    return template

See implementing a state below for more information on adding functionality to the state class.

To test the state, select the asset in the network editor. Move the mouse into the scene viewer and press Enter. The mouse coordinates should be logged in the Viewer State Browser console as you move the mouse.

For creating file viewer states, use the code generator in the Viewer State Browser window.

The following instructions create a file viewer state that can be “shared” between multiple assets. File viewer states are automatically registered by Houdini on startup.

1. Open the Viewer State Browser window with the New Pane Tab Type ▸ Viewer State Browser menu.

2. Select the Object category from the toolbar.

3. Open the Viewer State Code Generator with the File ▸ New State… menu.

4. Enter statedemo as the state’s name in the Name field.

5. Select the onMouseEvent event handler and click Accept.

The new file viewer state should be saved as $HOUDINI_USER_PREF_DIR/viewer_states/statedemo.py, listed in the Viewer State Browser tree as Statedemo.

You should now have a functional state listed in the Viewer State Browser tree as Statedemo.

import hou
import viewerstate.utils as su

class State(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer


    def onMouseEvent(self, kwargs):
        """ Process mouse events
        """
        ui_event = kwargs["ui_event"]
        dev = ui_event.device()
        self.log("Mouse:", dev.mouseX(), dev.mouseY(), dev.isLeftButton())

        # Must return True to consume the event
        return False


def createViewerStateTemplate():
    """ Mandatory entry point to create and return the viewer state 
        template to register. """

    state_typename = "statedemo"
    state_label = "Statedemo"
    state_cat = hou.objNodeTypeCategory()

    template = hou.ViewerStateTemplate(state_typename, state_label, state_cat)
    template.bindFactory(State)
    template.bindIcon("MISC_python")

    return template

To test the state, find an asset you want to add a state to, or create a blank SOP asset with these steps³ or these steps⁴ for an OBJ asset. To simplify the example, create an OBJ asset.

1. Open the type properties window for the asset. (Right click an instance of the asset type and choose Type properties).

2. Click the Node tab.

3. Set the Default state field to the state name (for example, in the code above, this is statedemo).

4. At the bottom of the type properties window, click Accept.

   • If the asset was locked, Houdini will prompt you to unlock the asset so you can save your changes.

5. To start testing, select the asset in the network editor. Move the mouse into the scene viewer and press Enter. The mouse coordinates should be logged in the Viewer State Browser console as you move the mouse.

   • The toolbar at the top of the viewer should display the state’s label on the left.

On startup, Houdini will call createViewerStateTemplate to access the state template and perform the registration. If omitted, Houdini will simply skip the state registration.

See implementing a state below for more information on adding functionality to the state class.

Event handlers are called with a single argument, a dictionary containing various useful items. The dictionary will typically (but not always) contain the following items:

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onEnter( self, kwargs):
        kwargs['state_flags']['mouse_drag'] = False
        ...                

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onMouseEvent( self, kwargs):
        kwargs['state_flags']['redraw'] = False
        if __some_redraw_test__:
            kwargs['state_flags']['redraw'] = True
        ...                

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onEnter( self, kwargs):
                            # Disable indirect handle dragging. Handle parms can 
                            # no longer be modified by dragging the MMB in the
                            # viewport.
        kwargs['state_flags']['indirect_handle_drag'] = False
        ...                

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onGenerate( self, kwargs):
        # Set this node-less state to remains active when 
        # a node selection occurs.
        kwargs['state_flags']['exit_on_node_select'] = False
        ...                

The following tables list the event handlers you can define on your state class.

Tracing is a builtin tool that allows you to print debugging information in the browser console window during the execution of a python state. Tracing can be turn on from the browser toolbar, and configured with the Trace Options dialog in the File|Debug menu. The options dialog let you choose the python state handlers you want to trace and the data to print as the handlers get executed.

• The tracing support of the viewer state browser is a useful way of debugging python states without adding a single line of code to your python state.

log is a method on your python state class and is similar to the python print function. Instead of printing to the standard output, it prints messages to the Viewer State Browser console. The methods has a severity argument you can use to print the message with a different background and text color.

• The browser lets you control when to log messages by toggling the Debug log button. This allows you to keep the log method call in your code instead of commenting out when debugging is not required.

• Houdini adds the log method dynamically to the python state after the object was created. log is therefore not yet available when __init__ is called. The workaround is to use viewerstate.utils.log from __init__ for logging messages in the Viewer State Browser console.

import traceback

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onMouseEvent(self, kwargs):
        # Log the mouse position
        ui_event = kwargs["ui_event"]
        device = ui_event.device()
        self.log("Mouse position x=", device.mouseX(), "y=", device.mouseY(), 
            severity=hou.severityType.ImportantMessage)

        # Log the current Python call stack
        self.log(''.join(traceback.format_stack()))

The browser console is Qt base and supports rich text formatting. With the use of HTLM-style tags, self.log can display text with a specific font, font size or color.

msg = "Lorem ipsum dolor sit amet."
self.log("<span style='color:#F0FF00; background:orange; font-size:50px;" \
    "font-family:arial narrow'>{}</span>".format(msg))

# Some characters are rich text sensitive. If you want to display 
# these characters without rich text parsing them, make sure to 
# use their escape forms to disable them.
msg = "<< Lorem ipsum dolor sit amet. >>"
msg = msg.replace("<", "&lt;")
msg = msg.replace(">", "&gt;")
self.log("<font color='#FF00FF'><b><i><u>{}<u/><i/></b><font/>".format(msg))

The utility class viewerstate.utils.DebugAid provides debugging support for viewer states. This utility provides a logging mechanism like self.log and all the debugging features currently available in the viewer state browser as methods:

• Inspect the active viewer state.

• Add markers.

• Enable a debug trace.

• Enable logging console

• Reload the running viewer state.

See also python handle DebugAid.

import traceback
from viewerstate.utils import DebugAid

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer
        self.dbg = DebugAid(self)

    def onEnter(self, kwargs):
        # Inspect the state
        self.dbg.marker()
        # inspect this viewer sate
        self.dbg.inspect()
        # start a trace
        self.dbg.trace()

    def onMouseEvent(self, kwargs):
        # Log the mouse position
        ui_event = kwargs["ui_event"]
        device = ui_event.device()

        self.dbg.marker()
        self.dbg.log("Mouse position x=", device.mouseX(), "y=", device.mouseY())

        # Log the current Python call stack
        self.dbg.log(''.join(traceback.format_stack()))

The most basic but still useful form of debugging is to print information, such as the contents of variables as the script runs.

• The main advantage of using prints is that you can output a lot of information, including multi-line blocks of text (such as the current Python call stack), and scroll back to read it later.

• The python state code needs to be edited in order to add the print outs.

The output appears in a console window, or Houdini’s Python shell window, or the shell you started Houdini from, depending on how you started Houdini and what windows are open.

from __future__ import print
import traceback

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onMouseEvent(self, kwargs):
        # Print the mouse position
        ui_event = kwargs["ui_event"]
        device = ui_event.device()
        print("Mouse position x=", device.mouseX(), "y=", device.mouseY())

        # Print the current Python call stack
        traceback.print_stack()

The hou.SceneViewer.setPromptMessage and hou.SceneViewer.clearPromptMessage functions let you display prompts for user interaction in the status line at the bottom of the main Houdini window. You can “abuse” these functions to display debugging information.

• The advantage of this method is that the information is front-and-center in the window as you interact with Houdini.

• The disadvantage is that the status line can only show one line of information at a time and when you change it the previous message is lost.

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onMouseEvent(self, kwargs):
        # Display the mouse position in the status line
        ui_event = kwargs["ui_event"]
        device = ui_event.device()
        message = "Mouse x=%d y=%d" % (device.mouseX(), device.mouseY())
        self.scene_viewer.setPromptMessage(message)

The hou.ui.displayMessage function pops up a message window and waits for the user to click OK or Cancel.

• This has a few advantages for debugging. One is that it pauses the script while it waits, which may be useful if you're trying to investigate changes that happen very quickly. It also lets you give some feedback to the script based on which button you click. Another is that the function has keyword arguments that let you attach a block of “details” text that is hidden by default but can be expanded. This is useful, for example, for displaying the current Python call stack.

• You probably don’t want to use this function in a loop, where it would be annoying to have to click to dismiss multiple message windows.

import traceback

import hou

class MyState(object):
    def __init__(self, state_name, scene_viewer):
        self.state_name = state_name
        self.scene_viewer = scene_viewer

    def onMouseEvent(self, kwargs):
        ui_event = kwargs["ui_event"]
        device = ui_event.device()
        # Only diplay the message on a click
        if device.isLeftButton():
            message = "Mouse x=%d y=%d" % (device.mouseX(), device.mouseY())

            # Get the call stack at this point in the script and format it
            # in a string so we can attach it to the message as "details"
            details = "".join(traceback.format_stack())

            # Display a message and wait for the user to click a button in
            # the message window
            clicked = hou.ui.displayMessage(
                message, buttons=("OK", "Error"),
                details_label="Current call stack",
                details=details
            )

            # If user clicked the "Error" button, raise an error
            if clicked == 1:
                raise Exception("Don't blame me!")