Scene

Scene owns the models, lights, categories, materials, background, and camera shared by the randomizer and renderer. New code should use Scene; telekinesis.illusion.core.context.Context remains only as a compatibility alias.

Import

from telekinesis.illusion.core.scene import Scene
from telekinesis.illusion.types.camera import CameraConfig
from telekinesis.illusion.types.light import Light
from telekinesis.illusion.types.model_asset import ModelAsset

Constructor

scene = Scene(
    camera_config=CameraConfig(image_width=720, image_height=720),
    asset_dir=None,
)

Parameter	Type	Description
camera_config	CameraConfig | None	Camera intrinsics and image resolution. None uses the defaults.
asset_dir	str | Path | None	Directory holding models/, hdris/, and materials/. None checks ./assets, then the assets beside an editable source checkout.

Constructing a scene initializes the process-wide Blender scene. Keep one active Scene per process and let SyntheticDataGenerator clean it up after generation.

Register Models and Lights

Register model definitions before generation. Geometry is imported later, when the generator prepares the scene with the capacity requested by ObjectInstanceRandomizer.

scene.add(
    ModelAsset(
        "assets/models/mechanical_parts/gearwheel_1.glb",
        object_name="gear",
        category_name="gear",
        category_id=1,
        active_in_simulation=True,
        collision_shape="CONVEX_HULL",
        scale=1.0,
        shading="FLAT",
        uv_mapping="smart",
    )
)
scene.add(Light("key", "POINT", power=40.0, location=(0.0, 0.0, 1.0)))

ModelAsset field	Description
model_path	Model file path, relative to the working directory or absolute.
object_name	Unique model name used by randomizer nodes.
category_name / category_id	COCO category. Omitting both uses object_name; category_name="distractor" disables annotation.
active_in_simulation	Whether active instances participate in physics.
collision_shape	Blender collider such as "CONVEX_HULL" or "MESH".
scale	Positive uniform scale or three-axis scale.
preprocess_model	Whether to preprocess materials, UVs, and shading on import.
shading	"FLAT", "SMOOTH", or "AUTO_SMOOTH".
material_preprocessing	"replace" or "preserve".
uv_mapping	"smart", "cube", "cylinder", or "sphere".

Category IDs and names have a one-to-one mapping. Conflicting pairs, duplicate object names, missing model files, and model registration after preparation are rejected.

Read the Scene

Method	Returns
get_objects()	Prepared mesh instances keyed by instance name.
get_objects_by_name(name)	One matching object, or a list when several names match.
get_object_group(object_name)	Every prepared instance belonging to a registered model.
get_visible_object_names()	Names of instances active in the current sample.
get_lights() / get_light(name)	Registered lights.
get_camera()	The rendering camera.
get_background()	The scene background.
get_categories()	The category-ID/name mapping.
get_asset_dir()	The resolved asset root.

Next Steps

Randomizer

Build the randomizer graph executed over the scene.

Explore →

Randomizer Nodes

Choose which aspects of the scene vary.

Explore →