Randomizer Tool
Overview
The Randomizer Tool is used to add randomized transforms to Xformable objects, to select a randomized sub-sample of objects from a larger selection, and/or randomly assign or replace materials on selected prims. The Randomizer Tool features live previewing while using the tool UI.
All USD Xformable types are supported for transforms and selections; materials are supported for any prim that supports material binding - 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 collapsible 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 second collapsible 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.
Materials
The third collapsible section of the UI provides controls for randomized materials. The Materials feature allows users to define a list of materials from the stage that will be randomly assigned to any selected objects that support material binding. Additionally, users can choose to replace specific materials with a randomly selected material by populating the Replace
tab with the materials to replace.
Feature |
Description |
---|---|
Enabled |
Toggle this feature on or off.
|
Materials tab |
The list of materials to use.
|
Replace tab |
The list of materials to replace on selected objects.
|
Add |
Open a stage materials window. Add selected materials to the active tab’s list.
|
Remove (X) |
Remove the hovered/selected material from the active tab’s list.
|
Seed |
The random seed to use for this operation.
|
Seed Refresh Button |
Generate a new random seed.
|
Note
The Add button opens up a stage dialog that is specifically filtered to only show materials.
Note
You can also drag materials from the stage directly into the material list
Note
You can remove individual materials by hovering over them and clicking the X
Material Replacement
The Replace
tab can be populated with materials to be replaced by materials in the Materials
tab. Any occurrence of a material in the Replace tab on the selected prims can be replaced by any material in the Materials tab. This can be useful for targeted replacement of specific materials instead of just replacing all materials on all selections.
The Shared Material Replacement
and Include Children - Materials
options can be used to further extend the replace materials feature.
Note
Both tabs need to be populated in order for the Replace feature to work. If either tab is empty the material randomizer will revert to default functionality.
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.
Include Children - Materials
When Include Children - Materials is enabled
, all valid children of the selected prim(s) are also included in material operations. When disabled
only the selected prims will be considered for material operations.
This is useful if you have a complex hierarchy and don’t want to manually select all child prims individually. You can just select the top of the hierarchy and all children will be automatically included.
Note
This option applies to all features in the materials section of the Randomizer.
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 three callable commands: RandomizeSelectionCommand
, RandomizeTransformsCommand
, and RandomizeMaterialsCommand
.
Note
As when using the UI, these commands support all USD Xformable types, this includes objects such as lights, meshes, xforms, and skeletons. Material randomization will only apply to objects that support material binding. 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
)
RandomizeMaterialsCommand
The RandomizeMaterialsCommand
is used to bind randomized materials to objects. It expects the following arguments:
Argument |
Description |
---|---|
target_prims (list) |
The list of prims to bind to. Expects prims, not prim paths.
|
material_list (list) |
The list of materials to bind to the selected prims. Expects paths, not prims.
|
Optional Argument |
Description |
---|---|
replace_material_list (list) |
The list of materials to replace with materials from the material_list. Expects paths, not prims.
|
shared_material_replacement (bool) |
Replace repeated occurrences of the same material with the same random material. If false, use a new random material for each replace occurrence.
|
include_children (bool) |
Include all valid child prims of the provided target_prims in material randomization/replace calculations.
|
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 RandomizeMaterialsCommand
and pass in a list of target prims and a list of material paths.
"""
This is a simple example that uses omni.tools.randomizer to add random materials 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)
# Get all materials from the Looks folder in World
material_prims = stage.GetPrimAtPath("/World/Looks").GetAllChildren() # Collect all the materials in the stage under /World/Looks
material_paths = [x.GetPath() for x in material_prims] # Convert to a list of paths
omni.kit.commands.execute("RandomizeMaterialsCommand", target_prims=prims, material_list=material_paths)
And here is a more complex example where we replace a specific material with some options enabled.
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 - select the top level of prim hierarchies
prims = [stage.GetPrimAtPath(path) for path in selected_prim_paths] # Convert to a list of prims (Usd.Prim)
# Get all materials from the Looks folder in World
material_prims = stage.GetPrimAtPath("/World/Looks").GetAllChildren() # Collect all the materials in the stage under /World/Looks
material_paths = [x.GetPath() for x in material_prims] # Convert to a list of paths
replace_paths = ["/World/Replace_Looks/Birch"] # A list of material paths to look for and replace on the selection
shared_material_replacement = True # Enable this option
include_children = True # Enable this option
omni.kit.commands.execute(
"RandomizeMaterialsCommand",
target_prims=prims,
material_list=material_paths,
replace_material_list=replace_paths,
shared_material_replacement=shared_material_replacement,
include_children=include_children
)
Features Supported
Selection and Transform work on all USD Xformable types, this includes xforms, meshes, lights, cameras, skeletons, etc.
Material randomization is supported for all USD Xformable types that support material binding.
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.
Replace found materials on selected prims.
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.