The Layout LOP node has a brushing mode that lets you interactively populate the scene with point instanced models (for example, trees, bushes, rocks, buildings). How the node translates mouse events into creating instances is controlled by a brush asset. You can create your own brush asset that provides custom behavior defined by a SOP network.

Since the brush’s behavior is defined by a compiled SOP block, you can use the full power of (compile-able) SOPs, including curve and polygon manipulation nodes, scatter nodes, and VEX code in wrangles.

You can give the brush asset a parameter interface. This interface is displayed in the Layout UI when your brush is active. This lets you give your uses controls to customize your brush’s behavior.

Before you implement a brush, you should probably be familiar with the following subjects:

• Compiled blocks. The implementation of the brush is inside a compiled block (so it can be invoked by the parent Layout node with high performance). There are limitations to what SOP nodes you can use inside a compiled block, as well as limitations on expressions that cause nodes to cook.

• Wrangle nodes and VEX snippets. Often the easiest way to implement some behavior is to use an Attribute Wrangle to read attributes, compute values, and write new attributes. However, this requires some knowledge of VEX snippets and the built-in VEX functions.

• A brush is a SOP asset with six inputs and two outputs. A brush can create new points, or modify/delete existing points.

• Within the network is a compiled block that is repeatedly invoked as the user moves the mouse.

• The compiled block inputs contain information from the layout LOP about the current state and what the user has done.

• The compiled block is invoked even when the user is just moving the mouse around, before they begin a stroke. This allows you to display guides and preview.

  Switch If|Node:sop/switchif] nodes are useful to control behaviour specific to certain mouse actions, for example, only outputting points when the user is dragging the mouse.

• The layout brush convention to represent transforms are the same pscale and orient attributes output by many common SOPs like the Scatter and Align SOP.

  Note

  Authoring other instance attributes may cause odd behaviour as some will override all pscale and orient attributes for all current and previously authored points.

• Outputting custom point attributes will create primitive attributes on the resulting instances for all authored points. Be careful not to introduce a large amount of attributes as it may hinder performance.

• To instance a model from the working set onto a point, do the following:

  • Set the point’s asset_index attribute to the point number of the point in the sixth (Working Set) input corresponding to the model you want to instance.

