| On this page | |
| Inheritance |
|
Overview ¶
The hou.Drawable2D API provides a unified solution for drawing shape entities in both compositing
and scene viewers within a 2D context. It supports rendering of various geometric primitives, from
simple lines to complex freeform shapes, as either wireframes or filled areas. Full picking and
locating functionality is integrated across both viewer types.
Note
By default, hou.Drawable2D shape entities are constrained to the XY plane (z=0) in the Front and Perspective views. However, the plane transform can be modified, which automatically places and aligns the drawables to the new plane position.
Primarily intended for COP Python states and handles, they can also be utilized in other contexts like SOPs
and LOPs. A current limitation prevents the concurrent use of hou.Drawable2D and hou.GeometryDrawable.
Methods ¶
__init__(scene_viewer, type, name, label=None, pickable=False, fixed_size=False, params=None)
Creates a new drawable object of a specified type. The newly created drawable is initially hidden.
Warning
hou.Drawable2D objects must be created from the onEnter event of a Python state or
the onActivate event of a Python handle.
For node-less Python states, the onGenerate event must be used instead of onEnter.
Creating Drawable2D objects outside of these contexts may lead to unexpected behavior or cause the drawable to function incorrectly.
scene_viewer
A reference to the viewer where the drawable will be displayed, either a hou.SceneViewer or hou.CompositorViewer.
type
A hou.drawable2DType value indicating the type of drawable to create (e.g., Arc, Line, Shape).
name
A string used to uniquely identify this drawable object.
label
An optional string to set a display label for the drawable. Defaults to an empty string.
pickable
A boolean value indicating whether the drawable can be picked and located. Set to False to disable interaction. Defaults to True.
fixed_size
Flag used to render the drawable at a fixed size. When enabled, the drawable maintains a constant size regardless of zoom level. Defaults to False.
Note
This flag is enabled by default when the drawable is created for use by a Python Handle.
params
An optional dictionary containing parameters to configure the drawable’s appearance and behavior. See hou.Drawable2D.setParams for a detailed list of available parameters for each drawable type.
setParams(params)
Sets the parameters of the drawable entity using a dictionary. The params dictionary can include
attributes common to all drawable types (e.g., position, color) and those specific to the drawable’s
type (e.g., radius for an Arc, points for a Line or Shape).
Common parameters available for each drawable type:
Common |
Description |
Type |
|---|---|---|
|
The main color of the drawable, as an RGB or RGBA value. |
Sequence of 3 or 4 ints or doubles, hou.Color. Defaults to |
|
The locate color (or highlight) of the drawable, as an RGB or RGBA value. |
Sequence of 3 or 4 ints or doubles, hou.Color. Defaults to |
Specific parameters for each drawable type:
Arc |
Description |
Type |
|---|---|---|
|
The ending angle of the arc in degrees. |
int or double. Defaults to |
|
The cap style at the end of the arc. |
hou.drawable2DCapStyle. Defaults to |
|
The end cap color, as an RGB or RGBA value. |
Array of 3 or 4 ints or doubles, hou.Color. Defaults to |
|
Whether to fill the arc area. |
int or bool. Defaults to |
|
The inner radius of the arc. |
int or double. Defaults to |
|
The position where the entity is placed in the viewer (XY plane). |
Array of 2 ints or doubles, hou.Vector2. Defaults to |
|
The radius of the arc. |
int or double. Defaults to |
|
The starting angle of the arc in degrees. |
int or double. Defaults to |
|
The cap style at the start of the arc. |
hou.drawable2DCapStyle. Defaults to |
|
The start cap color, as an RGB or RGBA value. |
Array of 3 or 4 ints or doubles, hou.Color. Defaults to |
|
The arc thickness value (1 to 5) |
int, double. Defaults to |
Circle |
Description |
Type |
|
Whether to fill the circle area. |
int or bool. Defaults to |
|
The inner radius of the circle. |
int or double. Defaults to |
|
The position where the entity is placed in the viewer (XY plane). |
Array of 2 ints or doubles, hou.Vector2. Defaults to |
|
The radius of the circle. |
int or double. Defaults to |
|
The circle thickness value (1 to 5) |
int, double. Defaults to |
Line |
Description |
Type |
|
The cap style at the end of the arc. |
hou.drawable2DCapStyle. Defaults to |
|
The end cap color, as an RGB or RGBA value. |
Array of 3 or 4 ints or doubles, hou.Color. Defaults to |
|
An array containing the points defining the line. The first two values describe the starting point (x0, y0), and the next two describe the ending point (x1, y1). |
Array of 4 ints or doubles. Defaults to |
|
The cap style at the start of the line. |
hou.drawable2DCapStyle. Defaults to |
|
The start cap color, as an RGB or RGBA value. |
Array of 3 or 4 ints or doubles, hou.Color. Defaults to |
|
The style of a line drawable. |
hou.drawable2DLineStyle. Defaults to |
|
The line thickness value (1 to 5) |
int, double. Defaults to |
Marker |
Description |
Type |
|
The position where the entity is placed in the viewer (XY plane). |
Array of 2 ints or doubles, hou.Vector2. Defaults to |
|
Enumerator value to set the size of the marker. |
hou.drawable2DMarkerSize. Defaults to |
|
The marker thickness value (1 to 5) |
int, double. Defaults to |
|
The style of marker. |
hou.drawable2DMarkerStyle. Defaults to |
Rect |
Description |
Type |
|
Corner radius parameter for rounded corners. |
int or double. Defaults to |
|
Whether to fill the rectangle area. |
int or bool. Defaults to |
|
The position where the entity is placed in the viewer (XY plane). |
Array of 2 ints or doubles, hou.Vector2. Defaults to |
|
Sets the width and height of the rectangle. Pass a single value for a square. |
int, double, Array of 2 ints or doubles, hou.Vector2. Defaults to |
|
The rectangle thickness value (1 to 5) |
int, double. Defaults to |
Shape |
Description |
Type |
|
If |
int or bool. Defaults to |
|
The vertices describing the shape, defined as a flattened sequence of point
coordinates (e.g., |
|
|
The shape thickness value (1 to 5) |
int, double. Defaults to |
Text |
Description |
Type |
|
The position where the entity is placed in the viewer (XY plane). |
Sequence of 2 ints or doubles, hou.Vector2. Defaults to |
|
The text font size. |
int or double. Defaults to |
|
The text value. |
string |
Layer |
Description |
Type |
|
Apply viewer color correction preferences to the drawable layer. |
|
|
When true, the layer retains the size and aspect ratio of the node layer. |
|
params() -> dict[str, Any]
Returns the parameter dictionary currently stored in a hou.Drawable2D object. See hou.Drawable2D.setParams for details on the dictionary’s contents.
draw(handle, params=None)
Draws the drawable in a viewport. This method is typically called during the Python state’s
onDraw or onDrawInterrupt
event to render the drawable in the current viewport.
handle
An opaque identifier generated by Houdini for rendering the drawable. This handle value is
provided to the Python state’s onDraw callback and should be passed directly to this draw
method of the drawable object.
params
An optional dictionary of parameters to override the drawable’s current settings specifically for this draw call. These parameters are the same as those used by hou.Drawable2D.setParams.
mapToModel(x, y, z=0)
→ hou.Vector3
Maps a screen-space mouse position (x, y, z) to a corresponding point in the drawable’s local model space. This is particularly useful for positioning and interacting with 2D drawables within both 2D and 3D viewports.
Note
The z parameter is often 0 for interactions constrained to the 2D plane.
Returns a hou.Vector3 representing the mapped point in the drawable’s model space.
x
The mouse’s X-coordinate in screen space.
y
The mouse’s Y-coordinate in screen space.
z
The mouse’s Z-coordinate in screen space (typically 0 for 2D drawables).
setPickable(value)
Sets whether this drawable can be picked and located by user interactions.
value
A boolean value. Set to True to enable picking and locating for this drawable. Set to False to disable interaction.
isPickable()
→ bool
Returns True if this drawable is currently enabled for picking and locating, False otherwise.
setFixedSize(value)
Set whether this drawable is rendered at a fixed size.
value
Set to True to render the drawable at a fixed size.
isFixedSize()
→ bool
Return True if the drawable is rendered at a fixed size.
fixedSizeScale()
→ double
Returns the scale factor used for fixed-size rendering. When fixed-size rendering is enabled on the drawable, the scale factor is computed based on the current viewport zoom level. Otherwise, the scale factor is 1.0.
postTransform()
→ hou.Matrix4
Returns the post-transform matrix currently assigned to the drawable. The post-transform is pre-computed in COPs and allows the drawable to be aligned with a COP layer’s world transform.
The post-transform is applied after the drawable’s own transform stack, so the effective transform becomes:
final_xform = drawable_transform * post_transform
A post-transform effectively makes the drawable’s transform behave as a local matrix relative to the post-transform. When the post-transform is not the identity, the drawable’s transform is evaluated in the space defined by the post-transform, even though it may have originally been authored in world space.
This is not a traditional parent-child hierarchy in which the drawable is authored directly in the parent’s local space. Instead, the post-transform is applied afterward to reposition and reorient the already-defined drawable.
Note
By default, Houdini assigns the current layer world transform (index = 0) as the post-transform when a state is entered or a handle is activated. No additional code is required for this default behavior.
The scaling component of the post-transform is removed so that it does not affect the drawable’s own scaling.
xform
A hou.Matrix4 transformation matrix specifying translation and rotation. This can be the layer world transform or any other transform you wish to apply.
postScale()
→ hou.Vector3
Return the post-scale vector used during rendering to position the drawable.
This scale is extracted from the COP layer transform and baked into the drawable’s translation matrix at render time. As a result, drawables do not need to be manually positioned using postScale(), since their translation is already adjusted accordingly.
However, postScale() can be useful when computing or adjusting the positioning of drawable guides.
drawTransform()
→ hou.Matrix4
Returns the transform matrix used for rendering the drawable. This transform is the combination of transform() and postTransform().
layerTransform()
→ hou.Matrix4
Return the COP layer transform matrix used as the reference transform for the drawable.
postMulTransform(xform)
Post-multiply the drawable’s transform with xform
preMulTransform(xform)
Pre-multiply the drawable’s transform with xform
imageLayer()
→ hou.ImageLayer
Returns the image layer displayed by this drawable.
setImageLayer(image_layer)
Sets an image layer on this drawable for display.
image_layer
Mandatory image layer to display.
Methods from hou.Drawable ¶
name()
The name of this drawable.
label()
The label of this drawable.
setLabel(label)
Set the label for this drawable.
show(value)
Displays or hides the element attached to this drawable in the viewport. The element will appear the next time the viewer redraws.
value
True to show the element or False to hide it.
visible()
→ bool
Returns True if the drawable is visible or not.
setTransform(xform)
Sets the transform matrix of the element attached to this drawable. The changes will appear the next time the viewer redraws.
xform
A hou.Matrix4 transformation matrix to set the element’s translation, rotation, and scale.
transform()
: → hou.Matrix4
Returns the transform matrix of the element attached to the drawable.
setIsControl(value)
Flags the drawable as control geometry. Simple Drawables are not affected by certain shading modes nor will they have decorations or visualizers drawn for it. They will be hidden when the Node Guides display option is off.
Note
This method does not apply to hou.Drawable2D objects.
isControl()
: → bool
Query if a drawable has been flaged as control geometry.