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:
Navigate to
window > extensions
In the search bar enter
Array Tool
Locate the Array 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 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.
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.