• Python handles can only be implemented in Python module files, they cannot be implemented yet in a Houdini digital asset.

To load a Python handle in Houdini you need to a registration function. The preferred way to create such function is to use the Python handle code generator from the Viewer Handle Browser. You can still create the code by yourself from scratch though, but the code generator will let you get your Python handle up and running in no time with no syntax errors.

The following instructions create a file Python handle that can be used by multiple Python states. The new Python handle file will be automatically registered by Houdini on startup.

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

2. Select the Sop category from the list menu in the browser toolbar.

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

4. Enter handle_demo as the handle’s name in the Name field.

5. Select the gadget sample option and click Accept.

The new Python handle file should be saved as $HOUDINI_USER_PREF_DIR/viewer_handlers/handle_demo.py and listed in the Viewer Handle Browser tree as Handle demo.

import hou
import resourceutils as ru
import viewerhandle.utils as hu
import viewerstate.utils as su

#Usage: Simple handle that does nothing but draws a handle gadget.

GADGET_PIVOT = "pivot"
SCALE = 250.0

class Handle(object):

    def __init__(self, **kwargs):
        self.__dict__.update(kwargs)        

        # Utility class to support handle transform operations.
        self.xform_aid = hu.TransformAid(self,kwargs)

        # Here we store the gadget as a class attribute. This is 
        # optional though as gadgets are always available through the 
        # self.handle_gadgets attribute.
        color_options = ru.ColorOptions(self.scene_viewer)
        self.pivot = self.handle_gadgets[GADGET_PIVOT]
        self.pivot.setParams({"draw_color":color_options.colorFromName("HandlePivotColor")})

        # Assign a box geometry to the pivot gadget        
        sops = hou.sopNodeTypeCategory()
        verb = sops.nodeVerb("box")
        verb.setParms({"type":1, "scale":0.1, "divrate":(2,2,2)})
        pivot = hou.Geometry()
        verb.execute(pivot, [])
        self.pivot.setGeometry(pivot)
        self.pivot.show(True)

    def onDraw( self, kwargs ):        
        draw_handle = kwargs["draw_handle"]

        # draw the pivot gadget
        self.pivot.draw(draw_handle)

    def onDrawSetup(self, kwargs):
        """ Called prior to perform drawing, picking or locate operations. 
        """    

        # Scale the pivot gadget with a scale factor independent from the 
        # camera position.
        origin = hou.Vector3()
        scale = self.handle_context.scaleFactor(origin)*SCALE
        scales = [scale]*3

        xform = self.xform_aid.updateTransform(s=scales)
        self.pivot.setTransform(xform)

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

    handle_type = "handle_demo"
    handle_label = "Handle demo"
    handle_cat = [hou.sopNodeTypeCategory()]

    template = hou.ViewerHandleTemplate(handle_type, handle_label, handle_cat)
    template.bindFactory(Handle)
    template.bindIcon("MISC_python")

    # Bind the drawable gadget to the handle.
    # Gadgets are basically geometry drawables used to define the handle 
    # components that can be manipulated interactively in the viewport.
    #
    # The gadgets are used by Houdini to perform common handle operations 
    # such as mouse locating and picking. 
    #
    # Gadget instances are created by Houdini and are made available to 
    # the Handle object via this data member:
    # self.handle_gadgets: dictionary of gadgets keyable by name.
    template.bindGadget( hou.drawableGeometryType.Face, GADGET_PIVOT )

    return template

To test the handle, find a SOP asset with a Python state, or create a blank SOP asset with these steps¹.

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

2. Click the Interactive|Viewer State tab.

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

4. Select the Static Handle sample option and click Accept.

5. In the new state source code, set HANDLE_TYPENAME with "handle_demo" and click Accept.

6. Select the state handle demo node and hit enter in the viewer.

You should now have the Python handle demo activated with the pivot gadget at the origin.

def __init__(self, **kwargs)

The Python class __init__ method is mandatory to initialize the Python handle class. Houdini expects the method to take a kwargs dictionary as argument with the following key entries:

Several handlers are supported to react to Python handle events. All these event handlers are called with a single dictionary argument (kwargs) containing specific values related to the event.

Here are the kwargs entries common to all handlers:

The following tables list all event handlers by category along with specific kwargs entries if any.

Houdini automatically generates items on the undo stack for handle and node parameter changes. However, if custom undo support is needed you can use the hou.undos module and undo methods on hou.SceneViewer to group undoable operations into one single entry on the undo stack. See state undo support for details.

Houdini provides various utility classes to help with the Python handle implementation. Utilities such as ColorOptions and HUD, for example, are designed to be coherant with the Houdini standard, it is strongly suggested to use them. See the Python handle demos for examples how to use them.

• viewerhandle.utils.TransformAid:

  The TransformAid handles transform operations for Python handles. Methods such as updateTransform and toScreen will compensate for the handle’s object transform when the viewport is set to world space.

• viewerhandle.utils.DebugAid:

  A utility class to help debugging Python handles.

• resourceutils.ColorOptions:

  Utility class for accessing the Houdini color options. See gadget drawables for more details.

• resourceutils.DisplayGroup:

  This class allows drawables to be displayed as groups in the viewport. For instance, this can be useful if you want to make a group of handle gadgets visible in a cycling fashion, similar to the Houdini transform modes key Y.

• resourceutils.HUD:

  Utility class for displaying textual information in the viewport in the form of a HUD display.

• resourceutils.CursorLabel:

  Uses this class when you want to display some text label around the cursor. This is pretty handy for Python handles, have a look at the move_tool_demo handle for details how to use this class.

• resourceutils.DebugMenu:

  Used by Houdini for creating a debug menu entry in a Python handle context menu. The Viewer Handle Code Generator actually uses it to create the handle’s context menu.

The utility class viewerhandle.utils.DebugAid provides debug support for Python handles. This utility is convenient for logging messages in the Python handle browser but also provides all the logging features currently available in the browser as methods:

• Inspect the active Python handle.

• Add markers in the console.

• Enable a debug trace.

• Enable logging console

• Reload the running Python handle.

import traceback
from viewerhandle.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 handle
        self.dbg.marker()
        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()))

Reloading Python handle modules from Houdini improves the development cycle. There are several ways to reload a Python handle:

• If your source code is opened with the Houdini Python file editor, hit the Accept button.

• From one of the Viewer Handle Browser menus such as the Reload context menu in the browser tree.

• hou.ui.reloadViewerHandle()

• viewerstate.utils.DebugAid.reload

Another way of adding debugging capabilities to your Python handle is to use a debug context menu. The code generator has an option to generate a debug menu which gives access to the following Viewer Handle Browser debugging features:

• Logging

  Enable or disable console logging. If enabled, messages logged with self.log or with the DebugAid utility are sent to the console.

• Clear

  Clear the logging console.

• Inspect

  Dump the content of the underlying Python handle in the console.

• Trace

  Enable or disable a debug trace. If enabled, a trace of the active Python handle are logged in the console.

• Marker

  Add a marker in the console to discriminate messages.

The code generated will add the debug menu as a sub-menu. If you wish to add the debug menu as a flat menu, you can modify the code in createViewerHandleTemplate like this:

menu = hou.ViewerStateMenu(handle_type + "_menu", handle_label)
...

# Replace this ...
menu.addMenu(hu.createDebugMenu(handle_type))

# ... with this code
hu.addDebugEntriesToMenu(handle_type, menu)

...