Context

The scene state shared by every randomizer node: registered models, categories, materials, background, and camera. telekinesis-illusion separates what is in the scene from how the scene varies – the Context is the first half.

Import

from telekinesis.illusion.core.context import Context

Constructor

context = Context(
    auto_config=True,    # pick a default background HDRI
    camera_config=None,  # CameraConfig, or None for defaults
    asset_dir=None,      # directory holding models/, hdris/, materials/
)

Parameter	Type	Description
auto_config	bool	Configure the scene for default generation.
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 resolves the bundled default asset directory.

Creating a Context initializes BlenderProc, so a process holds exactly one scene at a time.

Registering Models

add_model() loads a 3D model, assigns it a COCO category, and pre-creates linked duplicates so instance counts can be randomized without reloading geometry.

context.add_model(
    model_path,                   # path to the model file
    object_name,                  # unique name within the scene
    category_name=None,           # COCO category name
    category_id=None,             # COCO category id
    min_number_instances=1,
    max_number_instances=1,
    active_in_simulation=False,   # participates in physics
    collision_shape="CONVEX_HULL",  # "CONVEX_HULL" | "MESH"
    scale=1.0,
    preprocess_model=True,
)

Parameter	Type	Description
model_path	str	Path to the 3D model file on disk.
object_name	str	Unique name within the scene. Instances are keyed <object_name>_INSTANCE_<n>.
category_name	str | None	COCO category name. Defaults to object_name. Use "distractor" together with category_id=None to exclude the model from the annotations.
category_id	int | None	Explicit COCO category id. Assigned automatically when omitted. Several models may share one id to fold multiple meshes into a single class.
min_number_instances	int	Lower bound on visible instances per scene.
max_number_instances	int	Upper bound on visible instances per scene. Determines how many linked duplicates are created.
active_in_simulation	bool	Whether the model participates in the physics simulation. Containers are typically False.
collision_shape	str	Collider type: "CONVEX_HULL" for parts, "MESH" for concave geometry such as bins.
scale	float | np.ndarray	Uniform or per-axis scale applied on import.
preprocess_model	bool	Whether to run import-time preprocessing.

Object names must be unique. Registering the same model twice raises a ValueError – increase max_number_instances instead. Category ids and names are kept in a strict one-to-one mapping; providing a combination that conflicts with an existing mapping also raises a ValueError.

Reading the Scene

Method	Returns
get_objects()	All registered instances, keyed by instance name.
get_objects_by_name(name)	The instance, or the list of instances, whose name contains name.
get_object_group(object_name)	Every instance of the model registered under object_name.
get_visible_object_names()	Names of the objects currently visible in the scene.
get_camera()	The Camera used for rendering.
get_background()	The scene Background.
get_categories()	The category-id to category-name mapping.
get_asset_dir()	The resolved asset directory.

Next Steps

Randomizer

The randomizer tree executed over the context, with per-node configuration and stage-scoped re-randomization.

Explore →

Randomizer Nodes

The individual axes of variation: instance count, object pose, material, background, and camera pose.

Explore →