Configs

SUMMARY

Every setting in Illusion is a config from telekinesis.illusion.config: the assets you register, each randomizer node, the renderer, physics, and every section of a worker YAML. Configs are immutable, validated when they are built, and convert to and from plain dictionaries, so the same settings work in Python and in YAML.

Import

from telekinesis.illusion import config

The module does not import Blender, so you can build and validate configs in tests, notebooks or a config editor without starting the renderer.

Build, Copy, Convert

camera = config.CameraConfig(image_width=640, image_height=480)
wide = camera.replace(field_of_view=1.2)      # a validated copy; camera is unchanged

camera.to_dict()
# {'image_width': 640, 'image_height': 480, 'clip_start': 0.1, 'clip_end': 1000.0, ...}

poses = config.CameraPoseRandomizerConfig.from_dict(
    {"sampler": "shell_sampler", "number_of_views": 2, "params": {"radius_min": 0.3, "radius_max": 0.5}}
)
type(poses.params)   # ShellSamplerConfig: nested dictionaries become nested configs

Every config shares the same three methods from BaseConfig:

Method	Does
to_dict(keep_none=False)	Plain dictionary, ready for YAML or JSON. Ranges become {"min", "max"}, paths become strings. Fields left at a None default are omitted unless keep_none=True.
from_dict(values)	Build from a dictionary. Rejects unknown keys and missing required ones.
replace(**changes)	Copy with some fields changed, validated again.

Configs are frozen: assigning to a field raises FrozenInstanceError. Use replace().

Errors Name the Offending Key

Invalid values raise ValueError or TypeError with the key path of the value, at construction time, before anything is rendered:

ValueError: params.radius_min: must be a number >= 0.0, got -1.
ValueError: views: unknown key(s) for CameraPoseRandomizerConfig. Valid keys are ['number_of_views', 'params', 'sampler'].
ValueError: counts: Invalid instance bounds for 'gear': (3, 1)

A worker validates its whole YAML file this way when it is loaded, so a typo fails in the first second instead of an hour into a run.

Which Config Goes Where

Distances are in meters and angles in radians unless a field says degrees.

Config	Used by	Documented in
ModelConfig, MaterialConfig, BackgroundConfig	Environment.add()	Environment
LightConfig, CameraConfig	Environment.add()	Environment
RenderConfig, PhysicsConfig	BlenderEngine(...)	SyntheticDataGenerator
InstanceRandomizerConfig	ModelInstanceRandomizer	ModelInstanceRandomizer
ModelPoseRandomizerConfig	ModelPoseRandomizer	ModelPoseRandomizer
MaterialRandomizerConfig, PrincipledMaterialConfig	MaterialRandomizer	MaterialRandomizer
BackgroundRandomizerConfig	BackgroundRandomizer	BackgroundRandomizer
LightRandomizerConfig	LightRandomizer	LightRandomizer
LightPoseRandomizerConfig	LightPoseRandomizer	LightPoseRandomizer
CameraPoseRandomizerConfig	CameraPoseRandomizer	CameraPoseRandomizer
ShellSamplerConfig, VolumeSamplerConfig	the params of the two pose randomizers above	CameraPoseRandomizer
DatasetConfig, ShardConfig, WriterConfig, CocoConfig, CocoLicenseConfig	the worker's dataset section	Worker YAML Reference
PoseSamplingConfig, GridSamplingConfig	the worker's pose_sampling section	Worker YAML Reference

From Python to YAML

Because a YAML section is just to_dict() of its config, anything you prototype in Python moves to a worker config unchanged:

config.LightRandomizerConfig(properties={"power": {"min": 20.0, "max": 60.0}}).to_dict()
# {'properties': {'power': {'min': 20.0, 'max': 60.0}}}

randomizers:
  light:
    key:
      properties:
        power: {min: 20.0, max: 60.0}

Randomizer

Combine randomizer nodes into the graph that turns the environment into one scene per sample.

Open randomizer →