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.

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

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

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.

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.