toolutils module

class toolutils.OrientInfo(parmname, defaultup=orientUpAxis.Y)

class toolutils.ToolboxTemplateGroup

Generates a UI code block and a template group for toolbox hou.SceneViewer.selectObjects

addFloatField(name, label, default_value, num_components=1, helpstr='')

Adds a float field control with a label to the toolbox

addIntField(name, label, default_value, num_components=1, helpstr='')

Adds an integer field control with a label to the toolbox

addMenu(name, label, values, default_value, helpstr='')

Adds a menu select control with a label to the toolbox

addStringField(name, label, default_value, num_components=1, helpstr='')

Adds a string field control with a label to the toolbox

addToggle(name, label, default_value, helpstr='')

Adds a toggle control with a label to the toolbox

addToggleList(name, labels, default_value, helpstr='')

Adds a TRS mask control with a label to the toolbox

buildHelpStr(h)

getValue(name)

Returns a UI Toolbox value

templategroup()

Returns the TemplateGroup

ui()

Returns the UI code block

update(layout_opt='JUSTIFY(center, center)')

Updates UI code block and TemplateGroup.

toolutils.activeCompositorPane(scriptargs)

toolutils.activePane(scriptargs)

Returns the current active pane. If the current tool was launched from a Tab menu, the “pane” scriptarg will be set, and indicates the active pane. Otherwise the tool was launched from the shelf and we have to look for an open viewer pane of the right type for the running tool.

toolutils.baseUpOrientation()

This function returns the base orientation (rotation) matrix that aligns the standard world axes to those of the global orientation preference.

toolutils.chooseNode(possible_nodes, title, message)

Prompts the user to select on of the given nodes. If there is only a single node, then that node is automatically returned. The title and message parameters determine what will show up in the prompt.

toolutils.compositorViewer()

Returns an existing open Compositing Viewer pane if there is one. A Context viewer is also acceptable is no dedicated compositing viewer is found.

toolutils.connectInputsAndOutputs(newnode, branch, inputitem, outputitem, inputindex, outputindex)

Simplified version of connectMultiInputsAndOutputs that takes at most a single input and output. Provided for backward compatibility with code written before the Multi code was written.

toolutils.connectMultiInputsAndOutputs(newnode, branch, inputs, outputs)

Wire the network so that new node connects to the provided inputs and outputs. This isn’t always possible, but get as close as we can. If branch is false, all of the inputs outputs will be made newnode’s outputs. Both inputs and outputs are optional.

toolutils.createModuleFromSection(module_name, node_type, section_name)

Create and return a module-like object with the given name from the contents of a section in an HDA. This module will not appear in sys.modules. If the source code has a syntax error, an exception will be raised. Use this function to create submodules in the PythonModule section of an HDA. For example:

submod = toolutils.createModuleFromSection(

‘submod’, kwargs[‘type’], ‘PythonSubmod’)

toolutils.createNodeInContainer(container, nodetypecategory, nodetypename, nodename, exact_node_type)

This function attempts to create a node of a given type category and type name in a given container. If the container does not allow a given type category, this funciton creates a network of a correct type first, and then creates the required node within that network. If exact_node_type is true, it attempts to create a node of the exact nodetypename; otherwise, the nodtypename may be resolved to the preferred namespace or version of that typename. It retuns a pair of nodes, the fist being the node created in the container and the second being the node of a required operator type (which in most cases will be the same nodes).

toolutils.createOrShowPythonPanel(kwargs, pypanel_interface_name, floating_panel_label, split_type)

creates a new float panel from a pypanel interface name or make existing ones visible.

split_type of 0, always creates a floating panel split_type of 1, adds a tab on the current panel split_type of 2, splits vertically and creates a new tab split_type of 3, splits horizontally and creates a new tab split_type of 4, splits vertically but only on viewports and creates a new tab Returns the python panels tab found

toolutils.dataTree(tree_type)

Returns an existing open Data Tree pane if there is one. If a tree type is provided, the Data Tree must be set to that tree type to be acceptable.

toolutils.findAllChildNodesOfType(parentnode, nodetype, dorecurse=False, findfirst=False, basetypematch=False)

Returns a list of all child nodes that match the given node type

toolutils.findAllChildNodesOfTypeWithParms(parentnode, nodetype, parmlist, dorecurse=False, findfirst=False, basetypematch=False)

Returns a list of all nodes contained in parent that match the nodetype & parmlist filters.

