Array Tool

Overview

The Array Tool is used to create an array (copies) of objects in multiple dimensions. This allows users to quickly create copies of prims in a repeating fashion by defining incremental translation, rotation, and scale values in three dimensions.

All USD Xformable types are supported - non-xformable types will not work (scopes, materials, etc.).

Set Up

Enable the Extension

Using the Array 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 Array appearing as a menu item, then the Array Tool is loaded.

How to Enable

To enable the extension:

1. Navigate to window > extensions

2. In the search bar enter Array Tool

3. Locate the Array 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 Array Tool

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

Clicking on Array again will close the Array Tool and cancel any current array operations.

Note

The Array Tool operates using your current selection; if you have something selected when opening the Array Tool it will begin working immediately. This could cause a temporary hang if opening the Array Tool with a dense mesh(es) selected, or with high counts set in the Array Tool from a previous operation.

Features

The standard features of the Array Tool.

1D & Increments

The top portion of the Array Tool UI contains the 1D incremental value controls. By default, transformation values set in the Array Tool represent incremental values, where each copy is transformed by an incremental amount from the previous copy. These 1D controls will create a single array - dimension - of copies.

The preview feature allows users to see their changes in real-time, however, if you plan on creating many prims (thousands+), or you are working with heavy meshes, you may want to turn preview off to help improve performance in the viewport.

Feature	Description
Count	The number of 1D copies to create. Includes the original selection.
Preview	Toggle the viewport preview for array operations.
Translate	The translation increment between each array element.
Rotate	The rotational increment between each array element.
Scale	The scale increment between each array element.

Note

Transformations are applied relative to the selected prim. If multiple prims are selected, transformations occur from the first prim selected.

Total Mode

The T icon next to the transform rows represents a toggle for enabling/disabling Total Mode. In Total Mode, the values in the UI change to represent the total value of the transformations at the endpoint of the array. So if the user wanted to array 10 prims up to 1000cm, they could easily switch to Total Mode and set translate to 1000cm, instead of trying to figure out individual increments.

Scale Linking

The Chain Link icon next to Scale represents the toggle for enabling/disabling Scale Linking. When Scale Linking is enabled, changing any scale value will change the other two scale values by a proportional amount.

In the example below, we changed the X axis scale from 0.05 to 0.1, and the Y and Z axes scaled proportionally.

Additional Dimensions

The lower portion of the Array Tool UI contains the 2D and 3D array controls. The 2D and 3D controls allow users to copy the previous dimension in an additional second and third dimension, which can be used to create some truly complex patterns. These dimensions only support translational transformations.

Feature	Description
2D	The number of copies to make of the first dimension, and the translational increments to use.
3D	The number of copies to make of the second dimension, and the translational increments to use.

Options

The Array Tool features a variety of options which allow the user to customize how the tool functions, such as remembering last values for quick iteration, or creating instances instead of copies for better performance.

Creation Type

These options let the user decide what kind of copies are created - are they exact copies, or instances? Create Copies is the default selection.

Option	Description
Create Instances	Create array elements as instances.
Create Copies	Create array elements as copies.

Source Selection As

The Array Tool supports arraying of multiple prims/selections at once, and Source Selection let’s the user decide how their selection should be copied. Single Stamp is the default selection.

Option	Description
Single Stamp	Arrays the entire selection as a single array stamp element for every copy.
Ordered Sequence	Arrays selected objects individually based on selection order.
Random Sequence	Arrays selected objects individually in random order.

Note

If multiple prims are selected, transformations occur from the first prim selected.

Random Sequence Seed

The Random Sequence Seed is enabled when Random Sequence is chosen for the source selection mode. The user can generate a new random seed for the array order by clicking on the refresh icon, or by manually entering a new seed.

Group Results

Groups the array results under a new xform named Group. The resulting group is a sibling of the selected prim who is highest in the stage hierarchy. Group Results is disabled by default.

Follow Rotation

