Pivot Tool
The Pivot Tool is an extension that allows you to adjust the pivot of a Prim. You can use this tool to more efficiently layout your stages. It comes with its own UI panel, which provides simple controls to position a pivot relative to the extents of its Prim’s bounding box. In addition, it offers several shortcuts for common pivot placement, as well as the option to set a pivot’s position to the world position of any Stage Prim.
Tip
The Pivot Tool cannot modify joints.
Note
Pivots are automatically added at the center of the bounding box, unless specified otherwise in its options. The option to control this setting is found in the tool UI under “Auto-Center Added Pivots”.
Access the Pivot Tool
The Pivot Tool can be accessed in two ways:
Go to Main menu > Tools
Select a Prim on your Stage and click the arrow dropdown that appears below the Prim. This displays the Manipilator Toolbar. Press the Selection Pivot button in the toolbar and click on Pivot Tool.
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 all 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 prims with time sampled transform ops or attributes (points, vertices, etc.)
Prims need to have a valid full XformOp stack (TRS) or a Transform XformOp.
Prims without computable bounding boxes such as xforms, lights, and cameras must have their pivot position edited manually via the transform property window.
Does not work on light or camera prims.