toolutils.findAllConnectionChainsToInputNode(startnode, endnode)

Finds all chains of hou.Connections that lead to endnode.

Returns an empty list if no such chain exists.

toolutils.findAllConnectionChainsToOutputNode(startnode, endnode)

Finds all chains of hou.Connections that lead to endnode.

Returns an empty list if no such chain exists.

toolutils.findAllInputNodesOfTypeWithParms(endnode, nodetype, parmlist, includeme=False, findfirst=False, seennodes=None, basetypematch=False)

Finds all nodes that are an ancestor of endnode, match nodetype, and have the parameters & value pairs listed in the parmlist dictionary. If basetypematch is true, only the node type’s base name is checked, ie, node type’s namespace and version components are ignored when testing against the matchtype (eg, matchtype ‘hda’ will match node types ‘hda’, ‘hda::1.5’ and ‘userx::hda’, etc). Otherwise, the node type name must match exactly the matchtype string.

toolutils.findAncestorOfBaseType(startnode, category, nodetype)

Return closest ancestor (or self) of ‘startnode’ with the specified category and type.

toolutils.findAncestorOfType(startnode, category, nodetype, basetypematch=False)

Return closest ancestor (or self) of ‘startnode’ with the specified category and type.

toolutils.findChildNodeOfType(parentnode, nodetype, dorecurse=False, basetypematch=False)

This function does a search of the node container hierarchy (rather than connection hierarchy) searching for a matching node type.

toolutils.findChildNodeOfTypeWithParms(parentnode, nodetype, parmlist, dorecurse=False, basetypematch=False)

This function does a search of the node container hierarchy (rather than connection hierarchy) searching for a matching node type which also has the given parameter list match.

toolutils.findConnectedNodes(startnode, connection_type, match_method, find_first=False, seennodes=None, includeme=False, incoming_conn=None, connection_chains=None, all_paths=False, connector_index=None, stop_method=None)

Finds all nodes that are connected to startnode for which match_method returns True. Searches either inputs or outputs, depending on the value of connection_type (either ‘input’ or ‘output’).

match_method may be a method taking a hou.Node as it’s argument. In that case only nodes for which it returns True are matched.

If connection_chains is a list, for each node it’ll be populated with the hou.NodeConnections by which the node was found. If additionally all_paths is True, all paths to the node will be returned, so nodes may appear multiple times in the returned list.

If find_first is True, the method will exit early as soon as a matching node is found. Having both find_first and all_paths True will raise a hou.Error.

stop_method may be a method taking a hou.Node and a hou.NodeConnection by which that node was reached. If it returns True, the node and further connected nodes will be ignored.

toolutils.findConnectionChainToInputNode(startnode, endnode)

Finds a chain of hou.Connections that lead to endnode.

Returns None if no such chain exists.

toolutils.findConnectionChainToOutputNode(startnode, endnode)

Finds a chain of hou.Connections that lead to endnode.

Returns None if no such chain exists.

toolutils.findGreatestCommonDescendent(endnode, searchnodes, seennodes=None)

Starting from end node and heading up the input chain locate the first node that doesn’t have all of searchnodes on the same input wire.

toolutils.findInputNode(endnode, searchnode, seennodes=None)

This function searches the endnode’s hierarchy to find if the given search node is connected

toolutils.findInputNodeOfBaseType(endnode, nodetype, includeme=False, seennodes=None)

This function does a depth first traversal of the node input hierarchy to find the first node whose type’s base name (ie, type name stripped of any namespace or version) matches the given type.

toolutils.findInputNodeOfType(endnode, nodetype, includeme=False, seennodes=None, basetypematch=False)

This function does a depth first traversal of the node input hierarchy to find the first node of a particular type. If basetypematch is true, only the node type’s base name is checked, ie, node type’s namespace and version components are ignored when testing against the matchtype (eg, matchtype ‘hda’ will match node types ‘hda’, ‘hda::1.5’ and ‘userx::hda’, etc). Otherwise, the node type name must match exactly the matchtype string.

toolutils.findInputNodeOfTypeWithParms(endnode, nodetype, parmlist, includeme=False, seennodes=None, basetypematch=False)

Finds any nodes that are an ancestor of endnode, match nodetype, and have the parameters & value pairs listed in the parmlist dictionary. If basetypematch is true, only the node type’s base name is checked, ie, node type’s namespace and version components are ignored when testing against the matchtype (eg, matchtype ‘hda’ will match node types ‘hda’, ‘hda::1.5’ and ‘userx::hda’, etc). Otherwise, the node type name must match exactly the matchtype string.

