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.

../_images/ext_randomizer-tool_submenu_off.JPG

How to Enable¶

To enable the extension:

../_images/ext_randomizer-tool_extension_window.JPG

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.

../_images/ext_randomizer-tool_submenu_on.JPG

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.

../_images/ext_randomizer-tool_ui_preview.JPG

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 second 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.

../_images/ext_randomizer-tool_range_linking_before_after.JPG

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.

../_images/ext_randomizer-tool_uniform_scaling.JPG

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.

../_images/ext_randomizer-tool_transform_toggle_example.JPG

Note

When an attribute is disabled, the Range Linking buttons and the number fields can still be interacted with and manipulated.

Materials¶

The third collapsable 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.

../_images/ext_randomizer-tool_ui_materials_add.JPG

Note

The Add button opens up a stage dialog that is specifically filtered to only show materials.

../_images/ext_randomizer-tool_ui_materials_drag.JPG

Note

You can also drag materials from the stage directly into the material list

../_images/ext_randomizer-tool_ui_materials_remove.JPG

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.

../_images/ext_randomizer-tool_ui_materials_replace.JPG

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.

../_images/ext_randomizer-tool_remember_last.JPG

Note

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

Shared Material Replacement¶

When Shared Material Replacement is enabled, prims who share the same material in the replace tab will be replaced by the same random material. When disabled a new random material will be assigned for each occurrence.

This can be useful for replacing all occurrences of the same car paint material on many separate prims with a new random car paint material.

../_images/ext_randomizer-tool_ui_materials_shared.JPG

Note

This option only applies to the Replace feature in the materials section of the Randomizer.

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 heirarchy and all children will be automatically included.

../_images/ext_randomizer-tool_ui_materials_children.JPG

Note

This option applies to all features in the materials section of the Randomizer.

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 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.