When Follow Rotation is enabled, copies are rotated from the previous copy’s position. This allows arrays to bend and curve in unique ways. Follow Rotation is disabled by default.

Note

By default, copies are rotated around their local position when Follow Rotation is disabled.

Remember Last Values

When Remember Last Values is enabled, the previously entered array values are remembered when the Array Tool window is opened again. If disabled the Array Tool values are reset back to the defaults every time the tool is opened.

Note

Remember Last Values is UI specific and is not available when using the Array Tool via command/code.

Auto Select Created Objects

Auto Selects the created objects when enabled. Can be used in conjunction with Group Results to auto-select the created group.

Buttons

The buttons at the bottom of the Array Tool UI.

Button	Description
Cancel	Cancels the array operation, deletes any previewed changes, and closes the Array Tool.
Reset All	Resets the Array Tool to default values and rebuilds the preview if turned on.
Apply	Applies the Array Tool settings and closes the Array Tool.

Programming Guide

The Array Tool can also be used without the UI via Omniverse Commands. This way, other scripts and extensions can use the core Array logic to create arrays of objects without having to load the extension or use the UI.

The CreateArrayCommand is used to create arrays via command. It expects the following arguments:

Argument	Description
target_prims (list)	The list of prims to array. Expects prims, not prim paths.
array_values (dict)	The values to use to construct the array. Expects a dictionary matching the one seen in ArrayParams.

Optional Argument	Description
usd_context_name (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 CreateArrayCommand and pass in the expected array values and target prims.

"""
This is a simple example that uses omni.tools.array to create an array of prims via command.
"""

import omni.kit
import omni.usd
from pxr import Gf
from omni.tools.array import array_const, Extension

values = Extension.construct_new_array()
values[array_const.INC_TRANSLATE] = Gf.Vec3d(125,0,0)

stage = omni.usd.get_context().get_stage()

prims = []
prims.append(stage.GetPrimAtPath("/World/Cube"))

omni.kit.commands.execute("CreateArrayCommand", target_prims=prims, array_values=values)

The CreateArrayCommand expects a dictionary of specific values for the array values. The easiest way to construct a new array is to use the construct_new_array() method from the Extension class as seen above. To modify these values, it is best to import the array_const module from the extension (omni.tools.array), as all array names and values are already defined in this utility class.

Below is an example code block where we create a new array values dictionary, and modify those values from their defaults using array_const. See the array_const.py module in the extension for more information about names and types.

import omni.kit
import omni.usd
from pxr import Gf
from omni.tools.array import array_const, Extension

values = Extension.construct_new_array()

# Change some default values
values[array_const.COUNT] = 25                         # Make 25 copies
values[array_const.INC_TRANSLATE] = Gf.Vec3d(125,0,0)  # Translate 125 in X per copy
values[array_const.INC_ROTATE] = Gf.Vec3d(0,5,0)       # Rotate 5 degrees around Y per copy
values[array_const.TWO_D_COUNT] = 5                    # Create 5 copies of the 1D array
values[array_const.TWO_D_OFFSET] = Gf.Vec3d(0,150,0)   # Translate each 1D array copy 150 in the Y axis.

# Set some Options
values[array_const.CREATE_TYPE] = array_const.CreateType.INSTANCES  # Create instances instead of copies
values[array_const.ARRAY_GROUP_RESULT] = True                       # Group results
values[array_const.REORIENT_ROTATION] = True                        # Follow Rotations

stage = omni.usd.get_context().get_stage()

# Pass in two objects to operate on
prims = []
prims.append(stage.GetPrimAtPath("/World/Cube"))
prims.append(stage.GetPrimAtPath("/World/Sphere"))

omni.kit.commands.execute("CreateArrayCommand", target_prims=prims, array_values=values)

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.

• Can work on Xformables missing some or all transform ops.

• Supports 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 Array Tool UI or command.

• If a parent and it’s child prim are both provided to the array tool, only the parent prim will be considered for operations to prevent doubling up on copies.

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