Spec YAML Reference

A spec is a self-contained dataset definition consumed by a Worker. The reference spec is configs/example_bin_picking_gearwheel_2.yaml.

metadata:
  asset_directory: ../assets
  dataset_name: example_bin_picking_gearwheel_2
  use_case: instance_segmentation
  annotation_format: coco_instances_rle
  num_images: 20
  base_output_directory: output

shard:
  size: 10

min_number_visible_models: 1
max_number_visible_models: 6
models:
  - name: gearwheel_2
    id: 1
    supercategory: part
    category_name: gear
    path: models/mechanical_parts/gearwheel_2.glb
    instances: { min: 0, max: 6 }
    simulation: { active: true, collision_shape: CONVEX_HULL }
    scale: 1.0
    preprocess_model: True

  - name: plastic_bin_2
    id: None
    supercategory: container
    category_name: distractor
    path: models/bins/plastic_bin_2.glb
    instances: { min: 0, max: 1 }
    simulation: { active: false, collision_shape: MESH }
    scale: 1.0
    preprocess_model: True

Metadata and Sharding

Key	Type	Purpose
metadata.dataset_name	string	Dataset directory name under the output root.
metadata.num_images	int	Exact image count requested across all shards.
metadata.base_output_directory	string | null	Output root. Null or empty falls back to ./output/<dataset_name> relative to the run directory.
metadata.asset_directory	string | null	Directory holding models/, hdris/, and materials/. Relative paths are anchored on the spec file.
metadata.info / metadata.licenses	map / list	Required COCO info and licenses blocks copied into the annotations.
shard.size	int	Images per shard. The final shard may be smaller.

use_case, annotation_format, and package_version may be kept as descriptive metadata, but the current worker does not consume them.

Models and Distractors

Key	Type	Purpose
models[].name	string	Unique asset name.
models[].id	int | None	COCO category_id. Several entries may share an id to map multiple meshes to one category. None excludes the asset from the annotations.
models[].supercategory	part | container | distractor	Drives randomizer routing.
models[].category_name	string	COCO category name. Must be consistent across entries sharing an id.
models[].path	string	Model path relative to metadata.asset_directory.
models[].instances.min / .max	int	Per-scene instance count range for this asset.
models[].simulation.active	bool	Whether the asset participates in physics. Containers are typically false.
models[].simulation.collision_shape	CONVEX_HULL | MESH	Collider type. Use MESH for bins.
models[].scale	float	Uniform scale.
models[].preprocess_model	bool	Run import-time preprocessing.
models[].shading	FLAT | SMOOTH | AUTO_SMOOTH	Imported mesh shading. Default FLAT.
models[].material_preprocessing	replace | preserve	Replace or retain imported material slots during preprocessing.
models[].uv_mapping	smart | cube | cylinder | sphere	UV projection used during preprocessing.
min_number_visible_models / max_number_visible_models	int	Bounds on visible target objects per scene.
min_number_visible_distractors / max_number_visible_distractors	int	Bounds on visible distractors per scene.
distractors[]	list	Same shape as models[]. Omit the list to disable distractors.

To label distractors, give them a real id and category_name. To keep them unlabeled, set id: None and category_name: distractor.

Placement

Key	Type	Purpose
pose_sampling.strategy	random | grid	Placement strategy for target objects on the container's upper face.
pose_sampling.sample_on_surface	string | null	Optional fixed surface model name. When omitted, the worker resolves the visible container.
pose_sampling.params.min_height / max_height	float	Vertical band above the container's upper face in which object centres are sampled.
pose_sampling.params.face_sample_range	[float, float]	Fractional inset on the container's upper face. Default [0.25, 0.75].
pose_sampling.params.grid.rows / .cols / .layers	int	Grid dimensions, used when strategy: grid. Grid capacity caps the number of visible parts.
pose_sampling.params.grid.layer_spacing	float	Vertical spacing between grid layers.
pose_sampling.params.grid.xy_jitter	float	Random XY offset applied per grid cell.
pose_sampling.params.grid.z_rotation_range	[float, float]	Bounds on per-instance Z rotation, in degrees.
pose_sampling.params.grid.shuffle	bool	Whether grid cell assignment is shuffled.

Camera and Renderer

