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

Navigate to window > extensions
In the search bar enter Distribute Tool
Locate the Distribute Tool extension and select it.
Select the Enabled toggle to enable the extension.
Select the Check Mark next to auto-load to Load the Extension Automatically on App Start if desired.
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.

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.

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.

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.

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.

Endpoints Info

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

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.