Distribute Tool

Overview

The Distribute Tool is used to distribute selected prims along any axis. Prims can be distributed between two endpoints or within a specific bounding box area. A variety of options exist to modify how the selected prims are distributed for the most desired results.

Set Up

Enable the Extension

Using the Distribute Tool begins with enabling the extension.

Check if it’s Enabled

You can quickly see if the extension is already loaded by looking at the menu bar. If your menu bar contains the Tools menu with Distribute appearing as a menu item, then the Distribute Tool is loaded.

_images/ext_distribute-tool_submenu_off.jpg

How to Enable

To enable the extension:

_images/ext_distribute-tool_extension_window.jpg
  1. Navigate to window > extensions

  2. In the search bar enter Distribute Tool

  3. Locate the Distribute Tool extension and select it.

  4. Select the Enabled toggle to enable the extension.

  5. Select the Check Mark next to auto-load to Load the Extension Automatically on App Start if desired.

  6. Close the Extensions Panel.

At this point the extension should be enabled and you should now see the tool menu item appear in your menu bar.

User Guide

Open the Distribute Tool

To open the Distribute Tool, simply select Distribute from the Tools menu. A checkmark will appear when the tool is open.

Clicking on Distribute again will close the Distribute Tool.

_images/ext_distribute-tool_submenu_on.jpg

Features

The standard features of the Distribute Tool.

Distribution Axes

The axes buttons are clicked on to apply a distribution operation to a current valid selection. Distribution is supported on all 3 axes: X, Y, and Z.

_images/ext_distribute-tool_axes.jpg

Feature

Description

X

Click to distribute along the X axis.

Y

Click to distribute along the Y axis.

Z

Click to distribute along the Z axis.

Note

Distribution is applied in world space. If a parent and child are selected while running a distribute operation, their world positions will be handled individually.

Distribute Between

The distribute between drop-down menu allows users to choose how they would like to distribute the selected prims, ie. which bounds to distribute between.

_images/ext_distribute-tool_distribute_between.jpg

Feature

Description

Axis Min/Max

Determines the objects with the min/max translation values on the given distribution axis and distributes the remaining objects between them.

Endpoints

Uses the selected endpoints and distributes the remaining objects between them.

Distribute Using

The distribute using drop-down menu allows users to choose how selected prims will be processed for distribution spacing calculations.

_images/ext_distribute-tool_distribute_using.jpg

Feature

Description

Pivots

Uses the mesh origin or pivot (if available) of the selected objects to determine the spacing of the distribution.

BBox Centers

Uses the centroid of the selected objects to determine the spacing of the distribution. This method uses the combined Centroid if multiple boundable objects are nested.

Options Menu

The options menu features options which allow the user to customize how the tool functions.

_images/ext_distribute-tool_options.jpg

Skip Hidden Prims

When enabled, the Skip Hidden Prims option will skip hidden prims (visibility disabled) when applying distribution calculations.

Endpoint Options

The endpoint options provides additional functionality when the Distribute Between method is set to Endpoints, such as choosing between different endpoint selection methods and toggling graphical overlays.

_images/ext_distribute-tool_endpoint_options.jpg

Endpoints Info

When enabled, the selected endpoints’ paths will be displayed in the tool UI.

_images/ext_distribute-tool_endpoints_info.jpg

Endpoints Viewport Overlay

When enabled, the endpoints will be displayed with a pink overlay in the viewport.

_images/ext_distribute-tool_endpoint_overlays.jpg

Endpoints Selection Method

This drop-down allows the user to choose how the endpoint prims are decided based on selection order.

_images/ext_distribute-tool_endpoint_selection_method.jpg

Feature

Description

FF

First Two Selected. The first two objects selected will be used as the endpoints for distribution.

FL

First and Last Selected. The first and last objects selected will be used as the endpoints for distribution.

LL

Last Two Selected. The last two objects selected will be used as the endpoints for distribution.

Programming Guide

