SyntheticDataGenerator

SyntheticDataGenerator prepares the scene, randomizes each sample, optionally simulates physics, renders the configured camera views, writes them, and cleans up.

Construction

from telekinesis.illusion.core.engine import (
    BlenderEngine,
    PhysicsConfig,
    RenderConfig,
)
from telekinesis.illusion.core.synthetic_data_generator import (
    SyntheticDataGenerator,
)

generator = SyntheticDataGenerator(
    scene=scene,
    randomizer=randomizer,
    writer=writer,
    engine=BlenderEngine(
        RenderConfig(device="CPU", samples=8),
        PhysicsConfig(active=False),
    ),
)

scene, randomizer, and writer are required. When engine is omitted, the generator creates a BlenderEngine with CUDA rendering and physics disabled. The legacy context= keyword remains accepted as an alias for scene=.

Generate

images_written = generator.generate(num_images=6)

Parameter	Default	Description
num_images	None	Exact number of camera views to write. The final batch is trimmed when necessary.
num_samples	None	Number of randomized scenes. Every configured camera view is written, so the image count may be larger.
clean_up_scene	True	Clean up engine and scene resources in finally. Workers set this to False between shards and clean up after the run.
save_blender_scene	False	Save scene.blend in the writer output directory after generation.

Pass either num_images or num_samples, not both. When neither is supplied, num_images defaults to 5. Counts must be positive integers. generate() returns the number of images written.

Physics and rendering behavior belong to the engine configuration:

engine = BlenderEngine(
    RenderConfig(
        device="CUDA",
        samples=64,
        noise_threshold=None,
        max_retries=2,
        verbose=False,
        depth=False,
        normals=False,
    ),
    PhysicsConfig(
        active=True,
        min_simulation_time_range=(0.5, 1.0),
        max_simulation_time_range=(2.0, 5.0),
        check_object_interval=2.0,
        object_stopped_location_threshold=0.01,
        object_stopped_rotation_threshold=0.1,
        substeps_per_frame=10,
        solver_iters=10,
        verbose=False,
        use_volume_com=False,
    ),
)

The older physics keywords passed directly to generate() are still accepted for worker compatibility, but new scripts should configure PhysicsConfig and RenderConfig explicitly.

Lifecycle

prepare() allocates the instance pools requested by enabled randomizer nodes, prepares their resources, and configures rendering. Normal generation calls it automatically. Call it yourself only when a static object transform must be changed after models are imported, as the parts-in-bin example does.

clean_up() releases engine and scene resources. A normal generate() call invokes it even when generation raises.

Next Steps

Workers

Generate sharded datasets from a YAML specification.

Explore →

Merging and Converting

Merge shards and export COCO or YOLO splits.

Explore →