Running a Worker

A worker turns a single spec YAML into a complete dataset. It builds the Context and the randomizer tree for a use case, generates the images in shards, and merges those shards into one annotation file – optionally split into train, valid, and test.

Use a worker when you want a dataset. Use the Python API directly when you are experimenting with a scene.

Import

from telekinesis.illusion.workers.bin_picking_worker import BinPickingWorker

Running a Worker

worker = BinPickingWorker(spec_file_path)
worker.generate()
worker.merge_shards(preview=True)

Method	Description
generate()	Generate every shard defined by the spec.
merge_shards(preview=True)	Merge the shards into merged_coco_annotations.json, run the dataset split when the spec requests one, and optionally open the result in the viewer.

The bundled entry script does the same from the command line:

python examples/generate_synthetic_data_with_bin_picking_worker.py \
  --spec-file example_bin_picking_gearwheel_2.yaml

Bare filenames resolve against the repository's configs/ directory; an absolute or relative path points at a spec elsewhere. Pass --no-preview to skip opening the merged dataset afterwards.

Smoke test first

Lower metadata.num_images and shard.size (for example both to 10) before a long run, so a full generate and merge cycle finishes in minutes.

Shards

A shard is a self-contained mini-COCO dataset: one coco_annotations.json plus an images/ directory of rendered PNGs. Shards let a run checkpoint its progress, so a size limit or an interruption never discards finished work.

• num_shards = ceil(metadata.num_images / shard.size). The total number of scenes across all shards always equals metadata.num_images exactly.
• shard.size counts scenes, not images. Each scene renders camera_pose_randomizer.number_of_views images.
• Generation stops after the first shard whose total dataset size reaches output.max_size_gb.
• Shards must be merged before use. Consumers load merged_coco_annotations.json, whose image paths resolve relative to the dataset root.

<base_output_directory>/
└── <dataset_name>/
    ├── merged_coco_annotations.json     # written by merge_shards()
    ├── shard_<date>_<uuid>/
    │   ├── coco_annotations.json
    │   └── images/
    │       ├── 000000.png
    │       └── ...
    └── shard_<date>_<uuid>/
        ├── coco_annotations.json
        └── images/

BinPickingWorker

BinPickingWorker generates parts-in-bin scenes: target parts and distractors are placed on the upper face of a container, settled with physics, and rendered against randomized backgrounds.

Given a spec, it registers every entry in models: and distractors: on the context, then wires the randomizers in a fixed order: object instances, container instance (always exactly one), object poses on the visible container, distractor instances, distractor poses, materials per supercategory, background, and camera pose. Per shard it runs the generation loop, then checks the dataset size against the configured limit.

Common Modifications

Goal	Change
Add a target part	Append an entry to models: with supercategory: part, a unique name, a model path, and an id plus category_name.
Map several meshes to one class	Give every entry the same id and category_name.
Swap the bin	Add or replace an entry with supercategory: container, simulation.active: false, and collision_shape: MESH. Exactly one container is picked per scene.
Add clutter	Raise max_number_visible_models and max_number_visible_distractors, and raise the per-asset instances.max so the instance pool is large enough.
Resize the dataset	Change metadata.num_images and shard.size, using output.max_size_gb as a safety cap.
Change resolution	Edit camera.image_width, camera.image_height, and camera.field_of_view (radians).

Every key referenced above is documented in the spec YAML reference.

Next Steps

Spec YAML Reference

Every key of a dataset spec: metadata, sharding, models, placement, camera, physics, and output.

Explore →

Merging and Converting

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

Explore →