20.08.2015 Views

TECHNICAL PAPER Building Tools for Houdini 9

TECHNICAL PAPER Building Tools for Houdini 9 - Digital Cinema Arts

TECHNICAL PAPER Building Tools for Houdini 9 - Digital Cinema Arts

SHOW MORE
SHOW LESS
  • No tags were found...

Create successful ePaper yourself

Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.

<strong>TECHNICAL</strong> <strong>PAPER</strong><strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9


1. Introduction 4Who is this <strong>for</strong>? 4Your Feedback is Important! 42. What are <strong>Tools</strong> and how are they used? 5Characteristics 5Where are <strong>Tools</strong> Found? 5Usage 6Examples Shipping with <strong>Houdini</strong> 63. Anatomy of a Tool 8Python Script 8Shelf Edit Tool Dialog 8Digital Asset Tool Options 9Representations on disk 9Loading Shelves into a .hip File 104. Steps to Develop a Tool 11Exercise 1: Add Scripted Button to the Shelf 11Exercise 2: Add Node to the Shelf using Drag-and-Drop 11Exercise 3: Add Node to the Shelf using Edit Tool… 11Exercise 4: Add Digital Asset to the Shelf and TAB menus 12Exercise 5: Add Tool by Editing .shelf File 125. Designing <strong>Tools</strong> <strong>for</strong> Wider Distribution 13ContentsWrite a Tool Specification 13Tool Description Outline 13Build the Digital Asset 14Operator Type Properties defaults and settings 14Promote Parameters 15Write the Tool Script 16Reference an Icon 18Tool Documentation 18Add Digital Asset to a Shelf 19Versioning 19Test, Test, Test 206. Distribution 21Internal Development using Local Paths 21Windows, $HIP and Local Path development 21Managing Shared Utilities 21Distribution with Local Paths 22Distribution with Explicit Paths 22Path Management with Discrete Environment Variables: 23Digital Assets and OTL’s: HOUDINI_OTL_PATH 23Toolbars and .shelf Files: HOUDINI_TOOLBAR_PATH 23Shaders and VEX <strong>Tools</strong>: HOUDINI_OTL_PATH 232 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Scripts: HOUDINI_SCRIPT_PATH 23Python Modules: HOUDINI_SCRIPT_PATH/python 23HDK dso’s: HOUDINI_DSO_PATH 23Distribution on the Exchange 24Prepare a Shelf Package. 24Upload to the Exchange 24Download from the Exchange 24Manual Installation and System-wide Installation 24Appendix A: Tool specification example 25RBD Simple 25Purpose 25Usage 25Components 26UI Elements 27Resources 27Appendix B: Help Card Format with Wiki Markup 28Node Help Structure 28Shelf item help structure 28Help components: 29Title 29Summary 29@usage 29@parameters 29Use heading 3s to represent parameter tabs. 30Including images 30Referencing other nodes 30Appendix C: The .shelf file <strong>for</strong>mat 31Example 32Semi-Formal XML Syntax Definition: 33Components Description: 34Appendix D: Development Checklist 35Icons and Help 35Context 35Behavior 35UI 35Appendix E: References 36Learning Python 36Creating and Managing Environments: Linux/Unix 36Creating and Managing Environments: Windows 36© Side Effects Software 2007. All rights reserved. Except as provided below, no part of this document may be reproduced in any material<strong>for</strong>m (including photocopying or storing in any medium by electronic means) without the prior written permission of Side Effects Software.Side Effects Software grants permissions to individuals and organizations to make copies of the entire document (including this copyrightnotice) <strong>for</strong> their own internal use. No copies of this document may be published, distributed or made available to third parties whether bypaper, electronic or other means without Side Effects Software’s prior written permission.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 3


1.Introduction<strong>Houdini</strong> Technical Directors have long been able to choose from a number of ways to create tools <strong>for</strong> artists.Scripts, custom nodes via HDK or VEX, and most importantly <strong>Houdini</strong> Digital Assets (HDAs) are all wellestablished means to creating ready-made tools in <strong>Houdini</strong>.With the addition of the Shelf and supporting Python modules to <strong>Houdini</strong> 9 we now have an important extensionto these capabilities. TDs can make use of a unified way of organizing and creating tools, and perhapsmost critically a language to allow interaction with those tools. Whether as part of the <strong>Houdini</strong> distributionor as 3rd-party add-ons the new methods <strong>for</strong> creating tools will enhance the capabilities of the TD to createtools and vastly improve the experience of the artists using them.These <strong>Tools</strong>:▪▪▪▪▪▪▪▪▪▪▪▪Do not require C++ programming, there<strong>for</strong>e a complex development environment is not needed.Utilize <strong>Houdini</strong> python modules to handle common tool behaviors to help minimize scripting.Are fully integrated with <strong>Houdini</strong> and work seamlessly along side the built-in toolsOffer flexible management within any pipeline since there is extensive control over where the toolsare stored on disk.Are easy to learn and use since they support prompted interactive input, extensive help, and requireonly the essential controls to be made visible to the artist.Promote a consistent style of interaction which reduces time spent on some design considerationsand further contributes to a reduced learning curve.Many of the recommendations we make here have been arrived at as a direct result of a pilot project run during<strong>Houdini</strong> 9 Beta in which both SESI and 3rd party contributors implemented a number of FX <strong>Tools</strong>. Thesetools can be found on the Exchange and will serve as illustrations of some of the methods described in thisreference.IntroductionWho is this <strong>for</strong>?This document is aimed at tool developers, whether they are interested in creating tools <strong>for</strong> personal, facilitywideor community use. We expect basic familiarity with▪▪▪▪▪▪<strong>Houdini</strong> 9 UICreating and using <strong>Houdini</strong> Digital Assets (HDAs)Basic Python scriptingTDs who wish only to develop tools <strong>for</strong> their own use will find most of what they need in the first 3 sections(“What are <strong>Tools</strong>?”, “Anatomy of a Tool”, and ending with “Steps to Developing a Tool”). Those who wouldlike to develop <strong>for</strong> a wide audience and are concerned with best practices will benefit from reading the remainderof this document.Your Feedback is Important!This is the first technical paper created by the Side Effects Software Production Consulting team to help youwork with <strong>Houdini</strong>’s more advanced tools. To help us understand how you are using this document, pleasesend your feedback to Senior Production Consultant Judith Crow at judith@sidefx.com .4 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


