isaaclab.cloner

Function namespaces

path	Stateless prim-path operations for clone plans.
query	Batched numeric topology queries.

Classes

ClonePlan	Prototype topology and placement used to instantiate a scene.
PrototypeWorldTopology	Numeric asset-prototype and world relationships.
CloneCfg	Configuration for environment replication.
InclusionSet	Legal clone combination defined by explicitly listing active assets.
ReplicateSession	Author prototypes before dispatching one shared world topology.
UsdReplicateContext	Apply routed clone-plan sources to one USD stage.

Functions

clone_plan_from_env_0(clone_cfg, asset_cfgs, ...)	Prepare one homogeneous topology, placement, and its USD authoring inputs.
make_clone_plan(asset_cfgs, ...[, weights, ...])	Select world compositions and retain their optional placement without creating native resources.
to_warp(topology, device)	Materialize numeric topology on an explicitly selected device.
make_valid_clone_combinations(asset_names, ...)	Expand named combinations into world memberships and relative weights.
num_spawn_variants(spawn_cfg)	Return the number of concrete prototypes declared by a spawner configuration.
grid_transforms(N[, spacing, up_axis])	Create centered grid transforms as host arrays.
replicate(plan, *[, replicate_physics])	Execute one topology through its declared clone contexts.
usd_replicate(stage, sources, destinations, ...)	Replicate USD prims from a raw source-to-environment mapping.
filter_collisions(stage, physicsscene_path, ...)	Create inverted collision groups for clones (PhysX only).

Clone plan

class isaaclab.cloner.ClonePlan

Prototype topology and placement used to instantiate a scene.

Attributes:

topology	Numeric asset-prototype and world membership, independent of naming and placement.
asset_cfgs	Host declarations indexed by asset-prototype ID, retained once by reference.
env_template	Destination-world path template, with one {} slot for the world ID.
positions	Destination-world origins [m], shape [num_worlds, 3]; None preserves authored placement.

Methods:

__init__(topology, asset_cfgs[, ...])

topology: PrototypeWorldTopology

Numeric asset-prototype and world membership, independent of naming and placement.

asset_cfgs: tuple[Any, ...]

Host declarations indexed by asset-prototype ID, retained once by reference.

env_template: str = '/World/envs/env_{}'

Destination-world path template, with one {} slot for the world ID.

positions: ndarray | None = None

Destination-world origins [m], shape [num_worlds, 3]; None preserves authored placement.

__init__(topology: PrototypeWorldTopology, asset_cfgs: tuple[Any, ...], env_template: str = '/World/envs/env_{}', positions: ndarray | None = None) → None

class isaaclab.cloner.PrototypeWorldTopology

Numeric asset-prototype and world relationships.

Arrays use NumPy storage for planning or Warp storage on one device for runtime queries. Treat the topology as read-only after planning; to_warp() explicitly materializes its numeric arrays on a device. Host declarations and naming belong to ClonePlan.

Attributes:

num_asset_prototypes	Number of asset definitions, including unused prototypes.
world_prototypes	Flat int32 asset-prototype indices.
world_prototype_starts	Offsets into world_prototypes, starting with the shared world -1.
world_prototype_layout	Int32 world-prototype index per world, indexed by world ID; shared assets are not sampled.

Methods:

__init__(num_asset_prototypes, ...)

num_asset_prototypes: int

Number of asset definitions, including unused prototypes.

world_prototypes: np.ndarray | wp.array

Flat int32 asset-prototype indices. Repeated indices represent distinct instances.

world_prototype_starts: np.ndarray | wp.array

Offsets into world_prototypes, starting with the shared world -1.

Shared assets occupy world_prototypes[world_prototype_starts[0]:world_prototype_starts[1]]. World prototype i occupies world_prototypes[world_prototype_starts[i + 1]:world_prototype_starts[i + 2]]. An empty shared world starts with [0, 0]. Offsets have dtype int64.

world_prototype_layout: np.ndarray | wp.array

Int32 world-prototype index per world, indexed by world ID; shared assets are not sampled.

__init__(num_asset_prototypes: int, world_prototypes: np.ndarray | wp.array, world_prototype_starts: np.ndarray | wp.array, world_prototype_layout: np.ndarray | wp.array) → None

class isaaclab.cloner.clone_plan.TemplateMatch

The "{}" text a template captured ("3", or a wildcard ".*"), and the path below it.

