[isaacsim.core.cloner] Isaac Sim Cloner#

Version: 1.6.3

The Cloner extension provides a set of APIs to clone prims and environments in an efficient way as well as filtering the collisions across the clones if needed.

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.core.cloner

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.core.cloner" = {}

Open the Window > Extensions menu in a running application instance and search for isaacsim.core.cloner. Then, toggle the enable control button if it is not already active.

API#

Python API#

Cloner

This class provides a set of simple APIs to make duplication of objects simple.

GridCloner

A specialized Cloner class that automatically generates clones in a grid pattern.

class Cloner(stage: pxr.Usd.Stage = None)#

Bases: object

This class provides a set of simple APIs to make duplication of objects simple.

Objects can be cloned using this class to create copies of the same object, placed at user-specified locations in the scene.

Note that the cloning process is performed in a for-loop, so performance should be expected to follow linear scaling with an increase of clones.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 4)
>>> cloner.clone(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
... )
clone(
source_prim_path: str,
prim_paths: List[str],
positions: ndarray | torch.Tensor = None,
orientations: ndarray | torch.Tensor = None,
replicate_physics: bool = False,
base_env_path: str = None,
root_path: str = None,
copy_from_source: bool = False,
unregister_physics_replication: bool = False,
enable_env_ids: bool = False,
clone_in_fabric: bool = False,
)#

Clone a source prim at user-specified destination paths.

Clones will be placed at user-specified positions and orientations.

Parameters:

  • source_prim_path – Path of the source object.

  • prim_paths – List of destination paths.

  • positions – An array containing target positions of clones. Dimension must equal the length of prim_paths. Defaults to None, in which case clones will be placed at (0, 0, 0).

  • orientations – An array containing target orientations of clones as quaternions (w, x, y, z). Dimension must equal the length of prim_paths. Defaults to None, in which case clones will have identity orientation (1, 0, 0, 0).

  • replicate_physics – Uses omni.physics replication. This will replicate physics properties directly for paths beginning with root_path and skip physics parsing for anything under the base_env_path.

  • base_env_path – Path to namespace for all environments. Required if replicate_physics=True and define_base_env() was not called.

  • root_path – Prefix path for each environment. Required if replicate_physics=True and generate_paths() was not called.

  • copy_from_source – Setting this to False will inherit all clones from the source prim; any changes made to the source prim will be reflected in the clones. Setting this to True will make copies of the source prim when creating new clones; changes to the source prim will not be reflected in clones. Defaults to False. Note that setting this to True will take longer to execute.

  • unregister_physics_replication – Setting this to True will unregister the physics replicator on the current stage.

  • enable_env_ids – Setting this enables co-location of clones in physics with automatic filtering of collisions between clones.

  • clone_in_fabric – Whether to perform cloning operations in Fabric for improved performance.

Raises:

  • ValueError – If the dimension of positions does not match the number of prim_paths.

  • ValueError – If the dimension of orientations does not match the number of prim_paths.

  • Exception – If the source prim does not exist.

Example:

>>> import numpy as np
>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 4)
>>>
>>> # Clone with positions
>>> positions = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]])
>>> cloner.clone(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
...     positions=positions,
... )
define_base_env(base_env_path: str)#

Create a USD Scope at base_env_path.

This is designed to be the parent that holds all clones.

Parameters:

base_env_path – Path to create the USD Scope at.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
disable_change_listener()#

Disable USD notice handlers to improve cloning performance.

This method temporarily disables various USD notice handlers including the PhysX UI notice handler, Fabric USD notice handler, and SimulationManager notice handler. This prevents expensive recomputation during batch cloning operations.

Note

Call enable_change_listener() after cloning is complete to restore the notice handlers.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.disable_change_listener()
>>> # Perform cloning operations...
>>> cloner.enable_change_listener()
enable_change_listener()#

Re-enable USD notice handlers after cloning operations.

This method restores the USD notice handlers that were disabled by disable_change_listener(). It re-enables the PhysX UI notice handler, Fabric USD notice handler, and SimulationManager notice handler if they were previously enabled.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.disable_change_listener()
>>> # Perform cloning operations...
>>> cloner.enable_change_listener()
filter_collisions(
physicsscene_path: str,
collision_root_path: str,
prim_paths: List[str],
global_paths: List[str] = [],
)#

Filter collisions between clones.

Clones will not collide with each other, but can collide with objects specified in global_paths. This method uses inverted collision group filtering for more efficient collision filtering across environments.