toolutils.findOutputNodeOfBaseType(endnode, nodetype, includeme=False, seennodes=None, returnall=False)

This function does a depth first traversal of the node input hierarchy to find the first node whose type’s base name (ie, type name stripped of any namespace or version) matches the given type. If returnall is true, returns a list of all matches in depth first order, or an empty list if no matches are found.

toolutils.findOutputNodeOfType(startnode, nodetype, includeme=False, seennodes=None, basetypematch=False, returnall=False)

This function does a depth first traversal of the node output hierarchy to find the first node that matches our search. If basetypematch is true, only the node type’s base name is checked, ie, node type’s namespace and version components are ignored when testing against the matchtype (eg, matchtype ‘hda’ will match node types ‘hda’, ‘hda::1.5’ and ‘userx::hda’, etc). Otherwise, the node type name must match exactly the matchtype string. If returnall is true, returns a list of all matches in depth first order, or an empty list if no matches are found.

toolutils.findOutputNodeOfTypeWithParms(startnode, nodetype, parmlist, includeme=False, seennodes=None, basetypematch=False, returnall=False)

Finds any nodes that are a descendent of startnode, match nodetype, and have the parameters & value pairs listed in the parmlist dictionary. If basetypematch is true, only the node type’s base name is checked, ie, node type’s namespace and version components are ignored when testing against the matchtype (eg, matchtype ‘hda’ will match node types ‘hda’, ‘hda::1.5’ and ‘userx::hda’, etc). Otherwise, the node type name must match exactly the matchtype string. If returnall is true, returns a list of all matches in depth first order, or an empty list if no matches are found.

toolutils.findPythonPanel(pypanel_interface_name)

toolutils.generateToolScriptForNode(nodepath_or_list, input_nodepath=None, output_nodepath=None)

toolutils.genericStateTool(scriptargs, statename)

Runs a specific state in an open viewer pane.

toolutils.genericTool(*args, **kwargs)

Handles the creation of any node in a Network Editor pane.

This function is intended to instantiate a node of a given type from shelf tools, and thus, if exact_node_type argument is True, it creates the node of the exact type specified by nodetypename. However, if exact_node_type argument is False, then the base type may get resolved to another namespace or another version, and the created node may be of that resolved type (eg ‘hda’ may resolve to ‘mynamespace::hda::2.0’).

toolutils.getBestConnector(innode, outidx, outnode, inidx, defaultidx)

toolutils.getImmediatePlacementOrientedPosition(scene_viewer, base_orientation=None)

Returns the world space position and world space orientation to use for immediate placement of a new tool given a scene viewer.

toolutils.getImmediatePlacementPosition(scene_viewer)

Returns the world space position to use for immediate placement of a new tool given a scene viewer.

toolutils.getSubnetOutputNodes(subnet)

Returns a list of output nodes. The position of a node within the list corresponds to it’s output index.

Intermediate entries that don’t have an output equal None.

toolutils.homeToItems(items)

Homes to their selection all network editors that are showing the network that contains items. Assumes that all items have the same parent.

toolutils.homeToSelectionNetworkEditorsFor(node)

Homes to their selection all network editors to that are showing the network that contains node.

toolutils.isMergeNode(node)

Returns True if the supplied node is a “merge” type node. Returns False otherwise. This merge designation affects the way this node gets inserted between existing inputs and outputs.

toolutils.mapTypeCategoriesToSubnetName(nodetypecategory, acceptedtypecategory)

This function returns a name of the subnet that accepts nodetypecategory as child type and can be created in a container whose child type is acceptedtypecategory. Returns None if these two categories are the same (ie, no need for a subnet to accommodate nodetypecategory). Also returns None if the mapping has not been defined yet.

toolutils.minimizePythonPanel(kwargs, pypanel_interface_name)

minimize pypanel interfaces.

toolutils.moveNodesToGoodPosition(movenodes)

Moves a list of nodes to good positions.

toolutils.networkEditor()

Returns an existing open Network Editor pane if there is one.

toolutils.nodeNameFromTypeName(nodetypename)

Given an operator node type name, return a valid node name corresponding to that type. For example, if the type name contains any namespace or version components, they are stripped off. The returned node name contains only characters that are allowed to appear in the node names.

toolutils.nodeTypeBaseNameMatches(node, matchtype)

