ModelInstanceRandomizer
SUMMARY
Decides which models appear and how many of each. It is usually the first node in a randomizer: every node after it only sees the instances it made visible.
Usage
from telekinesis.illusion import config
from telekinesis.illusion.randomizer.randomizer_node import ModelInstanceRandomizer
randomizer.add(
ModelInstanceRandomizer(config.InstanceRandomizerConfig(
counts={"gear": (1, 4), "pipe": (0, 2)}, # per-model [min, max] visible instances
min_num_total_models=2,
max_num_total_models=5,
)),
"instances",
)For every scene this draws a count for each model within its bounds, keeps the total within min_num_total_models–max_num_total_models, and activates that many instances. A scene from this config holds one to four gears and up to two pipes, two to five parts in all.
InstanceRandomizerConfig
| Field | Type | Default | Description |
|---|---|---|---|
counts | dict[str, tuple[int, int]] | required | Registered model_name → (min, max) visible instances, inclusive. |
min_num_total_models | int | None | None | Lower bound on the total across all models. |
max_num_total_models | int | None | None | Upper bound on the total across all models. |
The bounds are validated when the config is built: each (min, max) must be non-negative with min <= max, and the totals must be reachable from the per-model bounds.
Instance Pools
The generator imports each model once per instance it could ever need, before the first scene, and only toggles their visibility afterwards. The pool size comes from these bounds, so a generous max costs memory and preparation time but nothing per scene.
Instances are named <model_name>_INSTANCE_<n>. Several ModelInstanceRandomizer nodes can request the same model; their capacities add up and they never pick the same instance. That is how the worker gives parts, containers and distractors their own totals.