Pivot Tool¶
The Pivot Tool is an extension that allows the user to adjust the pivot of a prim.
Pivot Tool Context Menu¶
The Pivot Tool context menu can be accessed from the collapsible manipulator toolbar displayed in the Viewport beneath the selected prim.
Option |
Result |
|---|---|
Add Pivot |
Adds transform properties for the pivot of the selected prim (prim must have a full set of TransformOps)
|
Reset Pivot |
Resets pivot to initial position (0, 0, 0)
|
Pivot to BBox Center |
Moves pivot to the center of the bounding box
|
Pivot to BBox Base |
Moves pivot to the base of the bounding box
|
Pivot Tool … |
Opens the Pivot Tool Menu window
|
Note
The Pivot Tool cannot modify joints.
Note
Pivots are automatically added at the center of the bounding box. The option to control this setting is found in the tool UI under “Auto-Center Added Pivots”.
Pivot Tool Menu¶
The Pivot Tool Menu allows you to add, remove, and reposition the pivot of a selected prim. A pivot cannot be modified unless the prim has the pivot transform attributes added and enabled.
Pivot Position (Relative to Bounding Box)
Moving the sliders allows you to adjust the position of the pivot within the extents of the bounding box, expressed as values from -1 to 1 (0 by default)
Button |
Result |
|---|---|
Center Pivot |
Moves pivot to the center of the bounding box
|
Reset Pivot |
Resets pivot to initial position (0, 0, 0)
|
World Position to Pivot
Allows you to move the pivot of the selected prim to the world position of a source prim
Button |
Result |
|---|---|
Pick Source |
Allows you to select a prim from the viewport or stage (Records the position of the prim at the time of selection)
|
Set Pivot |
Move the pivot of the selected prim to the recorded position of the source prim
|
Note
The pivot can be moved outside of the extents of the bounding box by manually setting the Pivot Position fields to a value outside of the -1 to 1 range, by modifying the pivot transform fields in the Properties window or by aligning it to the world position of another prim.
Option |
Result |
|---|---|
Maintain Position |
Moving the pivot will counter-offset the transforms of the prim
|
Bounding Box includes Child Prims |
Bounding box includes any mesh that is a child of the prim
|
Auto-Enable Pivots on Edit |
Automatically enable any currently disabled PivotOps when editing the Pivot position values
|
Auto-Center Added Pivots |
Automatically center added pivots at the center of the bounding box
|
Programming Guide¶
The Pivot Tool can also be used without the UI via Omniverse Commands. This way, other scripts and extensions can adjust the pivot of objects without having to load the extension or use the UI.
The PivotToolAddPivot command is used to add the Pivot transform to a given set of prims. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
Optional Argument |
Description |
|---|---|
center_pivot (bool) |
Added pivots will be automatically centered in the bounding box.
|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolRemovePivot command is used to remove the Pivot transform to a given set of prims. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolUpdatePivot command is used to update the PivotOp transforms of a given set of prims. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
new_pivot_position (Gf.Vec3d) |
New Pivot position to set all Pivots to.
|
use_normalized_position (bool) |
Position values are normalized and relative to each Prim’s bounding box. (True by default)
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
auto_enable_pivots (bool) |
Automatically enable any disabled PivotOps. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolSetPivotFromWorldPosition command is used to set the Pivot position of a given set of prims from an arbitrary World Position. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
world_position (Gf.Vec3d) |
World position to apply to each PivotOp.
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
auto_enable_pivots (bool) |
Automatically enable any disabled PivotOps. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolSetPivotFromPrimWorldPosition command is used to set the Pivot position of a given set of prims from an arbitrary World Position. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
world_position_prim_path (str) |
Path of prim whose world position to apply to each PivotOp.
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
auto_enable_pivots (bool) |
Automatically enable any disabled PivotOps. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolSetPivotToBoundingBoxBase command is used to set the Pivot position of a given set of prims to the bottom center of their respective bounding boxes. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
auto_enable_pivots (bool) |
Automatically enable any disabled PivotOps. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolSetPivotToBoundingBoxCenter command is used to set the Pivot position of a given set of prims to the center of their respective bounding boxes. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
auto_enable_pivots (bool) |
Automatically enable any disabled PivotOps. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
The PivotToolResetPivot command is used to reset the Pivot position of a given set of prims to zero values. It expects the following arguments:
Argument |
Description |
|---|---|
prim_paths (list[str]) |
The list of prims to array. Expects prim paths, not prims.
|
maintain_position (bool) |
Modify TranslateOp to avoid drift. (True by default)
|
bbox_includes_child_prims (bool) |
Bounding box is extended to include Xformable child Prims. (True by default)
|
auto_enable_pivots (bool) |
Automatically enable any disabled PivotOps. (True by default)
|
Optional Argument |
Description |
|---|---|
context (str) |
The USD context where this command should be used - allows for this command to be used by multiple USD contexts simultaneously.
|
Below is an example code block where we call the PivotToolAddPivot and pass in the expected target prims. Then we call PivotToolSetPivotFromWorldPosition and set the pivot of the target prims to a set of world coordinates.
"""
This is a simple example that uses omni.tools.pivot to add a pivot to a list of prims via command, then move the pivot to a given position in the world.
"""
from pxr import Gf
prims = []
prims.append("/World/Cube")
pos = Gf.Vec3d(10, 10, 10)
omni.kit.commands.execute("PivotToolAddPivot", prim_paths=prims)
omni.kit.commands.execute("PivotToolSetPivotFromWorldPosition", prim_paths=prims, world_position=pos)
Features Supported¶
Works on most USD Xformable types, including xforms, meshes, shapes, and skeletons.
Works on all prim types, including instanceable, referenced, and payloads.
Supports undo and redo of operations, both from the UI and via command.
Limitations¶
Does not work on light or camera prims.
Prims need to have a valid full XformOp stack.