2.What are <strong>Tools</strong> and how are they used?This document defines tools as items that exist on the Shelf or in the TAB Menus. In their most basic incarnationtools are python scripts that per<strong>for</strong>m actions when a button on the Shelf is pressed or when an item isselected from a TAB Menu in any of the contexts that support them.All operators in <strong>Houdini</strong> are now defined as tools. A tool can per<strong>for</strong>m a function as simple as placing a singlenode or changing a node’s parameters. It can be as complex as placing multiple Digital Assets based onprompted input from the user.Some Examples are:Scripts that...▪▪▪▪▪▪▪▪Place new nodesModify existing nodesModify or create workspacesControl aspects of a pipelineNodes created using...▪▪▪▪▪▪Digital Assets (e.g. the Auto Rig nodes)VEX code (e.g. the Mountain SOP)HDK programmingCharacteristics▪▪▪▪▪▪Every tool has a python wrapper script that defines the way it behaves<strong>Tools</strong> know what context they’ve been invoked from and can adjust their behavior accordingly.<strong>Tools</strong> know what to work on based on selections. Status in<strong>for</strong>mation available to a tool includes:○○ The current operator (furnishes in<strong>for</strong>mation about node type and parenting)○○ A list of the selected nodes, objects, or components○○ The current viewport and desktopWhere are <strong>Tools</strong> Found?While tools can be used from a wide variety of contexts including the Main Menus, RMB Menus, the shell andcmd files, and bound to Hot Keys, we are limiting our scope here to the two main contexts most used by artists,namely the Shelf and TAB MenusOn the ShelfFigure 1 - Each of these icons represents a tool<strong>Houdini</strong> ships with many predefined shelves each of which consists of a set of tools with related functionality.Many of these are “automatic” tools – i.e. their behavior is limited to placing a node. However there are alsogood examples of more complex tools that prompt the user <strong>for</strong> interaction and build node trees. The user canmodify these existing tools or add new ones, as well as reconfiguring the contents of the shelves.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 5


In the TAB MenusFigure 2 - All items in the viewer and network pane TAB menus are defined as tools.Many of them can also be found on the shelf.UsageFor the end user using a tool is simply a matter of selecting the tool by whatever means the context offers andfollowing prompts as they occur.For the developer the tools paradigm offers consistency with <strong>Houdini</strong> methods, a wide variety of options <strong>for</strong>implementation, the flexibility of building bigger systems from smaller tools, and requires minimal scriptingExamples Shipping with <strong>Houdini</strong>Be<strong>for</strong>e delving into writing new tools it is useful to examine more closely some of the tools which ship with<strong>Houdini</strong>.1. Script-only tools such as Delete simply per<strong>for</strong>m an operation on operators already in the scene.2. Single operator tools such as the Polygon tools can be found on shelves and in TAB menus andsimply place and wire a node into a network. This behavior is handled by the Python module soptoolutils.genericTool.Figure 3 - Single operator tool3. Object creation tools such as “box” or “grid” behave differently depending on the ToolOptions setting.Figure 4 - Tool Options MenuIf Create at Object Level is ON then these tools create a new object and place the appropriate SOP6 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


inside it. If Create in Context is ON and the user is at the SOP level then only the SOP will beplaced in the current object. This behavior is handled by soptoolutils.genericTool4. Network creation tools such as the Create Particles (Source from Geometry or Emitter) orRigid Bodies (RBD Object) tools may create multiple objects and networks and merge together theresults. These have more complex scripts and go beyond the generic tools behavior.Figure 5 -Network creation tool5. Modifier keys may be used with shelf tools to alter tool behavior. For example, the “Create”tools when used without a modifier key allow interactive placement in the viewport. Howeverselection with the CTRL key while invoking the tool from either the Shelf or the viewport Tab menuwill immediately place the geometry at (0,0,0). Cameras and Lights on the other hand have theirtrans<strong>for</strong>ms set to the current view if the CTRL modifier is used. The SHIFT and ALT keys are alsoavailable as modifiers but are not currently used by the default shelf tools6. Digital Asset creation tools such as found in the Auto Rigs shelf place Digital Assets in thenetwork. It is possible in these cases <strong>for</strong> the tool definition to be contained in the asset itself. Moreon this later.Figure 6 -Digital Asset creation toolsContext and selection sensitive behavior7. can be found in a number of shelf tools, such as theDelete tool. Use the Delete tool in the object context and the selected object(s) and all of its geometrywill be removed from the scene. Use it at the geometry level and a Blast SOP will be insertedinto the network after the current SOP to remove only the selected points or primitives.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 7


3.Anatomy of a ToolPython ScriptAll tools must have a Python script that defines an action such as placing a node or changing parameters onan existing node. <strong>Houdini</strong> provides a large number of Python modules in $HFS/scripts/python which will beexamined in more detail later.There are two places to define a tool interactively. The first is a Shelf Dialog, the second is as a part of anDigital Asset Op Type Properties Dialog. The dialogs themselves are almost identical, so let’s look at theShelf <strong>for</strong> an example.Shelf Edit Tool DialogChoose a Shelf Tool to examine – say “Box” from the Create Shelf.RMB on the tool icon and “Edit Tool…” to see the following dialog:The tool must have▪▪▪▪▪▪▪▪Figure 7 - Fig. 7 – Edit Tool DialogA location on Disk (Save To)A nameA labelA script (or it will do nothing and not show up in the interface)All other settings are optional, but important <strong>for</strong> good tool behavior. Let’s look at them one-by-one.Options:▪ ▪ Save To location is the name of the shelf file containing the tool.. All shelf files should be savedwithin the $HOUDINI_PATH in a toolbar folder or somewhere in the $HOUDINI_TOOLBAR_PATHif it is defined. All shelf files have to have a .shelf extension. Shelves that are not part of the <strong>Houdini</strong>distribution will typically be saved in $HOME/houdini9.0/toolbar8 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


▪ ▪ Name is the internal name of the tool and should contain no spaces▪ ▪ Label is the name which will be visible on the Shelf or in the TAB Menus▪ ▪ Icon can be chosen from the distribution or you can create your own [see Icon section]Script:This is where the tool behavior is defined.Script Language defaults to Python. Although Hscript can be used it does not offer any of the advantagesof Python in that it is not selection/context aware. We discourage using Hscript <strong>for</strong> writing toolsHelp:Help can either be entered directly here using the wiki markup language (see Appendix B <strong>for</strong> more details) orthe Help URL box can be checked to use Help saved elsewhere in your path. This is the Help that shows upwhen the F1 key is pressed over the tool icon.Context:The tool visibility is defined here.For both the Network Pane and the Viewer Pane you can select which TAB Menus it should appear in, aswell as specifying one or more TAB Submenu Paths in which it will be located. If the TAB Submenu Path currentlydoesn’t exist in the specified context, the tool will automatically create the Submenu and add itself to it.Hotkeys:Hotkeys can be bound <strong>for</strong> any of up to 4 different contexts. Refer to the Hotkey Manager to avoid any possibleconflicts with existing hotkeys.Digital Asset Tool OptionsDigital Assets can now contain the components necessary <strong>for</strong> defining a tool and thereby bootstrappingthemselves onto the Shelf and into the appropriate TAB Submenus. This makes sharing and distributingDigital Assets that are designed to be used from a Shelf much easier as everything required <strong>for</strong> their use canbe contained in a single file. It is preferable to specify the tool behavior in the asset itself so it can be addedto any shelf and TAB Submenu with ease. The Type Properties…/<strong>Tools</strong> section replicates the options foundin the Edit Tool Dialog described above. Note the local variables that are available <strong>for</strong> standardizing namesand labels. These will be discussed in more detail later.Figure 8 - OP Type Properties DialogRepresentations on diskFiles with the extension .shelf are ASCII xml descriptions of the tools found on the shelf and are createdautomatically by applying changes via the Edit <strong>Tools</strong> Dialog. Although they can be edited by hand it must bedone with care, and only while the Shelf is not loaded. See Appendix C <strong>for</strong> more detail on the <strong>for</strong>mat.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 9