The Distribute Tool can also be used without the UI via Omniverse Commands. This way, other scripts and extensions can use the core Distribute logic to distribute a list of provided prims along an axis.

The DistributeToolDistributeTranslateOnAxisCommand is used to distribute a list of prims via command. It expects the following arguments:

Argument

Description

prim_paths (list)

The list of prim paths to distribute.

axis (omni.tools.distribute.constants.DistributionAxis)

The world axis to distribute the prims on. Also supports int values (0 = X, 1 = Y, 2 = Z).

Optional Argument

Description

distribute_between (omni.tools.distribute.constants.DistributeBetweenType)

Determines if distribution occurs between any two prims with the min/max translate value on the given distribution axis, or the endpoints passed via argument.

distribute_using (omni.tools.distribute.constants.CenterType)

Determines if the distribution occurs using the prims’ current Bounding Box center or Pivot/Mesh origin.

endpoint_a_prim_path (str)

The prim path for Endpoint A. Will be ignored if distribute_between is set to Axis Min/Max.

endpoint_b_prim_path (str)

The prim path for Endpoint B. Will be ignored if distribute_between is set to Axis Min/Max.

context (str)

Specify the USD context. Allows this command to be used in multiple USD contexts.

skip_hidden_prims (bool)

If True, prims in the distribution list with their visibility turned off will be ignored.

Below is an example code block where we call the DistributeToolDistributeTranslateOnAxisCommand and pass in the expected values and prims.

"""
This is a simple example that uses omni.tools.distribute to distribute selected prims on the X axis between two endpoints.
"""

import omni.kit
import omni.usd
from omni.tools.distribute import constants as d_c

usd_context = omni.usd.get_context()
selection = usd_context.get_selection()

selected_prim_paths = selection.get_selected_prim_paths()   # Get the selected prim paths
endpoint_a = "/World/Cube"                                  # Set Endpoint A
endpoint_b = "/World/Cube_01"                               # Set Endpoint B

axis = d_c.DistributionAxis.X                               # Set the distribution axis to the X axis
distribute_between = d_c.DistributeBetweenType.ENDPOINTS    # Distribute between two endpoints
distribute_using = d_c.CenterType.BBOX_CENTER               # Use BBox Centers for spacing

omni.kit.commands.execute(
    "DistributeToolDistributeTranslateOnAxisCommand",
    prim_paths=selected_prim_paths,
    axis=axis,
    distribute_between=distribute_between,
    distribute_using=distribute_using,
    endpoint_a_prim_path=endpoint_a,
    endpoint_b_prim_path=endpoint_b,
)

In this example we will pass an int into the axis field instead of the expected enum, change the distribute_between value to axis min/max, and use pivots for the distribute_using value.

import omni.kit
import omni.usd
from omni.tools.distribute import constants as d_c

usd_context = omni.usd.get_context()
selection = usd_context.get_selection()

selected_prim_paths = selection.get_selected_prim_paths()   # Get the selected prim paths

axis = 2                                                    # Set the distribution axis to the Z axis using an int
distribute_between = d_c.DistributeBetweenType.AXIS_MIN_MAX # Distribute between the axis min/max
distribute_using = d_c.CenterType.PIVOTS                    # Use Pivots for spacing

omni.kit.commands.execute(
    "DistributeToolDistributeTranslateOnAxisCommand",
    prim_paths=selected_prim_paths,
    axis=axis,
    distribute_between=distribute_between,
    distribute_using=distribute_using,
)

Features Supported

  • Works on all USD Xformable types, this includes xforms, meshes, lights, cameras, skeletons, etc.

  • Works on all prim types, including instanceable, referenced, and payloads.

  • Supports nested prims

  • Supports objects with pivots and non-zero pivots.

  • Supports undo and redo of operations, both from the UI and via command.

Limitations

  • Objects with time sampled transform ops are ignored and will not produce results when using the Distribute Tool UI or command.

  • Distribute Tool UI values can not be keyframed for animation.