Returns true if the node’s type base name matches the given type. A matchtype of None is assumed to match any node.

toolutils.nodeTypeNameBase(node)

Returns the node type base name (stripped of namespace or version).

toolutils.nodeTypeNameComponentsMatch(node, matchtype)

Returns true if the node’s type name components matches the given type. The components present in matchtype are checked against the node’s type, and this function returns true if they do match. Eg, matchtype ‘hda’ will match ‘hda’, ‘hda::1.5’, ‘userX::hda’, etc matchtype ‘userX::hda’ will match ‘userX::hda’, ‘userX::hda::1.5’, etc matchtype ‘hda::1.5’ will match ‘hda::1.5’, ‘userX::hda::1.5’, etc matchtype ‘::hda’ will match ‘hda’ and ‘hda::1.5’, but not ‘userX::hda’ matchtype ‘hda::’ will match ‘hda’ and ‘userX::hda’ but not ‘hda::1.5’ A matchtype of None is assumed to match any node.

toolutils.nodeTypeNameMatches(node, matchtype)

Returns true if the node’s type base name matches the given type. A matchtype of None is assumed to match any node.

toolutils.nodeTypeNameVersion(node)

Returns the node type version component.

toolutils.ocioColorSpaceMenu(include_roles=True)

toolutils.parseDialogScriptMenu(filename, defchoices=[], forhscript=True)

This function parses a disk file specified by the filename. The file is parsed such that comments (‘#’) are stripped and lines containing exactly 2 arguments are printed out. Quotes are handled.

The function can be used by dialog script menus which want to generate dynamic menus based on disk files.

The dynamic menu should have the script:

echo pythonexprs(“__import__(‘toolutils’).parseDialogScriptMenu(filename, [(‘token1’, ‘label1’), (‘token2’, ‘label2’), …])”)

the diskfile will be searched in the Houdini path. If the disk file isn’t found, the default choices will be used instead.

If the menu uses python script instead, set forhscript to False and it will return list of choices without surrounding them in quotes.

toolutils.placeToolImmediately(kwargs)

Returns true if the provided kwargs has a modifier key suggesting the tool be placed right away. This is a ctrl click or a cmd click depending on the platform.

toolutils.recursiveShowPane(p)

Maximize all the parent Pane splits and make the given panel visible.

toolutils.reformatPermissionErrors(function)

This function decorator will trap any permission error exceptions and raise a different exception with a nicer message.

toolutils.removeDefaultGeometryObjectContents(objectnode)

Destroy the File SOP that gets created inside a default Geometry Object.

toolutils.replaceInputConnections(olditem, oldinputindex, newnode, newinputindex)

Stick the new node between the output node and the node it is connected to (insert operation). Note there can be only one.

toolutils.replaceOutputConnections(olditem, oldoutputindex, newnode, newoutputindex)

Stick the new node between the input node and all nodes it is connected to (insert operation).

toolutils.safe_reload(module)

toolutils.sceneViewer()

Returns an existing open Scene Viewer pane if there is one. A Context viewer is also acceptable is no dedicated scene viewer is found.

toolutils.selectionPrompt(nodetypecategory, multisel=True, whichprompt=0)

Generates a generic selection prompt string when no specific prompt string is available in the toolprompts module.

toolutils.setUpOrientation(node, parmname, defaultup)

Assumes that the default value of the specified parameter in the given node corresponds to the orientation specified in defaultup and applies the necessary change to convert the node to the current orientation mode.

toolutils.testTool(tool, debug=False, kwargs=None, pane=None, ctrlclick=False, altclick=False, shiftclick=None)

executes a shelf tool.

If debug is True, the tool will be executed within pdb.run()

If ‘kwargs’ is not None, it is passed to the tool script as is and the remaining parameters are ignored, along with everything described below.

If ‘pane’ is None, hou.ui.paneTabOfType(hou.paneTabType.SceneViewer) is passed to the tool instead.

toolutils.updateBakeExtractImageFormat()

Obsolete as of H16.0 - but is required for old hip files

toolutils.updateBakePlanes(parm)

Obsolete as of H16.0 - but is required for old hip files

toolutils.updatePlaneType(planeindex, variable)

This function is intended to update deep raster plane parameters based on the newly set plane variable name. Use this in a callback script as follows:

callback “pythonexprs(“__import__(‘toolutils’).updatePlaneType($script_multiparm_index, ‘$script_value’)”)”