Loading Shelves into a .hip FileShelves found in the <strong>Houdini</strong> path can be displayed by going to the (+) Menu in any Shelf Set and selectingfrom the Shelf MenuFigure 9 - Shelves in <strong>Houdini</strong> pathAnother method is to install shelves from the Side Effects Exchange site (www.sidefx.com/exchange) or otherexchange file server. From the (+) Menu choose Download Shelf… and select the package you’d like toinstall. This will place the .shelf file and any related Digital Assets or supporting files into the $HOME/houdini9.0/toolbardirectory, or any other directory of your choosing.Figure 10 -Downloading a shelf10 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


4.Steps to Develop a ToolIn this section we’ll work through some simple tool creation examples:▪▪▪▪▪▪▪▪▪▪add scripted button to shelf (Hello World)add node to shelf via Drag-n-Dropadd node to shelf via Edit Tool…add Digital Asset to shelf and TAB menusadd Digital Asset via editing .shelf fileExercise 1: Add Scripted Button to the ShelfFirst, create a new Shelf on which to place the new tools.1.In any Shelf Set choose (+) -> New Shelf.2. Save To $HOME/houdini9.0/toolbar/test.shelf with the name test and the label Test.3. RMB on the Test Shelf and choose New Tool.4. Make sure Save To is set to your test.shelf path.5. Name the tool hello_world and Label it Hello World.6.In the Script Folder enter:hou.ui.displayMessage(“Hello World”)7. Choose Accept.8.Select the Test tool and the Hello World message dialog should appear.Exercise 2: Add Node to the Shelf using Drag-and-Drop1.2.3.4.5.Add any node or subnetwork of nodes to a network pane.Select the node you wish to include in your tool. Multiple nodes should be put into a subnetwork.Drag the selected node, object or subnetwork onto the Test Shelf.The cursor changes to solid black with a trailing white rectangle.The tool is added to the shelf using the icon of the current node.Exercise 3: Add Node to the Shelf using Edit Tool…1. RMB on Test Shelf and choose Edit Shelf…2.Go to the <strong>Tools</strong> Folder and scroll down to the Add tool.3. Select the Add tool named sop_add and Accept.4.Note:Select the Add tool and follow the prompts to place in the viewport.The object and SOP were both created in the network as a result of this action5. RMB on Add and choose Edit Tool…Note:Note:The Script automatically imported the python module and passed the name of the tool to thegenericTool function.In the Context Folder, the contexts have been set such that TAB Menus will only show this tool inthe SOP context with further filtering into the Polygon Submenu Path.6. Change the Submenu Path to read Polygon, Points7.Note:Test out the TAB Menu behavior in both the viewport and network panesthe new “Points” submenu path with the Add entry.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 11


Exercise 4: Add Digital Asset to the Shelf and TAB menus1.2.3.Note:Install the Digital Asset to your hip file that you’d like to add to the shelf. For the sake of this exerciselet’s assume you have an asset named object_test.As <strong>for</strong> Exercise 3, select your asset in the <strong>Tools</strong> list and Accept.Select your tool from the shelf and observe what happens.If there is no current selection no nodes will be place in any networks.4. RMB on Test to Edit Tool… and Edit with an HDA Editor5.6.7.Because this is an asset you will not be modifying the shelf file, but will instead be modifying theasset itself.Go to the <strong>Tools</strong> Folder and notice a number of things:○○ The Name and Label have been filled in automatically based on the asset type.○○ The Script imports the appropriate utils module, also based on the asset type and calls thegenericTool function.○○ The Context uses the local variables $HDA_TABLE and $HDA_NAME to make an in<strong>for</strong>medguess as to which contexts you’d like this to work in.○○ The TAB Submenu Path initializes with a Digital Assets entry.You could at this point add some additional Python scripting to prompt the user or give other feedback.You could also add Help that would be visible in the Shelf. We go into more detail on how todo this in the next section.Cancel out of the Op Type Properties Editor.Exercise 5: Add Tool by Editing .shelf File1.2.Exit from <strong>Houdini</strong>.Open $HOME/houdini9.0/toolbars/test.shelf with your favorite text editor (preferably one withindentation and syntax color coding).3.4.5.6.Figure 11 - .shelf file exampleTo add an existing <strong>Houdini</strong> Tool to this shelf you just need to insert a new memberTool in the block between lines 8 and 12.To add a Digital Asset do as <strong>for</strong> an existing <strong>Houdini</strong> tool, but remember the asset must be in the pathor it will show as Undefined when you open your hip file.To add a new button-push script tool add the memberTool name and then define the script itself in a section similar to the “hello_world” exampleSave the new shelf file and open <strong>Houdini</strong> to see the results.12 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


5.Designing <strong>Tools</strong> <strong>for</strong> Wider DistributionIn the course of developing the FX <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 we have come up with a number of recommendationsto enhance the development, distribution and user experience. This section will concern itself with DigitalAsset <strong>Tools</strong> in particular.Write a Tool SpecificationFor all but the simplest tools it’s a good idea to write a tool specification be<strong>for</strong>e starting development. At thevery least the Purpose and Usage need to be clearly understood. For anything complex you may wish to usethe following <strong>for</strong>mat as a template. See Appendix A <strong>for</strong> a fleshed-out example taken from the FX <strong>Tools</strong> project.Tool Description OutlinePurposeWhat problem is the tool designed to solve?UsageA brief description of how the tool will be used in the various contexts, including any special use of modifierkeys. What kind of controls will the user be offered to modify the initial state?ComponentsTool ScriptsOptionsName: rbd_simpleLabel: RBD: SimpleTool Shelf BehaviourDetailed description of what happens when the tool is invoked from the shelf. What will the userbe prompted to do? How will exceptions be handled?Tab Menu Behaviour: Viewer PaneDetailed description of what happens when the tool is invoked from the Viewer TAB Menu.Tab Menu Behaviour: Network PaneDetailed description of what happens when the tool is invoked from the Network TAB Menu.Asset ScriptsAny OnCreated or other custom scripts that will have to be writtenAsset(s)A list of all the assets needed to create the toolMaterial(s)Any custom Materials to be included with the toolSourced DataAny data integral to the tool (such as default objects, images)Generated DataUI ElementsAny data that will be written to disk as part of the tool use<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 13


