Skip to content

Touch Regions Touch Regions

Named face sets that turn the model itself into the control picker.

Node type RigExecTouchRegions
Example touch_regions.usda

On this page:

Overview

Touch regions make the skin clickable: a named set of faces on one mesh carries the control a click inside it should select, so picking the forearm selects the forearm control instead of hunting for a wire shape in a crowded viewport. A RigExecTouchRegions scope names the mesh it annotates and holds one RigExecTouchRegion child per set, plus the one colour ramp declared for all of them — rigExec:touch:palette, indexed by the region's own order — and the opacity to draw them at. The scope is found by type, so it may be parked beside the geometry it annotates or inside the RigExecRoot for a studio that ships one prim holding the whole rig.

Regions are annotation, not rig: a stage evaluates identically with them, without them, or with half of them unpainted. They are deliberately not GeomSubsets — hdSt collects every face subset under a mesh whatever its familyName, so a touch set would collide with the materialBind subset owning the same face; the sets live in a scope of their own.

A mesh's touch regions: the shared palette, and one RigExecTouchRegion child per named set.

A SCOPE rather than a bare Typed prim: it is a grouping of annotations on drawable geometry, and an imageable container costs nothing and keeps the door open for anything drawable parented under it later.

THE HIGHLIGHT IS NOT GEOMETRY. TouchPose tints the touched mesh in its own Storm shader, through a Hydra scene index that adds a per-face region primvar and a per-region colour table (libs/rigExecImaging/touchPoseHighlight.h). A hover authors nothing on the stage and never invalidates the rig.

Found BY TYPE, so the regions may be parented anywhere -- beside the geometry they annotate, or inside the RigExecRoot for a studio that ships one prim holding the whole rig deliverable. The mesh is named by relationship rather than by position, which is what makes that placement free.

How it works

Touch regions belong to no compile or evaluation phase: rigExec:touch:* appears nowhere under libs/rigExec, so they add nothing to the pose walk. They are read at UI time by the usdview TouchPose plugin, which traverses the stage for prims typed RigExecTouchRegions, keeps the scopes whose rigExec:touch:mesh targets the mesh being touched (a scope naming no mesh matches whichever mesh is asked for), orders the ones that have region children by rigExec:touch:layerOrder, opens the first (or the one the editor's layer switch names) as the live layer, and flattens its regions into a single face -> region int array (−1 for unpainted skin). That table goes to the native mesh in rigExecImaging, which keeps a BVH over the posed triangles and refits it whenever the rig publishes a new pose, so a pick ray hits the deformed skin and resolves to a face, a region, and the control that region names. Lighting a region creates, deletes and authors nothing: the imaging plugin publishes a per-face slot (the region index + 1, 0 for unpainted skin) as a uniform primvar and the current colours as a constant vec4[] table, and swaps the mesh's surface terminal for a generated shader that runs the original one and then mixes table[slot] into the lit colour — a hover is one constant-primvar upload, not a resync.

Wiring

Relationship Points to Required
rigExec:touch:mesh The UsdGeomMesh whose faces every region under this scope indexes. Nothing enforces it: a scope with no target is kept for whichever mesh is asked for, which is only safe while the stage holds one character. no
(children) One RigExecTouchRegion per named set. A scope with no region children is passed over. yes
rigExec:touch:control Per region: the control a click inside it selects. Unenforced, but a region without one is dropped by the reader's default rather than drawn inert. no
rigExec:touch:faces Per region: the face indices it owns on the parent's mesh. Unenforced: a region with none is read, owns no face, and can never be hit. no

Parameters

Touch region (per child prim)

rigExec:touch:faces

Type: uniform int[]. Default: [].

Face indices on the mesh named by the parent's rigExec:touch:mesh. Face indices, not vertex indices: a pick resolves to a face and this is the set it is looked up in.

rigExec:touch:elementType

Type: uniform token. Default: "face".

Valid values: face.

What rigExec:touch:faces indexes. Only face today; the token is here so a point or edge set does not need a second attribute when one is wanted.

rigExec:touch:control

Relationship.

The control a click in this region selects. Unauthored, TouchPose skips the region: its faces read as unpainted skin, where a plain click clears the selection.

Node parameters

rigExec:touch:mesh

Relationship.

The UsdGeomMesh whose faces these regions index.

rigExec:touch:palette

Type: uniform color3f[]. Default: [].

One ramp shared by every region, indexed by the region's own order. On the scope rather than per region: the overlay needs the whole ramp in a single read.

rigExec:touch:alpha

Type: uniform float. Default: 1.

Opacity the overlay draws the regions at.

rigExec:touch:layerName

Type: uniform token. Default: "".

This scope's name as a LAYER, for the editor's switch. Empty falls back to the prim's own name.

One scope is one layer: a mesh may carry several, each with its own regions, its own palette and its own paint, and exactly one of them is live at a time. That is what lets a body set and a face set annotate the same mesh without fighting over faces -- the face -> region table is one to one WITHIN a layer, and carries no obligation across them.

Note what this is NOT: it is not a USD layer. A touch layer is a prim, composed like any other, and a stage's sublayers can each contribute one.

rigExec:touch:layerOrder

Type: uniform int. Default: 0.

Where this layer sits in the editor's list, and which one opens live: the lowest order wins. Ties break on the layer name, so the order is total and an unordered file still opens the same way twice.

Example

A three-segment strip skinned by an FK chain, its twelve faces divided into three named regions — base_touch, mid_touch, tip_touch, four faces each — every one naming the control that poses that segment. The TouchPose scope targets the single Skin mesh and carries a three-colour ramp and the empty, invisible Overlay prim the TouchPose exporter ships beside the regions. Nothing in the file drives the regions: the FK controls curl the strip and back, and the face sets ride along on the deformed skin.

Open it live with:

bin\launch_usdview.bat docs\examples\touch_regions.usda

Tips

  • Keep regions disjoint. The lookup is one flat face -> region array built by scattering each region's faces in namespace order, so a face claimed twice silently belongs to whichever region is written last; the painting tools maintain the partition for you.
  • A region with no rigExec:touch:control is skipped by the reader rather than drawn dead — an unbound set must not swallow the click that would otherwise reach usdview's own picking.
  • Face indices are scattered against the mesh's live face count and anything out of range is dropped without a word, so a region set exported against different topology fails quietly: re-export the regions whenever the mesh's face count changes.

See also


UsdRig