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.

../_images/kit_tool_pivot_context_menu.png

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.

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.

../_images/kit_tool_pivot_menu.png
  • 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-Apply World Position on Copy

Pivot is updated automatically upon selecting the world position of a source 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

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.