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.
Pivot Tool Menu#
The Pivot Tool Menu allows you to add, remove, and re-position the pivot of a selected Prim. It’s important to note that in order to be able to modify a Prim’s pivot, it needs to have the pivot transform attribute pivotOp 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)
|
Set Pivot position to … |
Opens a menu with additional options to set the pivot position, as well as a shortcut to reset the Selection Pivot setting to ‘Authored’
|
The “Set Pivot position to …” Menu provides several additional options to set the Pivot position on the current Prim selection:
Option |
Result |
|---|---|
Bounding Box Base (individual Prims) |
Moves all Pivots to their respective Prim’s Bounding Box’s base
|
Bounding Box Center (Selection) |
Moves all Pivots to the center of the current selection’s Bounding Box
|
Bounding Box Base (Selection) |
Moves all Pivots to the base of the current selection’s Bounding Box
|
Center (Selection) |
Moves all Pivots to the center of the current selection. The center of the selection is based on the collective Pivot positions in the selection.
|
Current Selection Pivot: … |
Contextual Option (only available if Selection Pivot setting is not ‘Authored Pivot’, and at least one Viewport is visible). Moves all Pivots to the current Selection Pivot position as defined in the Selection Pivot settings.
|
Reset Selection Pivot to ‘Authored Pivot’ |
Shortcut to quickly change the Selection Pivot setting to ‘Authored Pivot’, to properly reflect the actual Prim pivot attribute’s position.
|
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
|
Apply Selection Pivot position on Add |
Automatically applies the position currently defined by the Selection Pivot setting when adding a Pivot (this overrides the above Auto-Center option)
|
Set Selection Pivot to ‘Authored’ on Add |
Automatically resets the Selection Pivot setting to ‘Authored Pivot’ when adding a Pivot to a Prim
|
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.