Randomizer

The randomizer tree: a directed acyclic graph of nodes, each changing one aspect of the scene. Nodes are executed in dependency order, each receiving the Context.

Import

from telekinesis.illusion.randomizer.randomizer import Randomizer, EdgeConfig
from telekinesis.illusion.randomizer.randomizer_node import NodeConfig

Constructor

randomizer = Randomizer()

randomizer.add_randomizer(
    randomizer_node,     # a RandomizerNode
    node_name,           # unique node name
    node_config=None,    # NodeConfig
    edge_config=None,    # EdgeConfig
)

add_randomizer() appends the node to the chain: the first node becomes the start of the graph, and every subsequent node is added as a successor of the previous one. Execution order is recomputed on every randomize() call using a topological sort, so nodes always run in dependency order.

Methods

Method	Description
add_randomizer(randomizer_node, node_name, node_config=None, edge_config=None)	Append a node to the chain.
add_node(randomizer_node, name, node_config=None)	Register a node without connecting it.
add_edge(from_node_name, to_node_name, edge_config=None)	Connect two registered nodes.
get_randomizer_node(node_name)	The node registered under node_name, or None.
replace_randomizer(node_name, randomizer_node)	Swap a node's implementation, leaving the graph topology and node config untouched.
get_node_stages()	The stage each registered node belongs to, keyed by node name.
randomize(context, stages=None)	Execute the tree over context.

replace_randomizer() is what interactive tools use to re-tune a node's parameters between runs without rebuilding the scene. The Blender extension relies on it for live preview.

NodeConfig

Per-node execution metadata, passed as node_config.

Field	Type	Default	Description
enabled	bool	True	Whether the node runs at all. Disabled nodes are skipped.
stage	str	STAGE_DEFAULT	The stage this node belongs to (see below).
priority	int	0	Reserved for ordering within a stage.
seed_key	str | None	None	Reserved for per-node seeding.
apply_prob	float	1.0	Reserved for probabilistic application.
max_tries	int	1	Reserved for node-level retries.
on_failure	str	"raise"	Reserved failure behavior: "raise", "skip_node", or "skip_sample".
profile	bool	False	Reserved for per-node profiling.

EdgeConfig currently carries a single enabled flag for an edge.

Stages

Stages group nodes by which part of the scene they change, so a caller can re-run only part of the tree.

Stage	Constant	Covers
"composition"	STAGE_COMPOSITION	Which and how many instances are visible.
"pose"	STAGE_POSE	Where the visible objects are placed.
"appearance"	STAGE_APPEARANCE	Materials and the background HDRI.
"camera"	STAGE_CAMERA	Camera pose sampling.
"default"	STAGE_DEFAULT	Assigned when a node opts into no stage. Never filtered out.

A node left at STAGE_DEFAULT runs in every pass, so a node that does not opt into a stage is never skipped by accident.

from telekinesis.illusion.randomizer.randomizer_node import (
    NodeConfig,
    STAGE_POSE,
    STAGE_CAMERA,
)

randomizer.add_randomizer(
    randomizer_node=object_pose_randomizer,
    node_name="pose_randomizer",
    node_config=NodeConfig(stage=STAGE_POSE),
)

# Re-sample geometry only: poses and camera, keeping materials and selection
randomizer.randomize(context, stages={STAGE_POSE, STAGE_CAMERA})

# A full generation run passes no stages, so everything executes
randomizer.randomize(context)

Next Steps

Randomizer Nodes

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

Explore →

SyntheticDataGenerator

The generation loop: randomize, optionally simulate physics, render, and write.

Explore →