Parameters:

  • physicsscene_path – Path to PhysicsScene object in stage.

  • collision_root_path – Path to place collision groups under.

  • prim_paths – Paths of objects to filter out collision.

  • global_paths – Paths of objects to generate collision with all clones (e.g. ground plane).

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 4)
>>> cloner.clone(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
... )
>>> cloner.filter_collisions(
...     physicsscene_path="/World/PhysicsScene",
...     collision_root_path="/World/collisions",
...     prim_paths=prim_paths,
...     global_paths=["/World/ground_plane"],
... )
generate_paths(root_path: str, num_paths: int)#

Generate a list of paths under the root path specified.

Parameters:

  • root_path – Base path where new paths will be created under.

  • num_paths – Number of paths to generate.

Returns:

A list of paths in the format {root_path}_{i} where i ranges from 0 to num_paths - 1.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> paths = cloner.generate_paths("/World/envs/env", 4)
>>> paths
['/World/envs/env_0', '/World/envs/env_1', '/World/envs/env_2', '/World/envs/env_3']
replicate_physics(
source_prim_path: str,
prim_paths: list,
base_env_path: str,
root_path: str,
enable_env_ids: bool = False,
clone_in_fabric: bool = False,
)#

Replicate physics properties directly in omni.physics.

This avoids performance bottlenecks when parsing physics by using the PhysX replicator interface to replicate physics properties directly.

Parameters:

  • source_prim_path – Path of the source object.

  • prim_paths – List of destination paths.

  • base_env_path – Path to namespace for all environments.

  • root_path – Prefix path for each environment.

  • enable_env_ids – Whether to use envIDs functionality in physics to enable co-location of clones. Clones will be filtered automatically.

  • clone_in_fabric – Whether to perform cloning in Fabric.

Raises:

  • ValueError – If base_env_path is None and define_base_env() was not called.

  • ValueError – If root_path is None and generate_paths() was not called.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 4)
>>> cloner.replicate_physics(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
...     base_env_path="/World/envs",
...     root_path="/World/envs/env_",
... )
class GridCloner(
spacing: float,
num_per_row: int = -1,
stage: pxr.Usd.Stage = None,
)#

Bases: Cloner

A specialized Cloner class that automatically generates clones in a grid pattern.

This class extends Cloner to provide automatic grid-based positioning of clones, simplifying the creation of environments arranged in a regular grid.

Example:

>>> from isaacsim.core.cloner import GridCloner
>>>
>>> cloner = GridCloner(spacing=2.0)
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 9)
>>> positions = cloner.clone(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
... )
clone(
source_prim_path: str,
prim_paths: List[str],
position_offsets: ndarray = None,
orientation_offsets: ndarray = None,
replicate_physics: bool = False,
base_env_path: str = None,
root_path: str = None,
copy_from_source: bool = False,
enable_env_ids: bool = False,
clone_in_fabric: bool = False,
)#

Create clones in a grid pattern with automatically computed positions.

Parameters:

  • source_prim_path – Path of the source object.

  • prim_paths – List of destination paths.

  • position_offsets – Positions to be applied as local translations on top of computed clone position. Defaults to None, no offset will be applied.

  • orientation_offsets – Orientations to be applied as local rotations for each clone as quaternions (w, x, y, z). Defaults to None, no offset will be applied.

  • replicate_physics – Uses omni.physics replication. This will replicate physics properties directly for paths beginning with root_path and skip physics parsing for anything under the base_env_path.

  • base_env_path – Path to namespace for all environments. Required if replicate_physics=True and define_base_env() was not called.

  • root_path – Prefix path for each environment. Required if replicate_physics=True and generate_paths() was not called.

  • copy_from_source – Setting this to False will inherit all clones from the source prim; any changes made to the source prim will be reflected in the clones. Setting this to True will make copies of the source prim when creating new clones; changes to the source prim will not be reflected in clones. Defaults to False. Note that setting this to True will take longer to execute.

  • enable_env_ids – Setting this enables co-location of clones in physics with automatic filtering of collisions between clones.

  • clone_in_fabric – Whether to perform cloning operations in Fabric for improved performance.

Returns:

Computed positions of all clones.

Example:

>>> from isaacsim.core.cloner import GridCloner
>>>
>>> cloner = GridCloner(spacing=2.0)
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 9)
>>> positions = cloner.clone(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
... )
>>> len(positions)
9
define_base_env(base_env_path: str)#

Create a USD Scope at base_env_path.

This is designed to be the parent that holds all clones.

Parameters:

base_env_path – Path to create the USD Scope at.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
disable_change_listener()#