Key	Type	Purpose
camera.field_of_view	float	Field of view, in radians.
camera.clip_start / clip_end	float	Near and far clip planes.
camera.image_width / image_height	int	Output resolution.
camera.pixel_aspect_x / pixel_aspect_y	float	Pixel aspect ratio.
camera.shift_x / shift_y	float	Lens shift.
renderer.image_format	JPEG | PNG	Writer image format. Default JPEG.
renderer.jpg_quality	int	JPEG quality from 0 to 100. Default 90.
renderer.device	string	Cycles device: CUDA, another supported GPU backend, or CPU. Default CUDA.
renderer.samples	int | null	Positive Cycles sample limit.
renderer.noise_threshold	float | null	Optional adaptive-sampling noise threshold.
camera_pose_randomizer.sampler	string	Camera pose sampler, for example volume_sampler.
camera_pose_randomizer.number_of_views	int	Rendered images per scene.
camera_pose_randomizer.params.distance_range	[float, float]	Bounds on the camera distance from the point of interest.
camera_pose_randomizer.params.inplane_rot_min / inplane_rot_max	float	Bounds on in-plane camera rotation, in degrees.
camera_pose_randomizer.params.point_of_interst	[float, float, float]	World-space point the camera looks at. Spelled as shown; copy the key verbatim.

Randomization Overrides

Key	Type	Purpose
instance_randomizer.<role>.min / .max	int	Per-supercategory override of the visible-instance bounds. Roles are part, container, and distractor.
material_randomizer.<role>	list[string]	Material type tags per supercategory. Defaults: part: [metal], container: [plastic], distractor: [metal]. An empty list disables material randomization for that role.
background_randomizer.categories	list[string]	HDRI categories the background is sampled from.

material_randomizer also supports rule-based configuration. A rule names exact target prefixes and forwards mode, materials, material_slots, and seed to MaterialRandomizer:

material_randomizer:
  active: true
  rules:
    - name: housing_slots
      target_objects: [housing]
      mode: slots
      material_slots:
        Body: [metal]
        Seal: [rubber]

Lights

light_randomizer.active: false disables explicit lights. Otherwise, each entry requires a unique name, a Blender light type, randomized properties, and a pose sampler:

light_randomizer:
  active: true
  lights:
    - name: bin_key
      type: AREA
      properties:
        power: { min: 40.0, max: 100.0 }
        shape: [RECTANGLE, DISK]
        size: { min: 0.3, max: 0.6 }
      pose:
        sampler: shell_sampler
        min_distance: 0.3
        max_tries: 100
        params:
          center: [plastic_bin_]
          radius_min: 1.2
          radius_max: 1.6

Property ranges use {min, max}. Fixed values are also accepted; area-light shape may be a list of choices. Pose samplers and parameters match the camera samplers.

Physics

Key	Type	Purpose
physics_simulator.active	bool	Whether to settle the objects before rendering each scene.
physics_simulator.min_simulation_time_range / max_simulation_time_range	[float, float]	Simulated-seconds ranges sampled per scene.
physics_simulator.check_object_interval	float	Interval, in simulated seconds, between at-rest checks.
physics_simulator.object_stopped_location_threshold	float	Maximum location change, in meters, for an object to count as at rest.
physics_simulator.object_stopped_rotation_threshold	float	Maximum rotation change, in radians, for an object to count as at rest.
physics_simulator.substeps_per_frame	int	Physics substeps per simulation frame.
physics_simulator.solver_iters	int	Solver iterations.
physics_simulator.use_volume_com	bool	Compute the center of mass from volume instead of mesh vertices.
physics_simulator.verbose	bool	Verbose simulation logging.
physics_simulator.catch_plane.active	bool	Enable the safety plane used to detect objects that fall below the container.
physics_simulator.catch_plane.distance_fraction	float	Place the plane this fraction of the container height below its lower bound.
physics_simulator.catch_plane.minimum_distance	float	Minimum plane offset below the container.
physics_simulator.catch_plane.size_factor	float	Plane size relative to the scene bounds.
physics_simulator.catch_plane.contact_tolerance	float	Distance used to classify an object as contacting the catch plane.

The worker manages scene cleanup between shards itself; a physics_simulator.clean_up_scene value in an older spec is not consulted.

Output

Key	Type	Purpose
output.shard_name_template	string	Shard directory name. Supports {date} (YYYYMMDD_HHMMSS) and {uuid} (8 hex characters). Default shard_{date}_{uuid}.
output.max_size_gb	number	Early-stop threshold for the total dataset size, in GiB. Default 10.
output.dataset_format	coco | yolo | null	When set, merge_shards() also runs a DatasetConverter split into this format.
output.train_val_tes_ratio	[float, float, float]	Train, valid, and test ratios for that split. Default [0.7, 0.2, 0.1]. Spelled as shown; copy the key verbatim.
output.stratify	bool	Whether the split is stratified by dominant category. Default true.
output.seed	int	RNG seed for the split. Default 42.

output.write_manifest may appear in older specs, but the current worker does not consume it.

Next Steps

Tuning a Randomizer Tree in Blender

Load a spec, edit the tree with a live preview of the randomized scene, and export the tuned YAML.

Open tutorial →

Merging and Converting

Merge shards into one annotation file and split it into train, valid, and test in COCO or YOLO format.

Explore →