Icon<strong>Houdini</strong> library or custom?HandlesHandles to be provided <strong>for</strong> the userToolBoxParameters to be exposed in the viewport tool boxLike <strong>Tools</strong>ResourcesAny existing tools with similar functionality that might provide a good usage model or starting pointReferencesSources to aid development e.g. images, papersBuild the Digital AssetDevelop the underlying networks as you would <strong>for</strong> any asset. We will not cover this process here – refer tothe online Help and Tutorials as necessary.Create Digital Asset and pay attention to how the asset is named. We suggest following nomenclature:Digital Asset name: <strong>for</strong>mat will be lower case with underscores in place of spaceseg: rbd_simpleDigital Asset label: <strong>for</strong>mat will be capitalized version of “name” with spaces allowedeg: RBD Simpleotl file: will prefix the “name” with “category”eg: FX_rbd_simple.otlOperator Type Properties defaults and settingsThe Edit Operator Type Properties dialog contains many settings that need to be managed. Here wediscuss a few of the most important.Basic Folder1.2.The Hide default Parameters option is usually checked on <strong>for</strong> object level assets. This hides the toplevel subnet Trans<strong>for</strong>m and Subnet folders. If the top level Trans<strong>for</strong>ms need to be accessed you caneither uncheck this option or create new parameters that are referenced in to the hidden defaultparameters.Turn off Save Defaults as initial Parameters if you wish to capture the state of any and all parametersand folder settings in the asset interface. Otherwise leave it on to <strong>for</strong>ce the parameter defaults to beused when the asset is placed. When off, you can change the top level parameters to values off theirdefaults plus switch to different folder views and have that captured as the initial state when the toolis placed.As an example, if you want your tool to always show a particular folder other than the first top levelfolder and change some default values in the parameters when initially placed in the scene, simplyturn this option off and configure the parameters and folders <strong>for</strong> the current edited asset appropriatelythen press Apply or Accept. The next time the asset is placed in a scene, the captured folderand parameters will be reproduced.14 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Parameters Folder3.The Gear Menu allows you to set a number of useful preferences. Generally speaking it will savetime in naming and labeling parameters if Prefix Linked Parameter Name with Source NodeName and Prefix Linked Parameter Label with Source Node Label are OFF. Remember tofollow this action with Save Options as Default.Figure 12 -Gear Menu options4.The Linked Channels fields <strong>for</strong> parameters in the Parameters/Channels folder should be used tomanage the channel references. You can enter any number of internal channel references as a spacedelimited string of paths to the appropriate target parameters. Only straight channel references aresupported. It is recommended that you use the Linked Channel strings as a way of ensuring straightchannel references. If the target parameters have a complex expression that contains a ch(), chs()or any other type of channel reference to the top level asset parameter interface, then this referencewill not show up in the Linked Channels field and can be safely ignored.Use the arrow menu to the right of the Linked Channels field to manage this field. To update any internalchannel references, choose the option “Reset current links <strong>for</strong> this channel” or “Reset currentlinks <strong>for</strong> all channels“ to update all the channels represented by the selected parameter(s).Disable the Linked Channels reference when you are finding that channel references are unexpectedlydisappearing due to workflow issues.5. In Parameters/Import you can automatically import folders from operators one level below to toplevel Asset Folders by enabling the Save import in<strong>for</strong>mation option. To fetch a folder labeled Setupfrom a contained object called my_embedded_obj do the following: set the Source field to my_embedded_obj:Setupand the Token to folder_name:Setup where folder_name is the Name field string<strong>for</strong> the folder labeled Setup on the target object. Additionally you can use the Mask field along withwild cards to only import subsets of channels from the referenced folder.Promote ParametersThere are no hard-written rules on how to organize or name an asset’s parameters and components. Howeverwe would like to encourage a consistent approach so the user can carry as much learned experience as possiblefrom using one asset to the next.For the FX <strong>Tools</strong> we organized parameters according to workflow and frequency of use.▪▪Folders (left to right) deal with Setup, Behavior (from gross animation parameters through tweaking),Look (Render) and Display (Viewport options)<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 15


▪▪▪▪▪▪Oft-used operations (such as caching to disk) are at the root folder levelFrequently changed parameters in a Folder are at the topParameters often found together (such noise controls) should stay together and be named as expectedFigure 13 - Smoke: Heavy parameter interfaceWrite the Tool ScriptOnce the Digital Asset functions as expected from the TAB Menu, it can be turned into a tool.The first thing you should do be<strong>for</strong>e you write a script is make sure that you really need to write a script. Theautomatic tools are generated by the defaulttools.py module (found in $SHS/scripts/python), and generallyjust call xoptoolutils.genericTool(). Each optype has its own toolutils module with a genericTool function. Evenif the tool you are writing is not really an optype-tool (i.e. it’s primary purpose is not to just lay down a newnode), you may not have to write as much code as you think. Get familiar with the toolutils module, and thexoptoolutils modules appropriate to the tool you are writing. There are lots of handy convenience methods, orat least sample code to get you started.Common things to do include:▪▪▪▪▪▪▪▪▪▪Detect contextDetect selectionsPrompt the user <strong>for</strong> inputGrab the viewport position and write to custom translate parametersCTRL-click Shelf to immediately add tool to sceneDetecting Context to determine what <strong>for</strong>m the tool should take is important when your tool can be usedeither at the Object, SOP or any other level. . The assumption is that the current selection drives the viewportcontext. If we know what context the viewer is in, we know our selection type.There are a few ways to write this part of your script. The most common is to follow the <strong>for</strong>mat as used in theDelete tool on the shelf:0001 import toolutils0002 # find out curr context16 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


0003 active_pane = toolutils.activePane(kwargs)0004 if active_pane is not None and \0005 active_pane.type() == hou.paneTabType.ContextViewer:0006 active_pane = active_pane.sceneViewer()0007 if active_pane is None or \0008 active_pane.type() != hou.paneTabType.SceneViewer:0009 raise hou.Error(“The tool was not invoked in the \0010 scene viewer.”)Line 3 uses toolutils.activePane(kwargs) to return whether or not a viewer pane is currently openwhen the tool was pressed.Lines 4 to 6 check to see if a viewer is actually open and available then finds out what context theviewer pane is in. This is what does the actual work. After this it is common to match the viewporttype with a known context to do a specific type of action. The Delete tool is a very good example ofexecuting different actions depending on what context the viewport is in.Lines 7 to 10 throw an error if there was no scene viewer detected making interactive placement ofthe tool impossible.Detecting Selections to use with your asset is a common tool task. Following from the python code abovein the Delete tool, the following lines take the current view type and pull out exactly what is the current nodetype that you have selected.0011 # we determine what selection type we should consider 0011 # (ie, OBJ, SOP,DOP,POP) based on the viewer network 0013 # path and the child type0015 scene_viewer = active_pane0016 child_type = scene_viewer.pwd().childTypeCategory()Line 16 uses the function childTypeCategory() to return the type of the current selection in the givenviewport given the path to that node: scene_viewer.pwd().The variable child_type now contains the type of the current selected node.The Delete tool then takes that type and compares it to an Object type, a SOP type, a DOP type and then aPOP type. For the Object context type match, the following line is used:0018 if child_type == hou.objNodeTypeCategory():....If child_type is of a type object, then that block of code. The function objNodeTypeCategory() simply returns astring representing an object type. Similar tests are done <strong>for</strong> the other possible types.Prompting the user <strong>for</strong> input is provided as a default when using any of the filter tool functions. The mostcommon filter tool is genericObjNodeFilterTool with the function interface:def genericObjNodeFilterTool(scriptargs, nodetypename,nodename, prompt = None):Using this function as is and not overriding the optional prompt field will result in the default prompt “Selectone or more objects, then press Enter to continue. Middle mouse to select. Left mouse to select and drag.”To create your own custom prompts you simply need to add an optional argument to one of the filter tools likethis:objecttoolutils.genericObjNodeFilterTool(kwargs,‘$HDA_NAME’, ‘$HDA_NAME’,‘Select the object to work on and Enter to complete’)To grab the viewport position and write to a custom parameter, you need to add an additionalparameter to the genericObjNodeGeneratorTool function. By default, the position is returned to the added objectsown tx, ty and tz channels. When working with assets with hidden default subnet parameters, the targetparameter t[xyz] is hidden and so will the resultant values. This is not recommended. Use the option in the<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 17