• To modify a point (from either the “new” or “existing” inputs), do the following:

  • To set the position of a point, set the P vector3 point attribute.

  • To set the orientation and scale of the instanced model on a point, you have to encode the rotations and scales into a matrix3 point attribute called transform.

    You can easily set/edit a transform attribute using a Transform SOP. Add the Transofrm node to the network, set the Rotate and Scale parameters on the node to the values you want, and set the Attributes parameter to transform to write the transformations into the attribute.

  • Send any modified points to the the first output.

    If you modify an existing point, it will be deleted and an identical new point will be added to the first (New Points) input on the next invocation. So any existing points you edit with a stroke become part of the stroke’s “new” points.

  Note

  To scale/rotate instances, you must encode them in the standard orient vector4 and pscale `float attributes. Using other instancing attributes may override these and cause undue effects.

• If you haven’t modified existing points, you shouldn’t send them to the output (the output always represents the new set of “new points” created by the current stroke). If your brush doesn’t affect existing points, you don’t need to wire the second input into anything at all.

• To delete an existing point, create a delete point attribute on the point and set it to 1. Then merge the point into the first output.

  To delete a point from the current stroke (the first (New Points) input), just don’t send it down to the output.

• Normally, on the mouse up event at the end of a stroke, the point output of the brush’s compiled block is “committed” and integrated into the Layout node’s point instance data.

• If necessary, you can implement a brush that allows the user to make multiple strokes as part of one operation.

  For example, you could implement a fence-drawing brush where each click/drag makes a new corner in the fence until the user closes the fence by connecting back to the start (or until the user presses Enter to leave the fence open).

  You could also use a multi-stroke interaction to let the user draw rectangles, where one stroke defines the length of one side, and then a second drag pulls out the length of the adjecent side.

• To indicate to the parent Layout node that the current operation should continue after the current stroke, add a end_stroke detail attribute to the first output, set to 0.

  The Layout node sees that the attribute exists and keeps the current operation active. Subsequent strokes will keep appending to the same list of “existing points”.

• Then, to indicate to the parent Layout that the current operation is finished, set the end_stroke detail attribute on the first output to 1.

  In the fence making example, you would use an Attribute Create node to create the end_stroke integer detail attribute, and connect it to the first output. You could then use an expression or Attribute Wrangle to set the attribute to 1 if the end of the current stroke is near the starting point or the first stroke, or 0 otherwise.

  The layout node sees end_stroke exists but is set to 1, and commits the output.

• The user can always press Enter to finish and commit the current operation.

• Implementing a multi-stroke brush is more complex, but there are a couple of techniques that can help you

  • Use a series of Switch If nodes to switch to individual branches that handle each of the different event types.

  • If you need to pass information between invocations and/or strokes, you can set your own custom detail attributes on the first output. The detail attributes from the first output will be copied back into the first (New Points) input, until the operation is committed.

    In the example of drawing a rectangle, you could use a detail attribute to keep track of whether the current stroke is the first or second stroke of the operation.

When the user finishes an operation:

• The Layout node clears any detail attributes added to the output geometry.

  Detail attributes you create on the output geometry become available as detail attributes on the first (New Points) input on the next iteration. If you use these detail attributes on the to communicate information between iterations (or strokes in a multi-stroke brush), the information will not carry over between operations.

• The Layout node also clears any primitives generated by the brush as a precaution.

  Since there is a lot of merging of point clouds, if primitives are involved the primitive merging quickly becomes exponential and will lock up Houdini.

You can design a parameter interface for the brush, and in the compiled block, use a ch expression to read the value of a parameter and use it to change how the brush works.

For example, you could have a Density parameter (internal name density) on the brush asset to control how many points the brush scatters as the user drags. Inside the compile block, for example in the Force Total Count parameter of a Scatter SOP, you can use the expression ch("../density") to copy the parameter value.

When a brush is active in the Layout LOP, the layout interface shows the brush parameters, the same as they would appear in a parameter editor.

There are two ways to allow the user to use the scroll wheel to change how your brush behaves.

• If your brush’s parameter interface has a parameter whose internal name starts with scroll, that parameter will be incremented/decremented when the user scrolls the mouse wheel. (If more than one parameter starts with scroll, the node will change them all.)

• If you implement an onMouseWheelEvent(kwargs) function in the asset’s Python module, the Layout state will call it when the user scrolls the mouse wheel.

The convention for resizing the radius (or similar attributes) of a brush is ⌃ Ctrl + ⇧ Shift + similar to Attribute Paint or Vellum brushes.

To enable this for your brush, add the tag drag_resize to the parameter or parameters that you want to affect.

By default changing parameters will cause the last invocation of the brush to reapply. This is desired for most parameters but sometimes you will have organizational parameters such as folders, or even menu parameters controlling the brush mode that you don’t want to cause a change in the last stroke.

To disable invocation of the brush due to a specific parameter change, add the layout_ignore tag to the desired parameters.

As a brush author, you can decide how to use the working set of models chosen by the user. You can choose to give significance to the ordering of the items in the working set, or not.

• A common interpretation will be to randomly choose items from the working set, for example when scattering items across the scene.

• Your brush can use the ordering of the working set. For example, you might make a brush that drops the first item in the working set into the scene, and scatters instances of the second item in a rough ring around it, and a ring of the third item around that, and so on (this might be useful for scattering trees with a small ecosystem of rocks, dead branches, etc. around each tree).

  As another example, in a brush that scatters items randomly, you could use the ordering of the items to influence how likely each item is to be chosen, with earlier items in the set being more likely than later items.

• Currently there is no automatic way to indicate to the brush user whether the brush treats the ordering of the working set as significant. It should be part of the brush’s documentation, or be controllable in the brush’s parameter interface.

• A good way to handle randomization of the working set onto generated points is to wire the working set input into a Connectivity SOP, set the piece attribute name to asset_index and then assign those pieces to the points using an Attrib From Pieces SOP.

A digital asset contains a section you can use to hold Python source code. This is often useful for storing shared utility functions for use by the asset’s various callbacks, as well as where the asset’s interactive state is implemented, if any.

For brush assets, the parent Layout node will check for a couple of functions in the

The Layout state currently uses the following functions, if they exist in the brush asset’s Python module.

def registerGadgets():
    return [("line_gadget", hou.drawableGeometryType.Line), ("face_gadget", hou.drawableGeometryType.Face)]

def onDrawGuides(kwargs):
    draw_handle = kwargs['draw_handle']
    guide_geo = kwargs['guide_geo']
    line_gadget = kwargs['gadgets']['line_gadget']
    face_gadget = kwargs['gadgets']['face_gadget']

    line_gadget.setGeometry(guide_geo)
    line_gadget.show(True)
    line_gadget.draw(draw_handle)

    face_gadget.setGeometry(guide_geo)
    face_gadget.show(True)
    face_gadget.draw(draw_handle)

def onMouseWheelEvent(self, kwargs):
    # Get the UI device object
    device = kwargs["ui_event"].device()
    scroll_amount = device.mouseWheel()

def hudTemplate():
    return [
        {"key": "G", "label": "Change brush shape"},
        {"key": "mousewheel", "label": "Change brush radius"},
        {"key": "LMB", "label": "Scatter instances"},
        {"key": "Shift + LMB", "label": "Smooth instance orientations"},
    ]

def hudTemplate():
    return [{
        'id': 'info',
        'label': ''
    }]

def hudUpdate():
    # This function might be triggered by a parameter callback script
    # calling layout.utils.requestHUDUpdate(). We evaluate what mode is
    # active and update the 'info' label accordingly.
    import layout.utils
    node = layout.utils.currentBrushNode()
    mode = node.evalParm("mode")

    if mode == 0:
        label = 'Define grid'
    elif mode == 1:
        label = 'Define disk radius'
    elif mode == 2:
        label = 'Draw scatter region'
    else:
        raise ValueError("Invalid brush mode.")

    return  {'info': {'label': label, 'key': 'LMB'}}

def radialMenu(kwargs):
    node = kwargs["node"]

    entries = {}
    entries['n'] = {
        'type':'script_action',
        'label':'Reset Radius',
        'script': lambda: node.setParm("radius", 1.0)
    }
    entries['e'] = {
        'type':'script_action',
        'label':'Embiggen Instances',
        'script': lambda: node.setParm("instance_scale", node.evalParm("instance_scale") + 1.0)
    }
    entries['s'] = {
        'type':'script_action',
        'label':'Disembiggen Instances',
        'script': lambda: node.setParm("instance_scale", node.evalParm("instance_scale") - 1.0)
    }
    return entries

To help make a brush that works in screen space, we provide the screen_to_world_xform detail attribute on the fifth (Stroke) input. This transform matrix corresponds to: viewport.windowToViewportTransform() * viewport.viewportToNDCTransform() * viewport.ndcToCameraTransform() * viewport.cameraToModelTransform() * viewport.modelToGeometryTransform()

In english what this does is maps a point in world space to screen space. To get the proper screen space position however you need to divide the resulting vector by its 'w' component to dehomogenize it. Once dehomogenized the x and y components represent the screen coordinates and the z component represents the depth from -1 to 1 NDC coordinates. -1 Being the near clipping plane and 1 being the far clipping plane.

It is highly recommended that you just copy an existing screen space brush such as the Delete or Nudge brushes then modify it as necessary.

• To handle asset assignment from a working set with more than one item, wire the working set into a Connectivity SOP with the Piece attribute name set to asset_index, then wire that into an Attrib From Pieces SOP's second input (wire the points you are instancing to into the first input).

• To get the number of points in an input to a wrangle, you can use npoints(‹input_num›) in the VEX snippet. This works in a wrangle since it cooks all its inputs but generally in compiled SOPs you need to use a spare input and call npoints on the spare input, for example npoints(-1). See compiled SOPs.

• You can create nodes outside the compiled block to do “set up”, then add another Compile Block Start node to the compile block as an “extra argument” and wire the “outside” nodes into it. These nodes will be cooked once, and the static result will be available in the block from the block input.

  For example, if you want to set up some complex guide geometry, where only the transform might change during the invocation, not the geometry itself, you could create the the geometry outside the compile block and wire it in, instead of recreating it on each invocation.