These instructions demonstrate how to create a SOP asset for embedding a Python viewer handle.

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 handle_demo, the Asset Label to Handle 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.

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

8. Click the Interactive|Handle Script tab.

9. Click the New… button to generate the handle code.

10. Select the Rotate sample event handler and click Accept.

11. Click the Apply button to register the new handle.

The Handle script editor should display the code for a Python handle capable of rotating a geometry around an axis. The new handle should be listed under the Handle Demo node in the the Viewer Handle Browser tree.

To test the new handle, you need to create a viewer state to bind the handle.

1. Click the Interactive|State Script tab.

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

3. Enter state_rotate_demo as the state’s name in the Name field.

4. Select the Static Handle sample event handler and click Accept.

5. Replace this line

   HANDLE_TYPENAME = "unknown"

   with

   HANDLE_TYPENAME = "handle_demo"

6. Replace this line

   template.bindHandleStatic( HANDLE_TYPENAME, HANDLE_NAME, [] )

   with

   template.bindHandleStatic( HANDLE_TYPENAME, HANDLE_NAME, [("ry","ry")] )

7. Add a float parameter in the asset called ry.

8. Click Accept.

The new state state_rotate_demo should be listed in the Viewer State Browser window. You can see the new handle_demo entry by expanding the state browser’s node.

Now create a box geometry and add this channel ch("../subnet1/ry") to the box’s Rotate Y field.

Select the demo asset node in the network editor. Move the mouse into the scene viewer and press Enter. The handle should be drawn as a green ring, pick and drag the ring to rotate the box.

The following instructions demonstrate how to create a Python handle module that automatically get 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 and click Accept.

A new Python handle file with sample code should be saved as $HOUDINI_USER_PREF_DIR/viewer_handles/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

#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, follow these steps:

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 state handle demo, the Asset Label to State Handle 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.

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

8. Click the Interactive|State Script tab.

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

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

11. In the new state source code, set HANDLE_TYPENAME with “handle_demo” and click Accept.

12. 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. The kwargs dictionary is pre-filled with the following key entries:

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

def onActivate(self, kwargs):
    self.log("Handle parameters", self.handle_parms)

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. For example, utilities such as ColorOptions and hou.SceneViewer.hudInfo 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.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 Handle(object):
    def __init__(self, **kwargs):
        self.__dict__.update(kwargs)
        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

• viewerhandle.utils.DebugAid.reload

• From the Python Handle editor if your handle is embedded in an HDA.

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)

...