The tool script can access extra information in a global dictionary variable called kwargs. For example, to check if the user selected the tool in a viewport, use kwargs["viewport"].

Houdini’s shelf uses a convention where clicking a tool with the ⌃ Ctrl key held turns the tool into an immediate action. For example, the Camera tool on the Lights and Cameras shelf tab lets you place a camera in the scene, but ctrl-clicking it immediately creates a camera from the current view, instead of asking you to place the camera. Similarly, ctrl-clicking the Sphere tool on the Create shelf tab immediately places the sphere at the origin instead of asking you to place it.

If you want to use this convention in your own tool, you can use the value of kwargs["ctrlclick"] to see if the user ctrl-clicked your tool.

When Houdini calls your script, it sets a special dictionary variable named kwargs in the script’s context. This dictionary contains useful information. You can see its contents by creating a tool and giving it the following script…

# Convert kwargs to a string and pass it
# to the displayMessage function.

hou.ui.displayMessage(str(kwargs))

shiftclick

altclick

ctrlclick

cmdclick

inputindex

outputnodename

outputindex

inputnodename

branch

toolname

pane

viewport

• While you're debugging a script, you can display alert windows using…

  hou.ui.displayMessage("Hello World")
  

• The default shelf items created when you drag nodes onto the shelf are generated by the code in $HFS/houdini/python2.5libs/defaulttools.py and generally just call xxxtoolutils.genericTool(). You may want to look at these scripts to learn how to write a simple tool script.

• The xxxtoolutils modules in $HFS/houdini/python2.5libs/defaulttools.py contain some useful high-level functions that might make writing tool scripts easier.

• View the scripts of stock items on the shelf, such as the Delete action on the Modify shelf tab, for useful techniques and bits of code.

• To get the scene viewer pane object…

  import toolutils
  
  scene_view = toolutils.sceneViewer()
  

• To get the current viewport in the active viewer:

  active_pane.curViewport()
  

• To get the network location of the scene viewer:

  import toolutils
  
  scene_viewer = toolutils.sceneViewer()
  path = scene_viewer.pwd()
  

You might want to make a tool that works inside two or more different network types. For example, the Delete action on the Modify shelf tab works at both the object level, where it deletes the selected object, and at the geometry level, where it creates a Blast surface node.

There are a few ways you could write this part of your script. One is to follow the code used by the Delete action’s script:

import toolutils

# Find out current context.
# Returns the active pane when the tool/action was called.
# If there is not an active pane when the tool/action is called,
# this returns None.

active_pane = toolutils.activePane(kwargs)

# If the pane is a context viewer, treat it like a scene viewer.

if active_pane is not None and active_pane.type() == hou.paneTabType.ContextViewer:
    active_pane = active_pane.sceneViewer()

# If there is no active pane, or the active pane is not a
# scene viewer, raise an error.

if active_pane is None or active_pane.type() != hou.paneTabType.SceneViewer:
   raise hou.Error("The tool was not invoked in the scene viewer.")

# Get the network context of the viewer.

child_type = active_pane.pwd().childTypeCategory()

if child_type == hou.objNodeTypeCategory():
    ...
elif child_type == hou.sopNodeTypeCategory():
    ...
elif child_type == hou.dopNodeTypeCategory():
    ...
elif child_type == hou.popNodeTypeCategory():
    ...

You can use methods on the scene viewer pane object to get a selection. If the current selection matches the selection type you're asking for, the method will return immediately. Otherwise, it will prompt the user for a new selection.

import toolutils

# The toolutils.selectionPrompt() utility function
# gets the standard prompt string for a given node type.
# For example, this...

prompt = toolutils.selectionPrompt(hou.dopNodeTypeCategory())

# will return something like
# "Select dynamic objects. Press Enter to accept selection."

# The selectXXX methods of the hou.SceneViewer class
# prompt the user for a selection in the viewer.
# The argument is the text of the prompt that appears in
# the status line.

# The result is usually a tuple of nodes, but the
# selectGeometry() method returns a GeometrySelection object.

scene_viewer = toolutils.sceneViewer()
selected_objects = scene_viewer.selectObjects(prompt)

The hou.SceneViewer.selectObjects() method has an optional allowed_types keyword argument that lets you supply a list of object type names. If you supply this argument, the method will only accept selections of these types, and during interactive selection the user won’t be able to select objects that aren’t of the allowed type(s).

The list of allowed types uses the internal names of nodes. To see a node type’s internal name, right-click an instance of the node type in the network editor and choose Type properties. At the top of the window the internal name is listed after Operator type:.

For example, to ask for a camera selection…

# Note: internal name of the Camera object is "cam"

selected_objects = scene_viewer.selectObjects("Select a camera and press Enter",
                                              allowed_types = ["cam"])

To ask the user for a location, as when you place new geometry using the tools on the Create shelf tab:

import toolutils

# The selectPositions() method of the hou.SceneViewer object lets
# you prompt the user for one or more positions (using the
# number_of_positions keyword), optionally connecting multiple
# positions (for example when prompting for a path), displaying
# a bounding box (when prompting to place geometry), etc.

# The result is a tuple of Vector3 objects.

scene_viewer = toolutils.sceneViewer()
positions = scene_viewer.selectPositions(prompt='Click to specify a position',
                                         number_of_positions = 1,
                                         connect_positions = True,
                                         show_coordinates = True,
                                         bbox = BoundingBox(),
                                         position_type = positionType.WorldSpace,
                                         icon = None,
                                         label = None)

See the help for hou.SceneViewer.selectPositions(), BoundingBox, and positionType.

To get the current viewport…

import toolutils

# Get the scene viewer
scene_view = toolutils.sceneViewer()

# Get the current viewport
viewport = scene_view.curViewport()

Calling the settings() method on the GeometryViewport object returns a GeometryViewportSettings object. This object has a ton of methods for getting and setting information about the viewport.

# Get the viewport's settings object
settings = viewport.settings()

Among the most useful methods on the settings object are viewTransform() and setViewTransform(), which get and set the viewport’s transformation matrix respectively. You can

To set the viewport to look through a camera, use…

viewport.setCamera(camera_node)

To get the camera node that a viewport is currently looking through…

# Returns None if not looking through a camera
viewport.settings().camera()

There’s a special method on viewports to copy their view to a camera or light, so you can copy the ctrl-click behavior of the standard tools on the Lights and Cameras shelf tab…

viewport.saveViewToCamera(cam_or_light_object)

• To modify the current selection, first get the selection as shown above. If the user already has an appropriate selection, you’ll get that, or Houdini will prompt her for a selection.

• If you want to make an item that always modifies the same node, instead of the currently selected one (for example, a button that toggles the Activate parameter on an important node), just use the standard function to get a node by name…

  my_cam = hou.node("/obj/cam1")
  

To modify a node’s parameters…

# Get a list of all parameters on a node
all_parms = my_cam.parms()

# Get the current value of a parameter
current_lookat = my_cam.parm("lookat").get()

# Set the value of a parameter
my_cam.parm("lookat").set("/obj/torus1")