Viewer states control interaction in the viewport. For example, the Rotate tool is a view state. The Handles tool allows access to the state associated with the current node. Houdini lets you create and register your own custom view states in Python.
This object describes a custom state, including its implementation class and bindings (e.g. menus, handles, hotkeys, selectors, etc…). You supply an instance of this object when registering a custom state, and Houdini uses it to create concrete instances of the state.
import hou # Create a class implementing the state callbacks class MyState(object): def __init__(self, state_name, scene_viewer): self.state_name = state_name self.scene_viewer = scene_viewer # Create a template to describe the state and its bindings template = hou.ViewerStateTemplate( "mystate", "My Custom State", hou.sopNodeTypeCategory() ) template.bindFactory(MyState) template.bindHandleStatic( "rotate", "rot", [("rx", "x"), ("ry", "y"), ("rz", "z")] ) # Register the template with Houdini hou.ui.registerViewerState(my_template)
For information on how to create your own custom view states, see Python states.
Methods ¶
__init__(state_name, state_label, node_type_category, contexts=None)
Creates a new instance of ViewerStateTemplate
representing a unique custom state type.
ViewerStateTemplate
is identified by a name and a category type. The name is the custom type of the
state. The category specifies the context-level that Houdini uses to run the state. If you want your state to run across
multiple context-levels, additional contexts can be added with the contexts
parameter. Therefore, when the state is
active and the user switches to a new context, Houdini will reuse the current state instance, provided the new context
matches one of the state contexts.
This example demonstrates how to register an OBJ
state which can run in the SOP
and CHOP
contexts as well:
import hou # Create a class implementing the state callbacks class MyState(object): def __init__(self, state_name, scene_viewer): self.state_name = state_name self.scene_viewer = scene_viewer # Create a template to describe the state and its bindings state_name = "mystate" state_label = "My Custom State" node_type_category = hou.objNodeTypeCategory() extra_contexts = [hou.sopNodeTypeCategory(), hou.chopNodeTypeCategory()] template = hou.ViewerStateTemplate( state_name, state_label, node_type_category, contexts=extra_contexts ) template.bindFactory(MyState) # Register the template with Houdini hou.ui.registerViewerState(my_template)
state_name
A unique string to identify the viewer state.
state_label
A human-readable name for the state, for display in the user interface.
node_type_category
An instance of hou.NodeTypeCategory. For SOPs use the result of:
hou.sopNodeTypeCategory()
For OBJ states use:
hou.objNodeTypeCategory()
For LOP states use:
hou.lopNodeTypeCategory()
For DOP states use:
hou.dopNodeTypeCategory()
contexts
A list of hou.NodeTypeCategory objects to specify additional context-levels for the state.
Choose any of the following types to add to contexts
:
Note: An exception will be thrown if unsupported types are used. Note: hou.lopNodeTypeCategory() doesn’t support extra contexts and cannot be used as such.
typeName()
→ str
Returns a unique string used to identify the viewer state.
categoryName()
→ str
Returns the name of the node type category of the state which you can use for creating the proper category object.
contexts()
→ list
of hou.NodeTypeCategory
Returns the list of contexts in which the state can be used.
bindFactory(callable)
Takes a callable object (such as a class or function) that returns an implementation of the state interface. Usually this will be a class (a Python class is a callable object which returns an instance of the class). The callable should accept two arguments: a string containing the name of the state, and a hou.SceneViewer object representing the current viewer.
class MyState(object): def __init__(self, state_name, scene_viewer): self.state_name = state_name self.scene_viewer = scene_viewer def onMouseEvent(sefl, kwargs): ui_event = kwargs["ui_event"] def createViewerTemplate(*args): template = hou.ViewerStateTemplate("mystate", "My State", hou.sopNodeTypeCategory()) template.bindFactory(MyState) return template
bindHandle(handle_type, name, settings=None, cache_previous_parms=False, handle_parms=None)
Dynamically binds a handle to the state (see also bindHandleStatic() and hou.SceneViewer.bindViewerHandle). While a static binding binds a handle to a parameter unconditionally ahead of time, this method gives you more flexibility, allowing you to choose in a callback function at runtime what parameter to bind to, or to bind to multiple parameters.
If you do know ahead of time that you need to bind a certain handle to a certain parameter (which is usually the case), use bindHandleStatic()
instead since it is more straightforward.
The following binds a vector
handle and enables only the rotation vector (vx
) and the twist
parms. The rest of the handle parms will be disabled along with their UI controls.
t = hou.ViewerStateTemplate('my_state', 'my_state_label', hou.sopNodeTypeCategory()) t.bindHandle( 'vector', 'Vector', handle_parms=["vx","vy","vz","twist"] )
This will bind a HUD slider with specific settings for the value and lock limits.
t = hou.ViewerStateTemplate('my_state', 'my_state_label', hou.sopNodeTypeCategory()) t.bindHandle( 'hudslider', 'Modifier', cache_previous_parms=True, settings="hudrangelow(0) hudrangehigh(5) hudlocklow(0) hudlockhigh(5)" )
handle_type
A string naming the type of handle. See State handle types for a list of handle types to choose from.
name
A string to use to identify the handle. Each binding’s name must be unique within this state. Trying to bind the same name more than once will raise an exception.
settings
A string containing specific settings of the handle. Multiple settings must be space separated.
cache_previous_parms
If True, the handle retains a record of previous values. This can be useful if you want your code to calculate deltas as the user moves the handle, for example to know how fast the user is dragging the handle.
handle_parms
An array of handle parm names to specify the parms to enable, only the parms contained in the array will be available to the python state callbacks.
All handle parms are enabled when handle_parms
is empty (default).
bindHandleStatic(handle_type, name, bindings, settings=None)
Binds a handle to the node parameters driven by the viewer state. Dragging the handle will automatically update the bound parameter(s). See also bindHandle() and hou.SceneViewer.bindViewerHandleStatic.
t = hou.ViewerStateTemplate('my_state', 'my_state_label', hou.sopNodeTypeCategory()) ... t.bindHandleStatic( 'vector', 'Up Direction', [ ('group', 'input'), ('originx', 'tx'), ('originy', 'ty'), ('originz', 'tz'), ('upx', 'vx'), ('upy', 'vy'), ('upz', 'vz') ] )
handle_type
A string naming the type of handle.
name
A unique string to use to identify the handle. Each binding’s name must be unique within this state. Trying to bind the same name more than once will raise an exception.
bindings
A list of ("node_parm_name", "handle_parm_name")
tuples. This binds the parts of the handle to individual parameters on the node.
settings
A string containing specific settings of a handle. Multiple settings must be space separated.
bindGeometrySelector(prompt, allow_drag=False, quick_select=True, auto_start=True, toolbox=True, use_existing_selection=True, consume_selection=True, secure_selection=hou.secureSelectionOption.Obey, initial_selection="", initial_selection_type=hou.geometryType.Primitives, ordered=False, geometry_types=[], primitive_types=[], allow_other_sops=False, hotkey="", name="")
Binds a geometry selector to a SOP viewer state. This selector is used for selecting geometry elements when the underlying viewer state is active. This selector can only be used in a scene viewer, exception is thrown otherwise at registration (hou.ui.registerViewerStateTemplate).
Multiple geometry selectors can be bound to a viewer state. However, other selector types cannot be mixed, exception is thrown otherwise.
The viewer state plug-in can implement the onSelection
method to receive new selections. onSelection
gets the new selection as a hou.GeometrySelection stored in the selection
entry of the input
kwargs
dictionary. The return value can be True
to stop the selection tool or False
to keep it running. Pressing Enter also terminates the selector.
allow_drag
Determines whether selecting a component with a single mouse click completes the selection. This is typically used to prevent a multiple component selection. Defaults to False.
allow_other_sops
Allow selecting components on geometry from other geometry nodes visible in the viewport. Defaults to False
.
auto_start
If True
(the default), starts the selector when the viewer state is activated. If False
, you must specify a hotkey
argument that activates the selector.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
consume_selection
If True (default), clears the current selection when the selector is deactivated.
geometry_types
An array of hou.geometryType values representing the component types the user can select. The default is an empty list, the selector follows the Geometry Select Mode.
hotkey
An optional hotkey which acts as a switch for starting or stopping the selector. The default is an empty string.
initial_selection
When use_existing_selection
is False
, this is a string of component group syntax representing what to set the selection to when the state is activated. The default is no selection.
initial_selection_type
A hou.geometryType value, representing the type of components specified by the initial_selection
argument. The default is None, the selector follows the Geometry Select Mode.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
ordered
If this is True
, Houdini returns the components in the selection in the order the user selected them. The default is False
, meaning the order of the components you get is unrelated to the order they were selected.
Only set this to True
if for some reason you need to distinguish, for example, the first primitive the user clicked, or the last, or that kind of thing.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
primitive_types
A list of hou.primType values representing the primitive types the user can select. An empty list (default) allows selecting all types.
quick_select
If this is True
, the state’s selection event is called whenever the selection changes. If this is False
, Houdini waits for the user to finish selection by pressing Enter before it notifies the state about the new selection.
secure_selection
This option is used to configure the selector for secure selection. By default, the selector always obey the current viewer’s secure selection setting. For more details see Secure selection support and hou.secureSelectionOption.
use_existing_selection
If this is True
, and a component selection exists when the user activates the state, Houdini will call onSelection
with that selection. If this is False
, Houdini will clear any existing selection and ask for a new selection.
bindObjectSelector(prompt, quick_select=True, auto_start=True, toolbox=True, use_existing_selection=True, allow_multisel=True, secure_selection=hou.secureSelectionOption.Obey, allowed_types=('*',), hotkey="", name="")
Binds an object selector to a OBJ viewer state. This selector is used for selecting objects when the underlying viewer state is active. This selector can only be used in a scene viewer, exception is thrown otherwise at registration (hou.ui.registerViewerStateTemplate).
Multiple object selectors can be bound to a viewer state. However, other selector types cannot be mixed with OBJ selectors, exception is thrown otherwise.
The viewer state plug-in can implement the onSelection
method to receive new selections. onSelection
gets the new selection as a list of hou.OpNode objects stored in
the selection
entry of the input kwargs
dictionary. The return value can be True
to stop the selection tool or False
to keep it running. Pressing Enter also terminates the selector.
allowed_types
A list of strings to specify one or multiple object types the user can select. For instance, add geo
to allowed_types
to select geometry objects only. Patterns such as *
can be used to select any objects or more restrictive patterns
such as *cam*
for selecting any camera objects. All available object types can be obtained with hou.objNodeTypeCategory.nodeTypes. Defaults to *
.
auto_start
If True
(the default), start the selector when the viewer state is activated. If False
, you must specify a hotkey
argument that activates the selector.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
hotkey
An optional hotkey which acts as a switch for starting or stopping the selector. The default is None
.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
quick_select
If this is True
, the state’s selection event is called whenever the selection changes. If this is False
, Houdini waits for the user to finish selection by pressing Enter before it notifies the state about the new selection. Defaults to True
.
secure_selection
This option is used to configure the selector for secure selection. By default, the selector always obey the current viewer’s secure selection setting. For more details see Secure selection support and hou.secureSelectionOption.
use_existing_selection
If this is True
, and a component selection exists when the user activates the state, Houdini will call onSelection
with that selection. If this is False
, Houdini will clear any existing selection and ask for a new selection. Defaults to True
.
bindSceneGraphSelector(prompt, allow_drag=True, quick_select=True, auto_start=True, toolbox=True, use_existing_selection=True, secure_selection=hou.secureSelectionOption.Obey, consume_selection=False, allow_multisel=True, prior_selection_paths=None, prim_mask=None, path_prefix_mask=None, prim_kind=None, hotkey="", name="")
Binds a scene graph selector to a SOP viewer state. This selector is used for selecting scene graph elements when the underlying viewer state is active. This selector can only be bound used in a scene graph viewer, exception is thrown otherwise at registration (hou.ui.registerViewerStateTemplate).
Multiple scene graph selectors can be bound to a viewer state. However, other selector types cannot be mixed with scene graph selectors, exception is thrown otherwise.
The viewer state plug-in can implement the onSelection
method to receive new selections. onSelection
gets the new selection as a list of element
paths stored in the selection
entry of the input kwargs
dictionary. The return value can be True
to keep running the selection tool or False
to stop it. Pressing Enter also terminates the selector.
allow_drag
Allows the selection to be completed with a single mouse click. Defaults to True.
allow_multisel
Allows the tool to select multiple elements. Defaults to True.
auto_start
Start the selector when the viewer state is activated. True by default.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
consume_selection
If True, clears the current selection when the selector is deactivated. Defaults to False
.
hotkey
An optional hotkey which acts as a toggle switch for starting or stopping the selector. No hotkey by default.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
path_prefix_mask
Filter out selectable elements by a name prefix. Empty by default.
prim_kind
Primitive kind to highlight. Empty by default.
prim_mask
Filter mask for the selection (hou.scenePrimMask). Defaults to hou.scenePrimMask.ViewerSetting
prior_selection_paths
Array of element paths to pre-select.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
quick_select
Configure the selector to use quick selections. When True the selection callback is called automatically for each selection, if False the user must hit 'enter' to complete the selection. Defaults to True.
secure_selection
This option is used to configure the selector for secure selection. By default, the selector always obey the current viewer’s secure selection setting. For more details see Secure selection support and hou.secureSelectionOption.
use_existing_selection
If True, the selector uses the existing selection. Defaults to True.
bindDynamicsSelector(prompt, allow_objects=True, allow_modifiers=False, quick_select=True, auto_start=True, toolbox=True, use_existing_selection=True, secure_selection=hou.secureSelectionOption.Obey, allow_multisel=True, hotkey="", name="")
Binds a dynamics selector to a DOP viewer state. This selector is used for selecting dynamics objects and modifiers when the underlying viewer state is active. This selector can only be used in a scene viewer, exception is thrown otherwise at registration (hou.ui.registerViewerStateTemplate).
Multiple dynamics, point and polygon selectors can be bound to a viewer state. However, other selector types cannot be mixed with DOP selectors, exception is thrown otherwise.
The viewer state plug-in can implement the onSelection
method to receive new selections. onSelection
gets the new selection as a list of hou.DopData objects stored in the selection
entry of the input
kwargs
dictionary. The return value can be True
to stop the selection tool or False
to keep it running. Pressing Enter also terminates the selector.
allow_modifiers
Allows the tool to select simulation modifiers. Exception is thrown if allow_modifiers
and allow_objects
are both set to False. Default to False.
allow_multisel
Allows the tool to select multiple elements. Defaults to True.
allow_objects
Allows object selection. Exception is thrown if allow_modifiers
and allow_objects
are both set to False. Defaults to True.
auto_start
If True
(the default), start the selector when the viewer state is activated. If False
, you must specify a hotkey
argument that activates the selector.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
hotkey
An optional hotkey which acts as a switch for starting or stopping the selector. The default is None
.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
quick_select
If this is True
, the state’s selection event is called whenever the selection changes. If this is False
, Houdini waits for the user to finish selection by pressing Enter before it notifies the state about the new selection.
secure_selection
This option is used to configure the selector for secure selection. By default, the selector always obey the current viewer’s secure selection setting. For more details see Secure selection support and hou.secureSelectionOption.
use_existing_selection
If this is True
, and a component selection exists when the user activates the state, Houdini will call onSelection
with that selection. If this is False
, Houdini will clear any existing selection and ask for a new selection.
bindDynamicsPointSelector(prompt, allow_objects=True, allow_modifiers=False, quick_select=True, auto_start=True, toolbox=True, use_existing_selection=True, secure_selection=hou.secureSelectionOption.Obey, allow_multisel=True, only_select_points=True, object_based_point_selection=False, use_last_selected_object=False, hotkey="", name="")
Binds a dynamics point selector to a DOP viewer state. This selector is used for selecting point elements when the underlying viewer state is active. This selector can only be used in a scene viewer, exception is thrown otherwise at registration (hou.ui.registerViewerStateTemplate).
Multiple dynamics, polygon and point selectors can be bound to a viewer state. However, other selector types cannot be mixed with DOP selectors, exception is thrown otherwise.
The viewer state plug-in can implement the onSelection
method to receive new selections. onSelection
gets the new selection as a list of (hou.DopData,hou.GeometrySelection) tuples stored in the selection
entry of the input
kwargs
dictionary. The return value can be True
to stop the selection tool or False
to keep it running. Pressing Enter also terminates the selector.
allow_modifiers
Allows the tool to select simulation modifiers. Default to False.
allow_multisel
Allows the tool to select multiple elements. Defaults to True.
allow_objects
Allows object selection. Defaults to True.
auto_start
If True
(the default), start the selector when the viewer state is activated. If False
, you must specify a hotkey
argument that activates the selector.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
hotkey
An optional hotkey which acts as a switch for starting or stopping the selector. The default is None
.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
object_based_point_selection
Force selection of points on the currently selected object instead of the default selection of points on the closest object. Default to False.
only_select_points
Default to True.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
quick_select
If this is True
, the state’s selection event is called whenever the selection changes. If this is False
, Houdini waits for the user to finish selection by pressing Enter before it notifies the state about the new selection.
secure_selection
This option is used to configure the selector for secure selection. By default, the selector always obey the current viewer’s secure selection setting. For more details see Secure selection support and hou.secureSelectionOption.
use_existing_selection
If this is True
, and a component selection exists when the user activates the state, Houdini will call onSelection
with that selection. If this is False
, Houdini will clear any existing selection and ask for a new selection.
use_last_selected_object
Force point selection to only be possible on the specified object and do not allow selection of a different object. Default to False.
bindDynamicsPolygonSelector(prompt, quick_select=True, auto_start=True, toolbox=True, use_existing_selection=True, object_based_point_selection=False, secure_selection=hou.secureSelectionOption.Obey, use_last_selected_object=False, hotkey="", name="")
Binds a dynamics polygon selector to a DOP viewer state. This selector is used for selecting polygon elements when the underlying viewer state is active. This selector can only be used in a scene viewer, exception is thrown otherwise at registration (hou.ui.registerViewerStateTemplate).
Multiple dynamics, point and polygon selectors can be bound to a viewer state. However, other selector types cannot be mixed with DOP selectors, exception is thrown otherwise.
The viewer state plug-in can implement the onSelection
method to receive new selections. onSelection
gets the new selection as a list of (hou.DopData,hou.GeometrySelection) tuples stored in the selection
entry of the input
kwargs
dictionary. The return value can be True
to stop the selection tool or False
to keep it running. Pressing Enter also terminates the selector.
auto_start
If True
(the default), start the selector when the viewer state is activated. If False
, you must specify a hotkey
argument that activates the selector.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
hotkey
An optional hotkey which acts as a switch for starting or stopping the selector. The default is None
.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
object_based_point_selection
Force selection of points on the currently selected object instead of the default selection of points on the closest object. Default to False.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
quick_select
If this is True
, the state’s selection event is called whenever the selection changes. If this is False
, Houdini waits for the user to finish selection by pressing Enter before it notifies the state about the new selection.
secure_selection
This option is used to configure the selector for secure selection. By default, the selector always obey the current viewer’s secure selection setting. For more details see Secure selection support and hou.secureSelectionOption.
use_existing_selection
If this is True
, and a component selection exists when the user activates the state, Houdini will call onSelection
with that selection. If this is False
, Houdini will clear any existing selection and ask for a new selection.
use_last_selected_object
Force polygon selection to only be possible on the specified object and do not allow selection of a different object. Default to False.
bindSelector(name, selector_type, prompt, primitive_types=None, group_parm_name=None, input_index=0, input_required=True, allow_dragging=True)
Binds a selector to the digital asset tied to this viewer state. You can bind multiple selectors to the same viewer state.
These selectors are typically used by the shelf tool of the digital asset to create new instances of the SOP
nodes. Houdini will
invoke all bounded selectors, wait for the user to select geometries, and then connect the input SOP
s and fill in group parameters
to match what was selected.
This kind of selector is different from the ones created with hou.ViewerStateTemplate.bindGeometrySelector or hou.ViewerStateTemplate.bindObjectSelector. They are strictly used by Houdini and cannot be triggered with hou.SceneViewer.triggerStateSelector.
name
A unique selector name identifier.
selector_type
The type of the selector to bind. The following types are supported:
Type |
Description |
---|---|
|
Select only primitives. |
|
Select only points. |
|
Select only edges. |
|
Select any geometries. |
prompt
Prompt displayed in the viewport to instruct the user what to select. The prompt is mandatory.
primitive_types
Specify the type of selectable primitives (hou.primType). Defaults to all types.
group_parm_name
The name of the SOP node parameter containing the group field. The selector will set this parameter to the string representing the points, primitives, edges, etc. chosen by the user in the viewer. If None, the selector will look for a parameter named “group”.
input_index
The index of the input connector on the SOP
node where the selector should wire input SOP
s. A cookie SOP
, for example, has two input
connectors. It has two selectors, one for each input connector. Defaults to 0.
input_required
Specify if an input is required or not. If the user does not select any geometry and the input is not required, the selector will not wire anything to its input connector. Defaults to True.
allow_dragging
Determines if click-and-drag operations are allowed. Click-and-drag operations select the geometry and begin manipulating the handles with a single mouse drag. Dragging the geometry forces the selector to finish immediately, the selector connects the input and sets the group parameter, and subsequent mouse movements are passed to the handle which translates the geometry by changing parameter values. Defaults to True.
bindDrawableSelector(prompt, auto_start=True, toolbox=True, drawable_mask=[], hotkey="", name="")
Binds a drawable selector to a viewer state to select drawable components such as points, faces and lines. Drawable selectors are supported for the SOP, OBJ and LOP contexts. The selector selects components of drawables created by the viewer state, a mask can be used to make specific drawables selectable. Drawables created by the viewer state not in the mask are ignored by the selector.
A selection event is triggered whenever the selection changes, the onSelection
handler can be implemented by the viewer state plug-in to receive new
selections. The locate information is sent to the viewer state whenever the mouse is positioned over drawable components, the onLocateSelection
handler
can be implemented by the viewer state plug-in to receive new drawable locate information. The viewer state typically uses these handlers for drawing the
located and selected drawable components. See Binding a drawable selector for more details.
auto_start
If True
(the default), starts the selector when the viewer state is activated. If False
, you must specify a hotkey
argument that activates the selector.
toolbox
If True
(the default), the selector toolbox is displayed when the selector is activated. If False
, the selector toolbox will be hidden.
hotkey
An optional hotkey which acts as a switch for starting or stopping the selector. The default is an empty string.
name
Optional name identifier (None by default) for the selector, must be unique within the viewer state. The name is used for triggering selector operations.
drawable_mask
A list of drawable names representing selectable drawables. By default (empty list) all drawables created by a python state are selectable.
prompt
Prompt displayed in the viewport when the selector is active. The prompt is mandatory.
bindMenu(menu)
Attaches a context menu to this viewer state. You can only bind one single context menu per template.
bindParameter(param_type, name=None, label=None, menu_as_button_strip=False, menu_items=[], num_components=1, default_value=None, min_limit=0, max_limit=1, align=False, toolbox=True)
Creates a parameter template for a viewer state. The template describes a parameter with settings such as the name or the data it holds. See state parameters for more details on how to use them.
align
Specifies how the parameter is aligned in the Parameter Dialog
. If True, the parameter is
aligned horizontally with the next bound parameter. if False, the parameter is displayed below
the previous one. Defaults to False.
default_value
The default value of the parameter. This is the value Houdini uses to initialize the parameter.
The value type should ideally match param_type
but Houdini will do its best to convert the
type appropriately. Defaults to None.
Parameter type |
Value type |
---|---|
The value is ignored. |
|
Menu item identifier as defined with |
|
Toggle state as a bool or int. |
name
The parameter string identifier. The name cannot be empty and must be unique within the state or an exception is raised.
label
The parameter label. If sets to None
(default), the label is set with the parameter name.
min_limit
Describes the minimum value the parameter can be set in the UI dialog. Defaults to 0. Used with the following types:
max_limit
Describes the maximum value the parameter can be set in the UI dialog. Defaults to 1. Used with the following types:
num_components
Specifies the number of components to create for the parameter template. Defaults to 1. Exceptions are raised if the value is invalid.
num_components
> 1 is supported for the following types:
param_type
The type of parameter to bind. The following types are supported:
An exception is raised for other types.
toolbox
The parameter is always displayed in the Parameter Dialog
but you can set this flag to display
the parameter in the Operation Toolbox
as well.
bindIcon(icon_name)
Sets the icon image of this viewer state.
icon_name
The name of the icon. Defaults to MISC_python
. The icon name can be specified as follows:
-
As a single name.
-
As a path to the image icon file on disk. There is no convention for where to put icon files on disk.
eg.
template.bindIcon("$HOUDINI_USER_PREF_DIR/config/Icons/myicon.pic")
-
As an
opdef
path if the viewer state is implemented in aDigital Asset
.eg.
template.bindIcon("opdef:/Object/myop?myicon.pic")
bindSupportsSelectionChange(supports_change)
Indicates to the LOP Viewer pane that this state can handle USD primitive selection changes. The state for the Edit LOP is a good example of such a state. Changing the primitive selection in the scene graph tree causes this node to move the handle to the new selection’s centroid and start manipulating the newly selected primitives.
bindSupportsMoveTool(supports_movetool)
Indicates to the LOP Viewer pane that this state can provide a “move tool” for the currently selected primitives. The state for the Edit LOP is a good example of such a state.
bindGadget(drawable_type, gadget_name, gadget_label=None)
Lets you bind a gadget drawable to a viewer state. A gadget is a special geometry drawable which provides visual interaction support for picking and locating the underlying gadget’s geometry.
Houdini uses the binding info to create the gadget drawable instances, you don’t create objects
of this type by yourself. The gadget instances are stored in a dictionary, accessible with the
state_gadgets
class attribute. Use the gadget name to query self.state_gadgets
for a specific
gadget.
Note
self.state_gadgets
cannot not be accessed from the class __init__
method, but you can
use it however from any other class methods.
Houdini provides the picking and locating support, you don’t have to implement anything specific
to locate or pick a gadget component. hou.ViewerStateContext is used by Houdini to store
the active gadget picking and locating information, this context is created by Houdini and
accessible with the state_context
class attribute.
import viewerstate.utils as su def createViewerStateTemplate(): state_typename = "state gadgets" state_label = "State gadgets" state_cat = hou.sopNodeTypeCategory() template = hou.ViewerStateTemplate(state_typename, state_label, state_cat) template.bindFactory(State) template.bindIcon(kwargs["type"].icon()) template.bindGadget( hou.drawableGeometryType.Line, "line_gadget", label="Line" ) template.bindGadget( hou.drawableGeometryType.Face, "face_gadget", label="Face" ) template.bindGadget( hou.drawableGeometryType.Point, "point_gadget", label="Point" ) return template class State(object): def __init__(self, state_name, scene_viewer): self.state_name = state_name self.scene_viewer = scene_viewer self.cursor = su.CursorLabel(scene_viewer) def onEnter(self, kwargs): """ Initializes the gadget drawables and assign them to class attributes. """ node = kwargs["node"] self.geometry = node.geometry() self.line_gadget = self.state_gadgets["line_gadget"] self.line_gadget.setGeometry(self.geometry) self.line_gadget.setParams({"draw_color":[.3,0,0,1], "locate_color":[1,0,0,1], "pick_color":[1,1,0,1], "line_width":2.0}) self.line_gadget.show(True) self.face_gadget = self.state_gadgets["face_gadget"] self.face_gadget.setGeometry(self.geometry) self.face_gadget.setParams({"draw_color":[0,.3,0,1], "locate_color":[1,0,0,1],"pick_color":[1,1,0,1]}) self.face_gadget.show(True) self.point_gadget = self.state_gadgets["point_gadget"] self.point_gadget.setGeometry(self.geometry) self.point_gadget.setParams({"draw_color":[0,0,.3,1], "locate_color":[0,0,1,1], "pick_color":[1,1,0,1], "radius":15.0}) self.point_gadget.show(True) def onMouseEvent(self, kwargs): """ Computes the cursor text position and drawable geometry """ # init the cursor with the mouse kwargs self.cursor.setParams(kwargs) # Use the active gadget information to set the cursor label. gadget_name = self.state_context.gadget() if gadget_name in ["line_gadget", "face_gadget", "point_gadget"]: gadget = self.state_gadgets[gadget_name] label = self.state_context.gadgetLabel() c1 = self.state_context.component1() c2 = self.state_context.component2() self.cursor.setLabel("{} : {} {}".format(label, c1, c2 if c2 > -1 else "")) self.cursor.show(True) else: self.cursor.show(False) return True def onDraw( self, kwargs ): handle = kwargs["draw_handle"] self.line_gadget.draw(handle) self.face_gadget.draw(handle) self.point_gadget.draw(handle)
geometry_drawable_type
The gadget geometry type. The following types are supported:
gadget_name
The gadget name string identifier.
gadget_label
An optional description name. Defaults to None.
bindNodeChangeEvent(event_types)
Binds an event handler to the state for listening to a particular event that occurs on the state’s node instance. onNodeChangeEvent must be implemented by the state to respond to events.
Binding a node event is similar to hou.OpNode.addEventCallback, but there is no need to provide a callback or to remove it by yourself when the state exits, Houdini takes care of it for you.
event_types
A list of hou.nodeEventType enumeration values describing the event types to listen to.
An error is raised if the list is empty.
bindNodeParmChangeEvent(parm_names)
Binds an event handler to the state for listening to parm changes occuring on the state’s node. onNodeChangeEvent
must be implemented by the state to respond to parm events. This method is similar to hou.OpNode.addParmCallback, it’s
considered more efficient than bindNodeChangeEvent
as Houdini will trigger onNodeChangeEvent
only for the changes
that occurs for the parms you want to track.
parm_names
A list of node parm names used by Houdini for filtering out the parm changes that occur on the state’s
node. Only the changes that match the parms specified in parm_names
are sent to onNodeChangeEvent.
An error is raised if the list is empty.
bindPlaybackChangeEvent()
Binds an event handler to the state for listening to playbar events such as hou.playbarEvent.Started
and hou.playbarEvent.FrameChanged. The state must implement onPlaybackChangeEvent
to respond to playback events. bindPlaybackChangeEvent
is similar to hou.playbar.addEventCallback` but
you don’t need to provide a callback or to remove it when the state exits, Houdini takes care of it for you.
bindHotkeyDefinitions(definitions)
Binds a hotkey definitions object to this viewer state that defines the hotkey commands and contexts implemented by the state. You can only bind one such definitions object per template.
definitions
The hou.PluginHotkeyDefinitions object to add.