Macro
Macros can be used in settings and mutable attributes in certain ways to retrieve a value from another setting or mutable attribute. They are defined like $[...]
. Macros are used everywhere to describe relationships among values to simulate complex scenes with compact descriptions.
$[/absolute_reference]
Absolute references refer to values by their absolute paths.
bright_light: type: light subtype: dome intensity: distribution_type: range start: distribution_type: range start: $[/dark_light/intensity] end: $[/dark_light/intensity] + 200 end: $[/dark_light/intensity] + 1000 texture_path: omniverse://content.ov.nvidia.com/NVIDIA/Assets/Skies/2022_1/Skies/Clear/lakeside.hdr transform_operators: - rotateX: 270 dark_light: subtype: dome intensity: distribution_type: range start: 100 end: 1000
In this example, the mutable attribute, /bright_light/intensity
, is a range that ranges from $[/dark_light/intensity]
to $[/dark_light/intensity] + 200
. These limits depend on the resolution of another mutable attribute, /dark_light/intensity
. Thus, in every frame /dark_light/intensity
is resolved before bright_light/intensity
is resolved.
$[relative_reference] and $[../relative_reference]
Relative references refer to values with the same parent. In the example below, $[a1]
is the same as $[/a/a1]
:
a: a1: x a2: $[a1]
You may also go to parenting attribute using ..
. In the example below, $[../a1]
is the same as $[/a/a1]
:
a: a1: x a2: a21: $[../a1]
$[reference_to_list_element~index]
References to list elements refer to values in lists. In the example below, /bins
will be expanded to /bins_0
to /bins_7
, with /bins_X/dimension
resolved to a 3-element list. $[/bins_$[index]/dimension~0]
in /transform_global_X/pitch
will retrieve the resolved value from index 0.
bins: # dimensions of 4 small bins count: 8 dimension: distribution_type: range start: - 100 - 200 - 300 end: - 400 - 200 - 300 transform_global: # transforms of 4 small bins count: 8 distribution_type: harmonized harmonizer_name: bin_pack_global_H pitch: - - -$[/bins_$[index]/dimension~0] / 2 * 1.5 - -$[/bins_$[index]/dimension~1] / 2 - -$[/bins_$[index]/dimension~2] / 2 * 1.5 - - $[/bins_$[index]/dimension~0] / 2 * 1.5 - $[/bins_$[index]/dimension~1] / 2 - $[/bins_$[index]/dimension~2] / 2 * 1.5
$[/as_is_reference]
As-is reference macro substitutes the whole value, supporting references to dictionaries. For example:
screen_width: 960 screen_height: 544 camera_parameters: far_clip: 100000 focal_length: 14.228393962367306 horizontal_aperture: 20.955 near_clip: 0.1 screen_height: $[/screen_height] screen_width: $[/screen_width] default_camera: type: camera camera_parameters: $[/camera_parameters]Evaluates to:
screen_width: 960 screen_height: 544 camera_parameters: focal_length: 14.228393962367306 horizontal_aperture: 20.955 near_clip: 0.1 far_clip: 100000 screen_width: 960 screen_height: 544 default_camera: type: camera camera_parameters: focal_length: 14.228393962367306 horizontal_aperture: 20.955 near_clip: 0.1 far_clip: 100000 screen_width: 960 screen_height: 544
$[special_macros]
$[seed]
resolves to the current frame’s seed number, and $[frame]
resolves to the frame index.
Note
An error is triggered if a cyclic reference is detected.
Some other examples are listed below:
You can define a macro for the path to load a USD file:
resources_root: [PATH_TO_MAIN_OBJECTS] main_object: ... usd_path: distribution_type: folder suffix: usd value: $[/resources_root]/main_objectsAt runtime, the folder to sample from is resolved as
[PATH_TO_MAIN_OBJECTS]/main_objects
, so thatusd_path
is[PATH_TO_MAIN_OBJECTS]/main_objects/[SAMPLED_FILE].usd
.seed: 3 penguin: ... count: 2 transform_operators: - rotateY: ($[../index] + $[seed]) % $[../count] * 60At frame two, this is equivalent to:
seed: 5 penguin_0: ... count: 2 index: 0 transform_operators: - rotateY: (0 + 5) % 2 * 60 penguin_1: ... count: 2 index: 1 transform_operators: - rotateY: (1 + 5) % 2 * 60Here,
$[../index]
and$[../count]
retrieve values from the local scope of the mutable they are in, while$[seed]
retrieves values from the global settings.Using macros, you can describe complex scenes that have a combination of randomized transform operators for each mutable.