Randomizer Tool¶
Overview¶
The Randomizer Tool is used to add randomized transforms to Xformable objects and/or to select a randomized sub-sample of objects from a larger selection. The Randomizer Tool features live previewing while using the tool UI.
All USD Xformable types are supported for transforms and selections - non-xformable types will not work (scopes, materials, etc.).
Set Up¶
Enable the Extension¶
Using the Randomizer 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 Randomizer
appearing as a menu item, then the Randomizer Tool is loaded.
How to Enable¶
To enable the extension:
Navigate to
window > extensions
In the search bar enter
Randomizer Tool
Locate the Randomizer 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 Randomizer Tool¶
To open the Randomizer Tool, simply select Randomizer
from the Tools
menu. A checkmark will appear when the tool is open.
Clicking on Randomizer
again will close the Randomizer Tool and cancel any current array operations.
Note
The Randomizer Tool operates using your current selection; if you have something selected when opening the Randomizer Tool it will begin working immediately. This could cause a temporary hang if opening the Randomizer Tool with a large amount of objects or dense meshes selected.
Features¶
The standard features of the Randomizer Tool.
Live Preview¶
The preview
feature allows users to see their changes in real-time, however, if you plan on manipulating many objects (thousands+), or you are working with heavy meshes, you may want to turn preview off to help improve performance in the viewport.
Selection¶
The top collapsable section of the UI provides controls for randomized selection. The Selection feature allows users to randomly select a subset/percentage of their current selection, from 0 to 100%. You can also generate a new seed to get a new randomized selection.
Feature |
Description |
---|---|
Enabled |
Toggle this feature on or off.
|
Select Subset % |
The percentage of the original selection to randomly select, between 0 and 100, inclusive.
|
Seed |
The random seed to use for this operation.
|
Seed Refresh Button |
Generate a new random seed.
|
Transform¶
The bottom collapsable section of the UI provides controls for randomized transforms. The Transform feature allows users to define random number ranges on a per-axis basis for each translation, rotation, and scale. Random numbers will be generated within these ranges (inclusive), and applied as offsets to the selected objects.
Feature |
Description |
---|---|
Enabled |
Toggle this feature on or off.
|
Translate |
The X, Y, Z axis value ranges for translation. Min (lower), Max (upper)
|
Rotate |
The X, Y, Z axis value ranges for rotation. Min (lower), Max (upper)
|
Scale |
The X, Y, Z axis value ranges for scale. Min (lower), Max (upper)
|
Seed |
The random seed to use for this operation.
|
Seed Refresh Button |
Generate a new random seed.
|
Note
Transformations are applied relative to the selected objects’ local transform.
Range Linking¶
The Chain Link
icon next to the Transform attributes represents a toggle for Range Linking
. Clicking on the icon will cycle through 3 specific range linking methods. The default setting is unique
(grey).
Range Link |
Description |
---|---|
Unique (Grey) |
Each axes’ range is individually set and managed. The ranges are not connected.
|
Relative (Orange) |
When changing the values on any min/max row, the other 2 axes’ min/max values change proportionally.
|
Uniform (Blue) |
Min and max rows are linked together and use the same values.
|
Below is an example of each link type and how they work.
Note
When Range Linking is set to Uniform on the scale field, objects will scale uniformly. This is the only time where the same random value is used for all 3 axes.
Note
When clicking on the link icon, the link setting loops between each of the link types. The order is: Unique -> Relative -> Uniform
Transform Field Toggles¶
Using the checkboxes to the left of each Transform attribute, users can quickly toggle on or off individual attributes while retaining their values in that attribute’s number fields.
Note
When an attribute is disabled, the Range Linking buttons and the number fields can still be interacted with and manipulated.
Options¶
This section features options which allow the user to customize how the tool functions, such as remembering last values for quick iteration.
Remember Last Values¶
When Remember Last Values is enabled
, the previously entered randomizer values are remembered when the Randomizer Tool window is opened again, or after clicking Apply. If disabled
the Randomizer Tool values are reset back to the defaults every time the tool is opened, or after each Apply.
Note
Remember Last Values is UI specific and is not available when using the Randomizer Tool via command/code.
Buttons¶
The buttons at the bottom of the Randomizer Tool UI.
Button |
Description |
---|---|
Cancel |
Cancels any active operations, reverts any previewed changes, and closes the Randomizer Tool.
|
Reset All |
Resets the Randomizer Tool to default values and rebuilds the preview if preview is enabled.
|
Apply |
Applies the Randomizer Tool settings. Keeps the window open and refreshes any enabled operations.
|
Apply & Close |
Applies the Randomizer Tool settings and closes the window.
|
Programming Guide¶
The Randomizer Tool can also be used without the UI via Omniverse Commands. This way, other scripts and extensions can use the core Randomizer logic to randomize objects without having to use the UI.
The Randomizer contains two callable commands: RandomizeSelectionCommand
and RandomizeTransformsCommand
.
Note
As when using the UI, both commands support all USD Xformable types, this includes objects such as lights, meshes, xforms, and skeletons. Non-xformables such as scopes and materials are not supported.
RandomizeSelectionCommand¶
The RandomizeSelectionCommand
is used to randomly select a subset/percentage from a provided list of objects. It expects the following arguments:
Argument |
Description |
---|---|
target_prim_paths (list) |
The list of prim paths to operate on. Expects paths (str or Sdf.Path)
|
percent_to_select (int) |
A percent of the provided prim paths to randomly select, between 0 and 100, inclusive.
|
Optional Argument |
Description |
---|---|
seed (int) |
The random seed to use for this operation. If none is given one will be generated.
|
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 RandomizeSelectionCommand
and pass in a list of target prim paths, a selection percentage, and a specific seed to use for the randomizer.
import omni.kit
import omni.usd
from pxr import Gf
import omni.tools.randomizer
usd_context = omni.usd.get_context()
selection = usd_context.get_selection()
selected_prim_paths = selection.get_selected_prim_paths() # Get the selected prim paths
percent = 65 # Percentage to select
seed = 45381 # Use a custom random seed
omni.kit.commands.execute(
"RandomizeSelectionCommand",
target_prim_paths=selected_prim_paths,
percent_to_select=percent,
seed=seed
)
RandomizeTransformsCommand¶
The RandomizeTransformsCommand
is used to add randomized transforms to objects. It expects the following arguments:
Argument |
Description |
---|---|
target_prims (list) |
The list of prims to array. Expects prims, not prim paths.
|
Optional Argument |
Description |
---|---|
translate_ranges (tuple(Gf.Vec2d, Gf.Vec2d, Gf.Vec2d)) |
Min and Max value range for X,Y,Z axes
|
rotate_ranges (tuple(Gf.Vec2d, Gf.Vec2d, Gf.Vec2d)) |
Min and Max value range for X,Y,Z axes
|
scale_ranges (tuple(Gf.Vec2d, Gf.Vec2d, Gf.Vec2d)) |
Min and Max value range for X,Y,Z axes
|
seed (int) |
The random seed to use for this operation. If none is given one will be generated.
|
uniform_scaling (bool) |
If True, the provided scale ranges will be set to the same min and max values, and scaling applied to the selected prims will be uniform on a per-prim basis.
|
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 RandomizeTransformsCommand
and pass in a list of target prims and optional transform values.
"""
This is a simple example that uses omni.tools.randomizer to add random translation values to a list of selected prims.
"""
import omni.kit
import omni.usd
from pxr import Gf
import omni.tools.randomizer
usd_context = omni.usd.get_context()
stage = usd_context.get_stage()
selection = usd_context.get_selection()
selected_prim_paths = selection.get_selected_prim_paths() # Get the selected prim paths
prims = [stage.GetPrimAtPath(path) for path in selected_prim_paths] # Convert to a list of prims (Usd.Prim)
trans_ranges = (Gf.Vec2d(0), Gf.Vec2d(0), Gf.Vec2d(-50, 50)) # Create some random translate ranges. In this example, on the Z axis only.
omni.kit.commands.execute("RandomizeTransformsCommand", target_prims=prims, translate_ranges=trans_ranges)
The RandomizeTransformsCommand
only requires a list of prims to operate. All transform ranges are optional; if a specific transform range is not provided, eg. scale, default values will be used (0,0 for all axis ranges).
Below is an example code block where we provide more arguments to the RandomizeTransformsCommand
to create a more complex result.
import omni.kit
import omni.usd
from pxr import Gf
import omni.tools.randomizer
usd_context = omni.usd.get_context()
stage = usd_context.get_stage()
selection = usd_context.get_selection()
selected_prim_paths = selection.get_selected_prim_paths() # Get the selected prim paths
prims = [stage.GetPrimAtPath(path) for path in selected_prim_paths] # Convert to a list of prims (Usd.Prim)
trans_ranges = (Gf.Vec2d(0), Gf.Vec2d(0), Gf.Vec2d(-50, 50)) # Create some random translate ranges. In this example, on the Z axis only.
rot_ranges = (Gf.Vec2d(0), Gf.Vec2d(-30, 30), Gf.Vec2d(0)) # Create some random rotate ranges. In this example, on the Y axis only.
scale_ranges = (Gf.Vec2d(0), Gf.Vec2d(-1, 1), Gf.Vec2d(0)) # Create some random scale ranges. In this example, on the Y axis only.
seed = 6187 # Use a custom random seed
uniform_scaling = True # Set uniform scaling to true - the selected objects will be randomly scaled uniformly on all 3 axes
omni.kit.commands.execute(
"RandomizeTransformsCommand",
target_prims=prims,
translate_ranges=trans_ranges,
rotate_ranges=rot_ranges,
scale_ranges=scale_ranges,
seed=seed,
uniform_scaling=uniform_scaling
)
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.
Selected objects can be manually manipulated to update their original positions while the Randomizer tool is open and live previewing.
Limitations¶
Objects with time sampled transform ops are ignored and will not produce results when using the Randomizer Tool UI or command.
If objects are manually moved in the viewport while preview is enabled, their current previewed positions are what is captured in the undo/redo history. So if you undo and redo after doing so, the objects will be in their previewed positions which may be undesirable. It is recommended to disable preview or close the Randomizer tool UI when manually repositioning your target objects.
Randomizer Tool UI values can not be keyframed for animation.