Attributes:

instance	Alias for field number 0
suffix	Alias for field number 1

Methods:

__new__(_cls, instance, suffix)

Create new instance of TemplateMatch(instance, suffix)

instance: str

Alias for field number 0

suffix: str

Alias for field number 1

static __new__(_cls, instance: str, suffix: str)

Create new instance of TemplateMatch(instance, suffix)

isaaclab.cloner.make_clone_plan(asset_cfgs: ~collections.abc.Sequence[~typing.Any], world_prototypes: ~collections.abc.Sequence[~collections.abc.Sequence[int]], num_worlds: int, *, weights: ~collections.abc.Sequence[float] | None = None, shared_assets: ~collections.abc.Sequence[int] = (), clone_strategy: ~collections.abc.Callable[[~numpy.ndarray, int], ~numpy.ndarray] = <function sequential>, env_template: str = '/World/envs/env_{}', positions: ~numpy.ndarray | None = None) → ClonePlan

Select world compositions and retain their optional placement without creating native resources.

Parameters:

• asset_cfgs – Asset prototype definitions, retained by reference.

• world_prototypes – Asset indices in each world prototype, including repeated instances.

• num_worlds – Number of destination worlds.

• weights – Relative world-prototype weights; None gives every prototype equal weight.

• shared_assets – Asset indices instantiated once in the shared world -1.

• clone_strategy – Function selecting world-prototype indices from weights.

• env_template – Destination-world path template with one {} slot for the world ID.

• positions – Destination-world origins [m], shape [num_worlds, 3]; None preserves authored placement.

Returns:

A plan holding the topology and placement. Topology starts with a shared-world slice.

isaaclab.cloner.grid_transforms(N: int, spacing: float = 1.0, up_axis: str = 'z') → tuple[ndarray, ndarray]

Create centered grid transforms as host arrays.

Parameters:

• N – Number of instances.

• spacing – Distance between neighboring grid positions [m].

• up_axis – Up axis for positions ("z", "y", or "x").

Returns:

Positions [m], shape [N, 3], and identity xyzw orientations, shape [N, 4].

isaaclab.cloner.to_warp(topology: PrototypeWorldTopology, device: str) → PrototypeWorldTopology

Materialize numeric topology on an explicitly selected device.

Parameters:

• topology – Host topology. Contiguous arrays with matching dtypes are borrowed on CPU and copied on CUDA.

• device – Warp device, such as "cpu" or "cuda:0".

Returns:

A new topology holding its arrays alive independently of the host topology. Call once during initialization and share the result; this function does not cache, synchronize later host edits, or transfer cfgs. Queries never call it implicitly.

Path

class isaaclab.cloner.path

Stateless prim-path operations for clone plans.

Concrete roots are matched on segment boundaries; templates carry one "{}" instance slot. Call these functions through cloner.path without constructing an instance.

Methods:

get_asset_prototypes(plan[, path_expr])	Select asset-prototype IDs by their declared cfg paths, without expanding instances.
get_world_prototypes(plan[, path_expr])	Select world-prototype IDs containing assets matched by their declared cfg paths.
get_asset_prototype_paths(plan)	Return authored source paths indexed by asset-prototype ID, without reading a stage.
get_world_prototype_asset_templates(plan, *)	Name every asset occurrence in each world prototype.
get_parent_indices(paths)	Return the nearest strict ancestor in a path collection, independent of input order.
match(path_expr, template)	Match path_expr against a destination template, capturing the instance slot.
relative_to(path, root)	Strip a concrete root prefix off path on a segment boundary.
rebase(path, src_root, dst_root)	Rebase path from one concrete root prefix onto another on a segment boundary.

static get_asset_prototypes(plan: ClonePlan, path_expr: str | None = None) → ndarray

Select asset-prototype IDs by their declared cfg paths, without expanding instances.

Parameters:

• plan – Host asset declarations and their numeric topology.

• path_expr – Exact cfg prim_path or a regular expression matching the complete declared path string. None selects all definitions, including unused prototypes.

Returns:

Ascending asset-prototype IDs, shape [num_matches], dtype int32, each included once. Generated native paths are not matched.

static get_world_prototypes(plan: ClonePlan, path_expr: str | None = None) → ndarray

Select world-prototype IDs containing assets matched by their declared cfg paths.

Parameters:

• plan – Host asset declarations and their numeric topology.

