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 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 is automatically registered by Houdini at startup. This example is valid for all Python handle contexts; however, some samples provided by the Code Generator may not be available in the COP Python handle context, such as the gadget sample shown below.

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.

The gadget sample generated code:

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.

3D Python handles possess 3D manipulation capabilities and operate within the Scene Viewer. You can define these handles in contexts such as SOP, LOP, and OBJ nodes.

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

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

2D Python handles are designed to operate within the Compositing Viewer and the Scene Viewer.

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. Most of 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:

This table lists all event handlers 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.

  Note

  While TransformAid is primarily designed for 3D Python handles and some of its methods might seem applicable to 2D handles, it is recommended to use drawable2d.Dragger2D for handling 2D-specific operations within 2D Python handles instead.

• 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.

• drawable2d.Dragger2D:

  A utility class for interactive mouse-based manipulation of hou.Drawable2D objects in 2D image space. This is primarily used in COP Python handles or states, where user interaction occurs within a normalized model space ranging from [-1, -1] to [1, 1].

• drawable2d.Drawable2DGroup:

  This class covers the drawable grouping functionality for hou.Drawable2D objects.

• resourceutils.CursorLabel:

  Use this class to display a text label that follows the cursor’s movement. This can be useful for both 2D and 3D Python handles to provide contextual information. Refer to the move_tool_demo and cop_state_drawable_demo handle examples for detailed usage.

• 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 viewer_handle_intro.hip scene gives an introduction to python handle implementation, the scene will guide you through the basic features of python handles.

The move_tool_demo.hip scene provides a much more complete and complex implementation example of a python handle for translating/rotating/scaling a geometry.

The cop_viewer_handle_demo.hip scene offers an introduction to creating Python handles specifically for COPs. By exploring this example, you will learn the fundamental features and implementation techniques for COP Python handles.

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)

...