Picker Button¶
One clickable shape: selects controls, flips a switch, or decorates.
| Node type | RigExecPickerButton |
| Example | picker.usda |
On this page:
Overview¶
A button is one shape in a panel and one of four things, decided by
what it names rather than by a flag: a SELECT button lists prims in
rigExec:picker:controls, a SWITCH edits the one attribute in
rigExec:picker:attribute, a COMMAND runs the named action in
rigExec:picker:command, and a button naming none of them is DECORATION —
a backdrop, a silhouette, a label. Everything else on the class is
appearance and visibility: outline, colours, text, draw order, and
which half of an IK/FK pair a button belongs to.
One button. Selects the prims in rigExec:picker:controls, edits the attribute in rigExec:picker:attribute, runs a rigExec:picker:command, or none of these -- such a button is a decoration: the body silhouette, a backdrop, a label.
LIVENESS is the resolve result, not a flag. A button is live when every prim it targets is a RigExecControl or RigExecJoint of the picker's rig, and the panel does not draw a button that is not. USD remaps the targets through renames and reparents on its own, which a path string in a sidecar file cannot do, so a control that MOVES keeps its button and only a control that is DELETED loses one.
How it works¶
usdview reads buttons when the panel opens and after any change to
the prims; no rig phase touches them. Liveness is the resolve result, not
a flag: pickerScene turns the relationships into target paths and the
model marks a selecting or switching button live only when every target —
or, for a switch, the prim owning the attribute — is a RigExecControl or
RigExecJoint inside the rig named by rigExec:picker:rig, or anywhere on
the stage when the picker names none (pickerModel.py:107-116,
pickerScene.py:345-353, :356-378); a command button the panel
implements is live on its own (pickerModel.py:107-108). A button that
resolves to nothing is not drawn at all, though coverage() still counts
it for the panel's status line (pickerModel.py:241-242, :344-354,
pickerUI.py:1087-1100). A click selects the targets in order, or steps
the switch's attribute to its next label and writes it back as a float,
matching the pose first when the switch drives an IK/FK limb or a space
switch; a switch with more than two labels opens a menu of them instead
(pickerUI.py:1102-1160, :1302-1338, :1439-1464); the hit test is
the button's bounding box rather than its drawn outline, and ui:size is
clamped up to 4 units so a fingertip button is still catchable
(pickerModel.py:23, :57-58, :288-310).
Wiring¶
| Relationship | Points to | Required |
|---|---|---|
rigExec:picker:controls |
The RigExecControl or RigExecJoint prims this button selects, in order. |
no |
rigExec:picker:attribute |
The single attribute a switch edits, as a property path on a control or joint. Mutually exclusive with rigExec:picker:controls; on a plain click the attribute wins. |
no |
rigExec:picker:modeDial |
The attribute rigExec:picker:mode is tested against — the limb's IK/FK dial. |
only with rigExec:picker:mode |
Parameters¶
Node parameters¶
ui:position¶
Type: uniform float2. Default: (0, 0).
Top-left corner in panel units.
ui:size¶
Type: uniform float2. Default: (10, 10).
Width and height in panel units, at least 4. Clicks and marquees test this box, not the drawn outline or ui:rotation.
ui:depth¶
Type: uniform float. Default: 0.
Painter's-algorithm order; higher draws later, on top, and a click finds the topmost. Equal depths keep prim order, and widgetControl buttons draw above every other shape whatever their depth.
ui:rotation¶
Type: uniform float. Default: 0.
Degrees clockwise about the button's own centre.
ui:shape¶
Type: uniform token. Default: "rectangle".
Valid values: rectangle, roundedRectangle, circle, ellipse, hexagon, triangle, trapezoid, polygon, bezier, widgetControl, slider.
Outline. polygon reads ui:polygon, bezier reads
ui:bezier, and every other token is generated from ui:size;
circle fills that box like ellipse. widgetControl draws as a
rectangle, and slider is not drawn.
ui:roundness¶
Type: uniform float. Default: 0.
Corner radius in panel units for rectangle, widgetControl, polygon and trapezoid outlines. roundedRectangle uses at least 35% of the shorter side.
ui:polygon¶
Type: uniform float2[]. Default: [].
Outline vertices for ui:shape = polygon, in panel units relative to ui:position.
ui:bezier¶
Type: uniform float2[]. Default: [].
Cubic control points for ui:shape = bezier, in panel units relative to ui:position, THREE per knot -- on-curve point, out-tangent, in-tangent -- flattened, with each span completed by the following knot's in-tangent. The last knot closes back to the first.
ui:fill¶
Type: uniform color4f. Default: (0.5, 0.5, 0.5, 1).
Interior colour, drawn as authored with no colour-space conversion and with straight (not premultiplied) alpha.
ui:stroke¶
Type: uniform color4f. Default: (0, 0, 0, 0.8).
Outline colour.
ui:strokeWidth¶
Type: uniform float. Default: 1.
Outline width in panel units.
ui:text¶
Type: uniform string. Default: "".
Label drawn inside the button. A command button with no text is labelled with its command.
ui:fontSize¶
Type: uniform float. Default: 8.
Label size in panel units.
ui:bold¶
Type: uniform bool. Default: false.
Label weight.
ui:textAlign¶
Type: uniform token. Default: "center".
Valid values: left, center, right.
Horizontal label alignment inside the button.
ui:textColor¶
Type: uniform color4f. Default: (0, 0, 0, 1).
Label colour.
ui:valueColor¶
Type: uniform color4f. Default: (0, 0, 0, 1).
Colour of the VALUE a switch or dial displays, as
distinct from its label: Foot is drawn in ui:textColor and the
IK beside it in this.
ui:direction¶
Type: uniform token. Default: "top".
Valid values: top, bottom, left, right.
Which edge a triangle points at. On a trapezoid, top and
bottom let the slopes inset the horizontal edges and left and
right the vertical ones; the slope signs choose which edge.
ui:slopeLeft¶
Type: uniform float. Default: 0.
Trapezoid inset at the left end, in panel units. With
ui:direction top or bottom, a positive value insets the top
edge and a negative one the bottom edge; with left or right it
shortens the left edge from the top (positive) or the bottom
(negative).
ui:slopeRight¶
Type: uniform float. Default: 0.
Trapezoid inset at the right end, in panel units. With
ui:direction top or bottom, a positive value insets the top
edge and a negative one the bottom edge; with left or right it
shortens the right edge from the top (positive) or the bottom
(negative).
ui:alternate¶
Type: uniform bool. Default: false.
This button shares a slot with another and is the one the panel hides. Where rigExec:picker:mode and rigExec:picker:modeDial are authored they are the authority and this is ignored: a stacked IK/FK pair is a mode pair, not an alternate.
rigExec:picker:command¶
Type: uniform token. Default: "".
A named action this button runs, instead of selecting or
editing. The panel implements a fixed set and ignores the rest, so
a picker may carry actions a given host cannot perform without
those buttons pretending to work. The usdview panel implements
zero_ctrls, which clears the authored pose channels of the
selected controls and joints (every control when none is
selected), and ctrl_vis, a checkbox that hides or shows the
rig's controls with session-layer visibility opinions.
rigExec:picker:controls¶
Relationship.
The prims this button selects, in order. Targets may be RigExecControls or directly-posed RigExecJoints; the picker treats both as selectable because the avar editor edits both.
rigExec:picker:attribute¶
Relationship.
The single attribute this button edits, for a switch or a dial. Mutually exclusive with rigExec:picker:controls.
rigExec:picker:attributeLabels¶
Type: uniform token[]. Default: [].
Labels for the values rigExec:picker:attribute takes: label i names value i, e.g. ["FK", "IK"] on an IK/FK blend. The button shows the label matching the attribute's CURRENT value, rounded; it never caches the value it was authored with. A click writes the next label's value, or opens a menu when there are more than two.
rigExec:picker:mode¶
Type: uniform token. Default: "".
Valid values: ,, ,.
Show this button only while its limb is in this mode, as
read from rigExec:picker:modeDial: ik at 1, fk at 0, and both
halves show in between. Empty, or no modeDial target, means always
shown, which is right for anything that is not half of an IK/FK
pair.
rigExec:picker:modeDial¶
Relationship.
The attribute rigExec:picker:mode is tested against. Only meaningful when that token is authored.
Example¶
picker.usda has one of each kind in a single panel: b_Shoulder
selects one control, b_Arm selects three at once, b_ArmIkFk switches
ArmParams.avars:ikfk between the labels FK and IK, b_Zero runs the
zero_ctrls command, and backdrop names nothing and is decoration. The
elbow/wrist pair carries rigExec:picker:mode = "fk" and the pole/hand
pair "ik", both dialled off ArmParams.avars:ikfk, so half the limb's
buttons swap out when the switch is clicked.
Open it live with:
Tips¶
- Leave
ui:textunauthored on a command button. The panel falls back to the command's own title (Zero Ctrls) and then dispatches on that LABEL, so a friendlier caption makes the button inert (pickerScene.py:154-155,pickerModel.py:28,:94-97). - Author a switch's attribute on a control or a joint — a custom
avars:ikfkon a params control, connected onward to the blend — because an attribute on a solver prim fails the liveness test and the button is never drawn (pickerModel.py:109-111,:241-242). rigExec:picker:modeis ignored withoutrigExec:picker:modeDial, and a dial resting between 0.001 and 0.999 counts as neither mode, so both halves stay reachable mid-handover (pickerScene.py:164-166,pickerUI.py:1239-1245).