• path_expr – Asset-path filter interpreted by path.get_asset_prototypes(). None selects all world definitions, including empty and unused prototypes and shared world -1.

Returns:

Ascending world-prototype IDs, shape [num_matches], dtype int32, not destination world IDs. Filtering selects complete compositions; repeated asset memberships remain in the topology.

static get_asset_prototype_paths(plan: ClonePlan) → tuple[str | None, ...]

Return authored source paths indexed by asset-prototype ID, without reading a stage.

Parameters:

plan – Host declarations, topology, and naming template.

Returns:

One source path per asset definition, or None for an unused definition. Explicit spawner paths take precedence; otherwise the first participating prototype/world supplies the source. Shared world -1 precedes replicated worlds.

static get_world_prototype_asset_templates(plan: ClonePlan, *, include_world_indices: bool = False) → tuple[tuple[str, ...], ndarray] | tuple[tuple[str, ...], ndarray, ndarray, ndarray]

Name every asset occurrence in each world prototype.

Parameters:

• plan – Host declarations, topology, and naming template.

• include_world_indices – Also return destination world IDs and their per-prototype starts.

Returns:

Flat templates aligned with topology.world_prototypes, and the existing world_prototype_starts array by reference. Shared templates have no instance slot; repeated memberships receive distinct sibling names. Unused prototypes retain templates.

When requested, two additional arrays group destination world IDs by world prototype, including shared world -1 first. For group g (prototype g-1), template starts select its members and world-index starts select its destinations. These are different boundaries; world IDs are not duplicated for every member. Both starts arrays include the final end.

static get_parent_indices(paths: Sequence[str]) → ndarray

Return the nearest strict ancestor in a path collection, independent of input order.

Parameters:

paths – Concrete paths or templates. Equal paths are peers, not parents.

Returns:

Parent index per input, dtype int32; -1 when no ancestor occurs in the collection. For duplicate ancestors the first occurrence is used. No stage is read.

static match(path_expr: str, template: str) → TemplateMatch | None

Match path_expr against a destination template, capturing the instance slot.

The "{}" slot matches one path segment’s worth of text: a concrete id (3) or a wildcard standing for one segment (.*, [^/]+). The captured text identifies the instance without slicing the path by hand.

Parameters:

• path_expr – Path or path expression on the clone (destination) side.

• template – Destination path template with "{}" for the instance id.

Returns:

A TemplateMatch with the captured instance text and the asset-relative suffix, or None when path_expr is not under the template’s instance root.

Example

>>> path.match("/World/envs/env_3/Robot/base", "/World/envs/env_{}/Robot")
TemplateMatch(instance='3', suffix='/base')

static relative_to(path: str, root: str) → str | None

Strip a concrete root prefix off path on a segment boundary.

Unlike slicing or str.removeprefix(), this returns None rather than a mid-segment remainder when path is not under root.

Parameters:

• path – Path to make relative.

• root – Concrete subtree root. A trailing slash is insignificant, and "/" is the root of every path.

Returns:

The suffix below root (starting with /, or "" when path equals root), or None when path is not under root.

classmethod rebase(path: str, src_root: str, dst_root: str) → str

Rebase path from one concrete root prefix onto another on a segment boundary.

Unlike str.replace(), this swaps only a boundary-aligned prefix and touches only the leading occurrence.

Parameters:

• path – Path to rebase.

• src_root – Concrete source root prefix.

• dst_root – Concrete destination root prefix.

Returns:

The rebased path, or path unchanged when it is not under src_root.

Query

class isaaclab.cloner.query

Batched numeric topology queries. Resolve declared paths separately with path.

All queries return (world_indices, world_starts). Indices are flat int32 values; starts are int64 offsets with shape [num_queries, num_worlds + 2], including shared world -1. For query q and world w, world_starts[q, w + 1 : w + 3] bounds its selected instances. Each row’s first/last offset bounds the entire query. Repeated IDs retain separate results.

NumPy queries allocate exact-sized results. Warp queries require resident int32 query IDs and preallocated out arrays on the topology’s device; no upload or readback is implicit. Warm up before CUDA graph capture. For nonempty batches, the valid prefix ends at world_starts[-1, -1]. If that required size exceeds capacity, starts are still reported but indices are left untouched: the caller must provide enough capacity for its selection domain, not consume a partial result.

Methods:

