Setting

If the key-value pair in the description file is neither a Mutable nor a Harmonizer, it’s a setting. You can define a description with only settings.

Required Keys

There are several required keys for settings:

Required Key	Type	Description
output_path	string	The output folders in which folders corresponding to each output switch are created
num_frames	int	Number of frames to output
screen_width	int	Screen width of output images
screen_height	int	Screen height of output images
seed	int	Global randomization seed
version	string	Version number of omni.replicator.object

output_switches

The setting output_path controls what is output to disk per frame. It has these switches:

Switch	Data
images	The RGB image of the frame
labels	2d tight bounding box and the occlusion rate information for each visible tracked object. Each line corresponds to an object, and it has Kitti format usd_base_name 0 occlusion 0 x_min y_min x_max y_max 0 0 0 0 0 0 0
3d_labels	3D bounding box information stored as Objectron format
descriptions	A description file logging the current state of the scene - Using this file as input description, the same graphics content is output
segmentation	The segmentation mask of tracked mutables
depth	The depth map of the scene, showing the distance to image plane
normal	The normal map of the frame

Setting a switch to True or not setting the switch creates the corresponding folder under output_path and writes corresponding data into it.

usd_base_name is the mutable name or the USD file base name of USD file when a geometry mesh is loaded, which means it’s not allowed to load different USD files with the same base name. Using ${resource_root_1}/apple.usd and ${resource_root_1}/inner/apple.usd in the same simulation causes unexpected behavior.

For example, an output switch could be:

output_switches:
  images: True
  labels: True
  descriptions: True
  3d_labels: True
  segmentation: True
  depth: False

Optional Keys

There are also optional keys, where if not set, have default values:

Optional Keys with Default Value	Type	Default value	Description
parent_config	string	None	Specifies the description file that this description file inherits from, in the same parent folder. Values re-defined in the current description file override values defined in parent configs.
path_tracing	bool	False	Render mode selection
inter_frame_time	numeric	0	The simulation time between 2 frames
output_name	string	$[seed]_$[camera]	The output name of a frame that can be customized. Seed, camera, and frame macros are available.
skip_frames_with_no_visible_tracked_mutables	bool	False	If set to true, and if there are no visible tracked mutables in the scene, the frame is skipped
gravity	numeric	0	Resolves gravity during physics resolution stage
friction	numeric	1	Friction among objects during physics resolution stage. Lower values indicate that the object is more slippery.
linear_damping	numeric	0	Linear damping of objects during physics resolution stage.
angular_damping	numeric	0	Angular damping of objects during physics resolution stage.
occlusion_threshold	numeric	1	If the occlusion of an object is bigger than this threshold, the object will be skipped in the labels.

Suggestions and More Information

path_tracing

Turing it on uses the path tracer, which makes simulation slower but image quality higher. Turning it off uses real-time RTX.

inter_frame_time

For complex scenes, leave more time for physics resolution and rendering.

output_name

Three macros are available:

• $[seed] evaluates to the seed of the current frame

• $[camera] evaluates to the camera name

• $[frame] evaluates to the frame index. Refer to seed for details.

$[seed]

Each frame is randomized with its own seed, which equals the global seed plus the frame index. For example, if global seed is 2, and 3 images are output, the frame indices for these 3 images are 0, 1, 2; and the seeds are 2, 3, 4, respectively.

Physics simulation explained

When objects are randomized in the scene for each frame, they may start at an overlapping position. Resolution of physics de-penetrates these objects. The de-penetration accelerates the objects, such that they may start off with a high speed. Increase linear/angular damping to keep object movement contained.

However, if the dampings are set too high, objects get lazy and they don’t move much. This can be bad in a gravity enabled setting, where we want objects to be in close contact with a surface. Because different objects have different sizes and shapes, it’s good to tune these physics properties to reach a good appearance.

Similarly, too high of a value for friction makes objects cluster if they are in close contact; while too low of a value for friction makes them slippery and glide off surfaces.

Note

If there is no object in the scene when you are expecting some objects, one reason might be that they flew away from the view frustum. Check your physics settings.