Help<strong>Houdini</strong> supports two types of asset help: help <strong>for</strong> nodes, and help <strong>for</strong> shelf items. A shelf item can have helpindependent of any node, or it can point to a node as the source of its help.Assets and shelf items can contain their own help text inside them, or they can point to locations in the onlinehelp. If you maintain a centralized server <strong>for</strong> <strong>Houdini</strong> Help it is preferable to put your tool help in that samelocation and point to it from inside the tool. For distribution outside the facility it is safer to embed the help inthe tool definition.Either way it is useful to develop the Help inside the tool definition so that it can easily be tested. You canalways remove it to an external reference later. The two locations are:▪▪▪▪Node Help (in OpTypeProperties/HelpShelf Help (in OpTypeProperties/<strong>Tools</strong>/Help) This is the tool tip Help that will be visible when mousingover or pressing F1 over the icon on the shelfSee Appendix B <strong>for</strong> structure and <strong>for</strong>matting detailsTool TipsTool tips should be entered <strong>for</strong> each parameter via the Operator Type Properties Editor and be as descriptiveas possible. This is done via the Help field in the Parameters Folder.Add Digital Asset to a Shelf1.Create a new Shelf, or select an existing shelf where the tool is to be added.2. RMB New Tool > Select from list of operators – note the label will begin with the type e.g. object_rbd_simpleNote:Versioningthe asset must be in the OTL path if the tool is to be defined next time <strong>Houdini</strong> is started.Versioning is an important part of tool management. We will only focus on versioning the tool itself and notestablishing and maintaining a control version environment with subversion, cvs, rcs or equivalent managementsoftware.Maintaining a Change LogIt is a good idea to maintain a text file or a document containing any changes made to the tool. A simplespreadsheet or table <strong>for</strong>mat is best. Google Docs spreadsheet was used to share the change logs on each ofthe tools amongst the team.The columns <strong>for</strong> each tool can be:▪▪▪▪▪▪▪▪Developer, Date | Tool Version | <strong>Houdini</strong> Version | DescriptionBe<strong>for</strong>e changes are done to a tool, the version is bumped using hscript or Python (see below).Each time work is done on the tool, a row is added with the appropriate in<strong>for</strong>mation.When enough changes are done to accommodate feedback from testing the tool is released.Subsequent changes require a version bump.An alternative method is to create a section inside the asset to document the changes so that there is always arecord of the changes distributed with the asset.Versioning of AssetsThe FX <strong>Tools</strong> are currently all Digital Assets. This makes the process straight<strong>for</strong>ward as Digital Assets supportversioning. Setting the version of a Digital Asset is done through the hscript command otversion and the<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 19


equivalent Python commands hou.NodeType.setVersion or hou.NodeType.version. The version string can beany ASCII text string supplied by the user.The FX <strong>Tools</strong> use a simple incrementing integer number as the version <strong>for</strong> now.To query the version of a digital asset using hscript, you first need to add the Digital Asset to your scene.Then run otversion passing in the path to the node as the first argument to the command. e.g.:/ -> otversion /obj/my_digital_asset015To edit the version of a digital asset using hscript, you first need to add the Digital Asset to your scene. Thenrun otversion passing in the path to the node along with the string that you want to set the version to thenunlock the asset, open the Edit OperatorType Properties and press accept or RMB on the unlocked asset andchoose the option Save Operator Type./ -> otversion /obj/my_digital_asset 016016Then unlock /obj/my_digital_asset and RMB > Save Operator Type to write changes.Test, Test, TestTry to have users with a range of experience levels test your tool be<strong>for</strong>e distribution. Remember to test in allpossible contexts and in both Master and Escape (if your tool is designed to work in both)1.2.3.Test from the ShelfCheck any use of modifier keysTest in the ViewportCheck prompts and selections work as expectedTest in the Network paneSee that the tool is available only in the desired contexts.Check the tool places in the network as expectedSee Appendix D <strong>for</strong> a Development Checklist to help guide you in your testing20 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


6.DistributionInternal Development using Local PathsWhen creating and developing tools it is advised that you work locally using local paths and a passive approachto managing your environment. This passive approach augments, and in most cases, will supersedeany facility environments. Once the tools reach a point where they can be tested, then you should move toa more explicit path approach <strong>for</strong> the testers. This can be a variant on the passive Local Path approach or aproper Explicit Path set up covered below.This local path approach is sensitive to where you launch <strong>Houdini</strong> whether it is from a shell directory or openingan existing hip file. The main factor is to have all the files and sub-directories under development locatedin the same directory as $HIP. $HIP is a permanent <strong>Houdini</strong> variable that is automatically set to the currentworking directory where you have opened and last saved the .hip session file. Working inside $HIP is critical<strong>for</strong> the passive Local Path development approach.Windows, $HIP and Local Path developmentOn windows, setting $HIP to the local directory is not as straight<strong>for</strong>ward as using a shell as with cygwin onWindows or any Linux shell. By placing an empty .hip file in the root local path directory, it is a simple matterof double clicking on that .hip file to launch <strong>Houdini</strong> and set $HIP correctly.When working on the FX <strong>Tools</strong> project, such an empty .hip file was placed in the root development directoriesand was called start_file.hipLinux users simply have to cd (change directory) to the development directory and launch <strong>Houdini</strong> at thecommand prompt to properly set $HIP and set the passive Local Path environment up.A typical local working path directory will look like this:$HIP/backup/dso/houdini/otls/scripts/toolbarstart_file.hipmy_hda.otl/python> .hip backup files> .ds or .dll files> <strong>Houdini</strong> directory> otl in development> .cmd hscript files> .py Python Scripts> .shelf files> Windows start fileThe python directory above is used to hold any helper scripts. It is advisable to have any python modules andfunctions contained inside the digital asset. One such script may be a versioning script or scripts responsible<strong>for</strong> asset management.Managing Shared UtilitiesIf you have any dependencies to custom assets, scripts or other components, you have two choices: Managethe development environment beyond $HIP or duplicate these files and place them within the $HIP developmentenvironment.The simple approach would be to copy the various externally referenced assets locally. You will have to dothat anyway when releasing your tools to the world.If the dependent externally referenced files are site wide and available to the other potential users of yourtools, then you can freely use them within your tools and expect these references to be resolved properly. See<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 21


the section Distribution with Explicit Paths below to set the appropriate environments up.If you plan on releasing these to a wider audience (Side Effects Exchange), then you will need to duplicatethem and place these external dependent files within your $HIP environment in the proper sub-directories.The FX <strong>Tools</strong> are an example of this approach. When you install the tools from the shelf exchange installer,shared .otl files are also included in the package and are installed along side the tool Digital Assets.Distribution with Local PathsThere are two methods to distribute your tool(s): Using the passive Local Path approach used <strong>for</strong> internal developmentset up on the tester machines or a more <strong>for</strong>mal Explicit Path approach described below. The LocalPath approach of distribution is recommended <strong>for</strong> testing purposes and <strong>for</strong> project specific cases. It is a fairlyloose way of working and encourages experimentation and development. For wider distribution and usagewithin a facility, managing your <strong>Houdini</strong> environments with Explicit Paths is mandatory. This method offers agreat deal of control and encourages proper versioning and release strategies to a wider audience.This method of distribution duplicates the same approach as the Internal Development process above. Youwill create local job directories and use the $HIP approach and all the appropriate sub-folders and files.There is much duplication of the tools. This has pros and cons. The pros is that you have local copies of yourassets and any global changes are not directly inherited. Manually copying in later versions of files and toolsis the way that versioning and upgrades are managed. Very secure. The downside is that you do not immediatelyinherit changes. Consider this a manual version control system.Distribution with Explicit PathsOnce tools have been developed and tested from $HOME/houdini9.0/toolbar they can be made accessiblefacility wide via the $HOUDINI_TOOLBAR_PATH, $HOUDINI_OTL_PATH and other environment variables.This method is used where you want the tools to be accessed site-wide or project wide. It allows users toinstantly inherit changes made to the tools.This method allows you to store the various files in very specific locations in the facility. This usually requiresworking with shells or setting system or user environment variables (windows). It requires an understandingof creating and managing system environment variables and knowing the various <strong>Houdini</strong> data types and theassociated environment variables to manage them. If you are the tool developer, then understanding the datatypes is assumed. Learning to create and mange environment variables is beyond the scope of this document.See Appendix E <strong>for</strong> references on managing system environments.The common major components of a tool consist of a .shelf file, an .otl file containing the digital asset(s),python scripts, python modules, and any other components. Any referenced images and geometry files shouldbe injected in to the digital assets saved in the .otl files to simplify the distribution and use of the tool(s). Allthe various components have their corresponding environment variables to manage them within the <strong>Houdini</strong>environment.$HOUDINI_PATH can be used as a way to manage tools. You can append the Local Path used <strong>for</strong> developingthe tool or a duplicated version to the $HOUDINI_PATH. This will include the tools in the current environment.If you are using a bash shell, it is done like this:export HOUDINI_PATH=$HOUDINI_PATH:/mnt/tools/my_toolwhere /mnt/tools/my_tool is the path to the root directory containing the tool(s) and all the related data thatyou wish to distribute to the site. This will append the path to the existing $HOUDINI_PATH environment variable.This line can be inserted directly in to the installed <strong>Houdini</strong> houdini_setup file <strong>for</strong> both bash and c-shellusers.Let’s take a look at the more common major parts of a Tool and the environment variables that are used tomanage them within the <strong>Houdini</strong> environment.HOUDINI_PATH environment variable to manage the environment22 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


It is best to not include the development path but to physically copy the development directory and all it’s subcomponentsto a more centralized location and include that in the $HOUDINI_PATH. This allows you to continuedeveloping the tools incrementing the versions as necessary and then bumping versions when required.Path Management with Discrete Environment Variables:Digital Assets and OTL’s: HOUDINI_OTL_PATHAs of <strong>Houdini</strong> 9 the use of OPlibrary files is not recommended to manage .otl files. The new method is toreference .otl files through $HOUDINI_OTL_PATH. Using this environment variable allows you to place the.otl files containing the Digital Assets anywhere on the file system. You do not have to locate these directoriesinside a <strong>for</strong>mal passive houdini sub-directory. This gives you a lot of freedom to put these .otl files anywhereon the file system. This goes <strong>for</strong> any of the subsequent discrete environment variables below.The default location of .otl files within a houdini directory is a local ./otls directory.Toolbars and .shelf Files: HOUDINI_TOOLBAR_PATHAll .shelf files are managed with the environment variable HOUDINI_TOOLBAR_PATH.The default location of .shelf files within a houdini directory is a local ./toolbar directory.Shaders and VEX <strong>Tools</strong>: HOUDINI_OTL_PATHAll shaders and vex files are managed as digital assets contained in .otl library files. See theHOUDINI_OTL_PATH section above to manage these.Scripts: HOUDINI_SCRIPT_PATHAll hscript .cmd scripts are referenced with HOUDINI_SCRIPT_PATH.It is good practice to embed any local scripts inside the Digital Asset either as a section file or in one of themany creation scripts available in the Edit Operator Type Properties editor. Only use external scripts wheremore than one component of your tool(s) use the same script.The default location of .cmd hscript files within a houdini directory is a local /scripts directory.Python Modules: HOUDINI_SCRIPT_PATH/pythonWhen you import a Python module, <strong>Houdini</strong> will look in $HOUDINI_SCRIPT_PATH/python <strong>for</strong> the appropriatemodule. This is a subset of Scripts. You need to explicitly create a local python directory inside thescript path and place all your .py Python modules in there <strong>for</strong> <strong>Houdini</strong> to pick them up.It is good practice to embed any python modules inside the Digital Asset using the Edit Operator Type Propertieseditor. Only use external Python modules where more than one component of your tool(s) use the samemodule functions.The default location of .py Python module files within a houdini directory is a local /scripts/python directory.HDK dso’s: HOUDINI_DSO_PATHAll dso’s are referenced with the environment variable HOUDINI_DSO_PATH.The default location of .so (linux) or .dll (Windows) files within a houdini directory is a local ./dso directory.To get a full listing of the various environment variables and the houdini components that they manage, refer<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 23


to the <strong>Houdini</strong> on-line help.Distribution on the ExchangeShelf <strong>Tools</strong> are simple to package <strong>for</strong> wider distribution via the Exchange.<strong>Tools</strong> can be distributed as a single tool or as one of a set of tools on a shelfPrepare a Shelf Package.The package should consist of at least a .shelf file along with any of the .otls on which it depends. The directorystructure of the package is entirely open and can contain other files such as images, README files, etc.Zip the package contents in preparation <strong>for</strong> uploading to the Exchange. The exception to this is if the packagecontains only a .shelf file, in which case zipping is unnecessary.Upload to the ExchangeLogin to the Exchange and follow instructions to upload the zipped package. Be sure to set the type as Shelf.Provide a 65x65 pixel icon if you wish.Download from the Exchange“Download Shelf…” grabs the shelf package .zip file from the exchange and unzips the contents of that packageinto HOME/houdini9.0/toolbar/downloads/Any .otls in that package are immediately installed, any .shelf files in the package are immediately loaded into<strong>Houdini</strong> and made visible and current in the shelf areaEach time <strong>Houdini</strong> starts up it looks in $HOME/houdini9.0/toolbar/downloads and recursively searches andinstalls any .shelf and .otl files it finds there.Manual Installation and System-wide InstallationInstalling the tools from the Exchange in to the default $HOME/houdini/toolbar/downloads directory workswell <strong>for</strong> local testing and use. This method relies on a back door mechanism in <strong>Houdini</strong> where any data typeknown to <strong>Houdini</strong> in the ./downloads folder is searched and included in to the current <strong>Houdini</strong> session. Onceyou want to start using the tools on a larger scale, you will want to move these tools and files in to a morerigid and maintainable structure. You have the same two choices that were covered in the Internal Developmentsection above: Local Path vs. Explicit Paths. It is recommended that Explicit Paths be used in facilitiesto centralize the tools <strong>for</strong> everyone to use. The Local Path approach should only be used <strong>for</strong> very small facilitiesor where the tools are to be used in a very local scope in a production.Regardless of which way you choose to install the tools from the default downloads directory, manual interventionand installation of the tools is required. This is covered in detail in the Internal Development sectionabove.24 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Appendix A: Tool specification exampleRBD SimplePurposeThis is a self-contained RBD simulation, with limited user controls, that allows a user to instantly have a workingsimulation to experiment with. It is particularly intended <strong>for</strong> Escape users, to let them get a sense of DOPsand RBD, without having to build anything.UsageUsing the tool from the ShelfThe user can -click on the RBD Simple tool in the shelf. In this case, the RBD tool is createdwith its default objects, and is ready to go. The user only has to hit Play.Alternatively, the user clicks on the RBD Simple tool in the shelf, and if 3 existing objects (separateobjects, at the /obj level) are already selected, then the Toy is created, ready to run, with the 3selected objects used as geometry.If any other number of objects is currently selected (0, 1, 2, 4 or more) then the user is prompted toselect 1 or more objects from either the viewport or the network. Be<strong>for</strong>e each new selection, the usercan complete the tool with the key or RMB -> Complete Selection. There needs to be someway to make additional selections (-select?)If the user completes the selection process with 3 objects, then they are all assigned as be<strong>for</strong>e. Ifless than 3, then the selections are assigned to the Toy objects, in order. The result would be someuser objects and some Toy default objects.I’m not sure what should happen if there are already 4 objects selected, or if the user tries to continueto select objects past 3. One simple rule would be that when he ends the selection process,only the first 3 selected objects are used, and the rest are ignored.The result is an object-level asset with 4 parameter tabs.Modifying the simulation objectsThere are 3 identical parameter tabs, one <strong>for</strong> each object in the Toy simulation. Each tab containsthe following parameters <strong>for</strong> its respective object:Path to object that contains the geometryActive / Passive toggleMassBounceFrictionInitial Velocity X Y ZModifying the simulation parametersThere is a tab that contains a few parameters <strong>for</strong> controlling the simulation. Those parameters are:Gravity X Y ZScale timeCollision Accuracy (maps to Resolve Penetration passes)Substeps (this modifies RBD Solver Min and Max Steps to the same value)Rendering the simulationThe asset will be set up so that the geometry is brought back out to the SOP level with the appropriaterender flags set. However, there will be no way to assign shaders or manipulate lights in thisasset. So the user can render it, but it will be monochrome (or some other default colors / textures)<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 25


Componentsand lighting will have to come from other lights in the scene. The only real purpose of this is to makesure something reasonable happens if the user tries to render the simulation.Tool ScriptsOptionsName: rbd_simpleLabel: RBD: SimpleTool Shelf Behaviour- Tool works on any geometry object selection in the viewport. It also works with no selections.- Takes selected object and references its display geometry to create DOPs RBD Objects.- If less than 3 objects are selected, the user is prompted to make additional object selections.These are optional- If a valid selection is made when tool script is completed, the tool is created with those objectsreferenced.- If the user chooses not to make a selection when tool script is completed, the simulation is createdwith default geometry – a torus, a sphere, and a teapot, piled into a stack.Tab Menu Behaviour Viewer PaneViewer Pane Mask(s): OBJ- Viewport is placed at the object level if it’s not there already to add RBD Simple.- Upon selecting the tool, the user is queried to make one or more selections. Upon completionof the selection(s), the tool is created with those objects referenced as new DOPs RBDObjects.Tab Menu Behaviour Network PaneNetwork Pane Mask(s): OBJ- Network pane must be an object network to add RBD Simple. It is not available to any othercontexts.- Upon selecting the tool, the RBD Simple asset is added to the network. The user is then expectedto reference the appropriate geometry objects if desired. The user can do this by drag ‘n’drop into the object parameter fields of the RBD Simple asset parameter pane.Asset ScriptsNoneAsset(s)Rbd_simple- Single HDA that contains a SOP network and a DOP network.Shader(s)SurfaceAssign generic Mantra shader to extracted SOP geometry.DisplacementN.A.ProceduralN.A.Sourced DataNoneGenerated Data26 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


UI ElementsIconNone, unless the user wants to render the simulationUse custom designHandlesGeo objects have their regular handles, and those are used to position the objects in space. Thetrans<strong>for</strong>m is inherited into the DOPs simulation as the initial position of each object.ToolBoxN.A.ExamplesN.A.Like <strong>Tools</strong>NoneResourcesReferences- Dr Seuss DOPs example file developed <strong>for</strong> demonstration purposes<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 27


Appendix B: Help Card Format with Wiki MarkupNode Help Structure= Title =#context: obj#internal: tool_name#largeicon: opdef:Object/tool_name?largeicon.png#smallicon: opdef:Object/tool_name?smallicon.png“””Summary”””Introductory/overview text.@usage#. Select the objects.#. Click the shelf item.<strong>Houdini</strong> creates a new Node Label node at the object level.@parametersParm 1:Explanation.Parm 2:Explanation.Shelf item help structure= Title =#largeicon: opdef:Object/blah?largeicon.png#smallicon: opdef:Object/blah?smallicon.png“””Summary”””Introductory/overview text.@usage#. Select the objects.#. Click the shelf item.28 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Help components:TitleThis should be the human-readable label of the node or shelf item.SummaryAim <strong>for</strong> the summary to do two things: summarize the item’s purpose, and ideally give a short bit of instructionon how to use it. You should start with a short, pithy summary of the purpose of the node/shelf item. Start thesentence with a verb in the simple future tense. Don’t start the description with the name of the node, or “Thisnode...” or “This allows you to...” etc.The summary is used as the tooltip <strong>for</strong> items on the shelf.= Drops =“””Creates an animated rain simulation asset using the selected objects as raindrops.”””@usagePut instructions here about how to use the tool under this heading.@usage#. Create profile curves that define the shape of the surface.#. Click the tool.#. Select the profile curves in order.@parametersFor node documentation, put descriptions of the parameters under this heading.The list of parameters is a definition list: the name of a parameter on a line ending with a colon (:), and thenone or more paragraphs describing the parameter indented under it.Position:Paragraph 1.Paragraph 2.Paragraph 3.Rotation:Paragraph.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 29


Use heading 3s to represent parameter tabs.=== Trans<strong>for</strong>m ===Position:Paragraph 1.Paragraph 2.Paragraph 3.Rotation:Paragraph.=== Render ===Shader:Blah blah blah.Quality:Blee bloog blarg.Including images1. Add your images inside the asset as sections.2. Reference as follows:[Image:opdef:Object/blah?image1.png]Referencing other nodes[link text | Node:sop/copy]See <strong>Houdini</strong> online Help <strong>for</strong> more detailed in<strong>for</strong>mation on Wiki Formatting30 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Appendix C: The .shelf file <strong>for</strong>matThis specification of the XML shelf file contains definitions of the various shelf elements - shelf sets, toolshelves, and tools.<strong>Houdini</strong> will look <strong>for</strong> files with the extension .shelf in its TOOLBAR_PATH (which includes the directories suchas $HH/toolbar, $HOME/houdini9.0/toolbar, and $HOME/toolbar). All files that were found will be parsedand their contents will be available in the <strong>Houdini</strong> session. If a shelf set refers to an undefined shelf, or a shelfrefers to an undefined tool, such entities will be reported in the shelf UI.One architectural restriction is that one .shelf file cannot contain two tools, two shelves, or two shelf sets bythe same name.Most of the XML element attributes are optional (and default to empty string) except any ‘name’ attribute.Turn to the next page is an example of the .shelf file that illustratesall aspects of the xml shelf file.<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 31


Examplehelp URLOBJSOPPOPDOPPOPCOP2table/operatorOBJSOPPOPCHOPROPSHOPCOP2VOPVOPNETDOPfist Submenusecond submenu32 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Semi-Formal XML Syntax Definition:FILE :=followed by: followed by: DOCUMENT_CONTENTSfollowed by: DOCUMENT_CONTENTS :=zero or more SHELF_SETor, zero or more SHELFor, zero or more TOOL(not necessarily inthis order)SHELF_SET :=followed by zero or more followed by SHELF :=followed by zero or more followed by TOOL :=followed by zero or more STRING followed by zero or more STRING followed by zero or more TOOL_MENU_CONTEXTfollowed by zero or more STRING followed by exactly one TOOL_SCRIPTfollowed by TOOL_MENU_CONTEXT :=followed by zero or onefollowed by zero or morefollowed by STRING STRING TOOL_SCRIPT :=followed by followed by<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 33


Components Description:FILE - is the contents of the xml fileSHELF_SET - defines the shelf set entity ‘name’ attribute is a unique name identifier <strong>for</strong> the shelf set.‘label’ attribute is the label that appears in menus, etc. The element defines which shelf isincluded in the shelf set; the shelf’s unique name is specified as the ‘name’ attribute.SHELF - similar to SHELF_SET, but it defines a shelf entity ‘name’ attribute is a unique name identifier <strong>for</strong>the shelf. ‘label’ attribute specifies a label that appears in various UI menus, etc. The elementdefines which tool is included in the shelf; the ‘name’ attribute specifies the tool’s unique name.TOOL - defines the tool entity. ‘name’ attribute is a unique name that identifies the tool ‘label’ attributespecifies the label used in UI menus, etc. ‘icon’ attribute specifies the icon name used by this tool specifies the help text <strong>for</strong> the tool specifies the URL at which additional help can be found. The element encompasses a string that defines a path <strong>for</strong> the submenu in which this tool shouldappear in the TAB menu. The ‘/’ delimits the nesting of the sub-sub menus (if needed).TOOL_MENU_CONTEXT - defines a context in which the tool can appear within the Tab menu. ‘name’attribute defines the context pane and currently can be either “viewer” or “network” elementencompasses a string that specifies an operator (the standard ‘table/operator’ string). The tool will appearwithin the Tab menu if the network type (of a pane in which the Tab menu popped up) allows this operator. encompasses a string that specifies a network type <strong>for</strong> which the tool is allowed in the Tabmenu. Currently, the strings can be: OBJ, SOP, POP, CHOP, ROP, SHOP, COP2, VOP, VOPNET, and DOP.TOOL_SCRIPT -defines the script associated with the tool ‘scrptType’ attribute specifies the script language,currently it can be: “python” or “hscript”. The string within the CDATA section is the script itself.34 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


Appendix D: Development ChecklistIcons and Help1.2.Each tool should have an appropriate icon <strong>for</strong> each context. [see icon guidelines]Each tool must have a tooltip (F1 Help). An abbreviated purpose/usage description is appropriate.3. Each tool must have a Help Card <strong>for</strong>matted using textbook <strong>for</strong>matting [see Appendix B]4.ContextAny non-standard parameters must have tooltips.1.2.Specify valid pane(s) in which the tool can be TAB-ed or drag-n-dropped: viewport, network editor.Specify valid networks: SOPs, DOPs, etc.Behavior1.2.3.4.5.6.Each tool will try to make do with the pre-defined selection, regardless of the selection type. If theincoming selection is incompatible with the selection required by the tool, the tool will automaticallyconvert it to a type it understands or in<strong>for</strong>m the user of the problem.If a selection does not exist when the tool is invoked the tool will prompt <strong>for</strong> one, and will set the(component) selection mask appropriately.Each tool will set the selection mask according to the type of data it works with (particles, DOPs,points, uvs, etc).If the operation results in some kind of selection, as it usually does, the selection should be highlightedunless it is really stupid to do soAll tools must have prompting/hinting messages. Furthermore, the prompts must be complete. Forexample, if you want the user to select points, say so (not “select geometry”). If the tool requires anaction to complete the operation, the prompt must specify it: “press Enter to complete”.If the tool creates a node, the name of the node should be descriptive and have a suffix of “1”. This isimportant so that the node name sequence will be like “gravity1”, “gravity2”, “gravity3”, etc. insteadof “gravity”, “gravity1”, “gravity2”, etc.UI1.2.3.4.5.6.The toolbox above the viewport will contain a meaningful subset of the parameter set of the instantiatednode.Parameters should be named descriptively and according to existing conventionsParameter ranges and defaults should provide good results out of the boxConsider providing presets where appropriateHandles will be bound where feasible.Use relative paths to reference other nodes wherever possible<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 35


Appendix E: ReferencesLearning PythonPython Official Website: www.python.orgThe official Python website has an excellent starter tutorial <strong>for</strong> those users both new to programming and newto Python: http://docs.python.org/tut/tut.htmlOnce you get through the tutorial you will be using this site to refer to the documentation on many of the modulesand their interfaces available in Python.There is also a nice bibliograpy of various Python Books that are available:http://wiki.python.org/moin/PythonBooks organized by programming experience.Dive into Python is a python book intended <strong>for</strong> experienced programmers. If you have a strong command ofshell programming this is certainly within your grasp. It is available <strong>for</strong> free on-line athttp://www.diveintopython.org/ in several different <strong>for</strong>mats.Creating and Managing Environments: Linux/UnixAny decent book on Linux or Unix will suffice as they all will have a h on creating and managing environmentsin shells. Each linux shell can have its own discrete environment unlike Windows which has a single environmentthat the user works in. The exception is if shells are used in Windows.Along with many books, you can use web searches <strong>for</strong> “managing linux environment variables” to get a greatrange of tips, tutorials and advice on getting a handle on managing linux/unix environments.Creating and Managing Environments: WindowsManaging Environment Variables in Windows XPhttp://support.microsoft.com/kb/310519This site is the official support site describing how to create and manage environment variables within theWindows XP operating system. You can have user specific environment variables or system wide variables.36 | <strong>TECHNICAL</strong> <strong>PAPER</strong> Rev 1.0


<strong>Building</strong> <strong>Tools</strong> <strong>for</strong> <strong>Houdini</strong> 9 | 37


Side Effects SoftwareProduction Consulting ServicesThis technical paper was researched and produced by theProducton Consulting team at Side Effects Software. Forstudios looking <strong>for</strong> ways of making a more efficient productionpipeline, our team of experts can provide you with valuablein<strong>for</strong>mation and advice.Call us at 310 319-9876 to learn more and to set up appointmentwith one of our consultants.Judith CrowSenior Production Consultantjudith@sidefx.com

Hooray! Your file is uploaded and ready to be published.

Saved successfully!

Ooh no, something went wrong!