Disable USD notice handlers to improve cloning performance.

This method temporarily disables various USD notice handlers including the PhysX UI notice handler, Fabric USD notice handler, and SimulationManager notice handler. This prevents expensive recomputation during batch cloning operations.

Note

Call enable_change_listener() after cloning is complete to restore the notice handlers.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.disable_change_listener()
>>> # Perform cloning operations...
>>> cloner.enable_change_listener()
enable_change_listener()#

Re-enable USD notice handlers after cloning operations.

This method restores the USD notice handlers that were disabled by disable_change_listener(). It re-enables the PhysX UI notice handler, Fabric USD notice handler, and SimulationManager notice handler if they were previously enabled.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.disable_change_listener()
>>> # Perform cloning operations...
>>> cloner.enable_change_listener()
filter_collisions(
physicsscene_path: str,
collision_root_path: str,
prim_paths: List[str],
global_paths: List[str] = [],
)#

Filter collisions between clones.

Clones will not collide with each other, but can collide with objects specified in global_paths. This method uses inverted collision group filtering for more efficient collision filtering across environments.

Parameters:

  • physicsscene_path – Path to PhysicsScene object in stage.

  • collision_root_path – Path to place collision groups under.

  • prim_paths – Paths of objects to filter out collision.

  • global_paths – Paths of objects to generate collision with all clones (e.g. ground plane).

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 4)
>>> cloner.clone(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
... )
>>> cloner.filter_collisions(
...     physicsscene_path="/World/PhysicsScene",
...     collision_root_path="/World/collisions",
...     prim_paths=prim_paths,
...     global_paths=["/World/ground_plane"],
... )
generate_paths(root_path: str, num_paths: int)#

Generate a list of paths under the root path specified.

Parameters:

  • root_path – Base path where new paths will be created under.

  • num_paths – Number of paths to generate.

Returns:

A list of paths in the format {root_path}_{i} where i ranges from 0 to num_paths - 1.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> paths = cloner.generate_paths("/World/envs/env", 4)
>>> paths
['/World/envs/env_0', '/World/envs/env_1', '/World/envs/env_2', '/World/envs/env_3']
get_clone_transforms(
num_clones: int,
position_offsets: ndarray = None,
orientation_offsets: ndarray = None,
)#

Compute the positions and orientations of clones in a grid.

Parameters:

  • num_clones – Number of clones.

  • position_offsets – Positions to be applied as local translations on top of computed clone position. Defaults to None, no offset will be applied.

  • orientation_offsets – Orientations to be applied as local rotations for each clone as quaternions (w, x, y, z). Defaults to None, no offset will be applied.

Returns:

  • positions: Computed positions of all clones.

  • orientations: Computed orientations of all clones as quaternions (w, x, y, z).

Return type:

A tuple containing

Raises:

  • ValueError – If the dimension of position_offsets does not match num_clones.

  • ValueError – If the dimension of orientation_offsets does not match num_clones.

Example:

>>> import numpy as np
>>> from isaacsim.core.cloner import GridCloner
>>>
>>> cloner = GridCloner(spacing=2.0)
>>> positions, orientations = cloner.get_clone_transforms(num_clones=4)
>>> len(positions)
4
replicate_physics(
source_prim_path: str,
prim_paths: list,
base_env_path: str,
root_path: str,
enable_env_ids: bool = False,
clone_in_fabric: bool = False,
)#

Replicate physics properties directly in omni.physics.

This avoids performance bottlenecks when parsing physics by using the PhysX replicator interface to replicate physics properties directly.

Parameters:

  • source_prim_path – Path of the source object.

  • prim_paths – List of destination paths.

  • base_env_path – Path to namespace for all environments.

  • root_path – Prefix path for each environment.

  • enable_env_ids – Whether to use envIDs functionality in physics to enable co-location of clones. Clones will be filtered automatically.

  • clone_in_fabric – Whether to perform cloning in Fabric.

Raises:

  • ValueError – If base_env_path is None and define_base_env() was not called.

  • ValueError – If root_path is None and generate_paths() was not called.

Example:

>>> from isaacsim.core.cloner import Cloner
>>>
>>> cloner = Cloner()
>>> cloner.define_base_env("/World/envs")
>>> prim_paths = cloner.generate_paths("/World/envs/env", 4)
>>> cloner.replicate_physics(
...     source_prim_path="/World/envs/env_0",
...     prim_paths=prim_paths,
...     base_env_path="/World/envs",
...     root_path="/World/envs/env_",
... )