get_asset_prototype_world_index(topology, ...)	Return one world index per asset instance, retaining repeated memberships.
get_asset_prototype_unique_world_index(...)	Return each world containing an asset once, independently for every requested asset.
get_world_prototype_world_index(topology, ...)	Return the destination worlds using each requested world prototype.

static get_asset_prototype_world_index(topology: PrototypeWorldTopology, asset_prototype: int | np.ndarray | wp.array, *, out: tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array] | None = None) → tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array]

Return one world index per asset instance, retaining repeated memberships.

Parameters:

• topology – Numeric topology with NumPy or Warp storage.

• asset_prototype – One integer (NumPy only), or a 1-D integer array of asset-prototype IDs.

• out – Optional NumPy outputs, required Warp outputs. See the namespace’s result/capacity contract.

Returns:

Flat world indices and per-query world boundaries. A scalar is a batch of length one. Missing or unused asset IDs produce empty slices; shared instances use world -1.

static get_asset_prototype_unique_world_index(topology: PrototypeWorldTopology, asset_prototype: int | np.ndarray | wp.array, *, out: tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array] | None = None) → tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array]

Return each world containing an asset once, independently for every requested asset.

Parameters:

• topology – Numeric topology with NumPy or Warp storage.

• asset_prototype – One integer (NumPy only), or a 1-D integer array of asset-prototype IDs.

• out – Optional NumPy outputs, required Warp outputs. See the namespace’s result/capacity contract.

Returns:

Flat world indices and per-query world boundaries, as in query.get_asset_prototype_world_index(). Every world slice has length zero or one. Separate queries are not deduplicated together.

static get_world_prototype_world_index(topology: PrototypeWorldTopology, world_prototype: int | np.ndarray | wp.array, *, out: tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array] | None = None) → tuple[np.ndarray, np.ndarray] | tuple[wp.array, wp.array]

Return the destination worlds using each requested world prototype.

Parameters:

• topology – Numeric topology with NumPy or Warp storage.

• world_prototype – One integer (NumPy only), or a 1-D integer array of world-prototype IDs. Index -1 selects the shared world, even when empty.

• out – Optional NumPy outputs, required Warp outputs. See the namespace’s result/capacity contract.

Returns:

Flat world indices and per-query world boundaries, as in query.get_asset_prototype_world_index(). Unused world prototypes produce empty slices.

Additional Public Classes

class isaaclab.cloner.CloneCfg

Bases: object

Configuration for environment replication.

Holds the knobs InteractiveScene forwards to make_clone_plan() when building per-env layouts.

Methods:

__new__(*args, **kwargs)
__init__([clone_strategy, ...])

classmethod __new__(*args, **kwargs)

__init__(clone_strategy: ~collections.abc.Callable[[~numpy.ndarray, int], ~numpy.ndarray] = <factory>, clone_combinations: list[~isaaclab.cloner.cloner_cfg.InclusionSet] = <factory>, clone_template: str = <factory>, replicate_physics: bool = <factory>) → None

class isaaclab.cloner.InclusionSet

Bases: object

Legal clone combination defined by explicitly listing active assets.

Methods:

__new__(*args, **kwargs)
__init__([assets, weight])

classmethod __new__(*args, **kwargs)

__init__(assets: list[str] = <factory>, weight: float = <factory>) → None

class isaaclab.cloner.ReplicateSession

Bases: object

Author prototypes before dispatching one shared world topology.

Methods:

__init__(cfgs, num_clones, env_spacing, *[, ...])	Capture prototype declarations, composition choices, and USD authoring inputs.
__new__(*args, **kwargs)

__init__(cfgs: ~collections.abc.Iterable[~typing.Any], num_clones: int, env_spacing: float, *, clone_strategy: ~collections.abc.Callable[[~numpy.ndarray, int], ~numpy.ndarray] = <function sequential>, world_prototypes: ~collections.abc.Sequence[~collections.abc.Sequence[int]] | None = None, weights: ~collections.abc.Sequence[float] | None = None, replicate_physics: bool = True, env_template: str = '/World/envs/env_{}')

Capture prototype declarations, composition choices, and USD authoring inputs.

classmethod __new__(*args, **kwargs)

class isaaclab.cloner.UsdReplicateContext

Bases: object

Apply routed clone-plan sources to one USD stage.

Methods:

__init__(sim)
__new__(*args, **kwargs)

__init__(sim: SimulationContext)

classmethod __new__(*args, **kwargs)