Source code for isaaclab.assets.asset_base_cfg

# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

from __future__ import annotations

from dataclasses import MISSING
from typing import TYPE_CHECKING, Any, Literal

from isaaclab.sim import SpawnerCfg
from isaaclab.utils import configclass

if TYPE_CHECKING:
    from .asset import Asset




@configclass
class AssetBaseCfg:
    """The base configuration class for an asset's parameters.

    See :class:`~isaaclab.assets.Asset` and :class:`~isaaclab.assets.AssetBase` for authoring-only and
    runtime-view assets.
    """

    @configclass
    class InitialStateCfg:
        """Initial state of the asset.

        This defines the default initial state of the asset when it is spawned into the simulation, as
        well as the default state when the simulation is reset.

        After parsing the initial state, the asset class stores this information in the :attr:`data`
        attribute of the asset class. This can then be accessed by the user to modify the state of the asset
        during the simulation, for example, at resets.
        """

        # root position
        pos: tuple[float, float, float] = (0.0, 0.0, 0.0)
        """Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0)."""
        rot: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 1.0)
        """Quaternion rotation (x, y, z, w) of the root in simulation world frame.
        Defaults to (0.0, 0.0, 0.0, 1.0).
        """

    class_type: type[Asset] | str = "{DIR}.asset:Asset"
    """The associated asset class. Defaults to :class:`~isaaclab.assets.Asset`, which authors the asset
    without creating a runtime simulation view.

    Physics-backed asset classes should inherit from :class:`~isaaclab.assets.AssetBase`.
    """

    cloning_contexts: tuple[str | type, ...] | None = None
    """Cloning contexts for this asset. Defaults to None.

    Entries are ``"module:ContextClass"`` references (or classes). If None, planning
    routes the asset to the active physics manager's clone context. An empty tuple
    requests no explicit physics context.
    :class:`~isaaclab.cloner.UsdReplicateContext` is still added automatically when ``spawn``
    is set and Kit is available; listing it explicitly forces USD replication even without Kit.
    """

    prim_path: str = MISSING
    """Prim path (or expression) to the asset.

    .. note::
        The expression can contain the environment namespace regex ``{ENV_REGEX_NS}`` which
        will be replaced with the environment namespace.

        Example: ``{ENV_REGEX_NS}/Robot`` will be replaced with ``/World/envs/env_[^/]+/Robot``.
    """

    spawn: SpawnerCfg | None = None
    """Spawn configuration for the asset. Defaults to None.

    If None, then no prims are spawned by the asset class. Instead, it is assumed that the
    asset is already present in the scene.
    """

    init_state: InitialStateCfg = InitialStateCfg()
    """Initial state of the rigid object. Defaults to identity pose."""

    collision_group: Literal[0, -1] = 0
    """Collision group of the asset. Defaults to ``0``.

    * ``-1``: global collision group (collides with all assets in the scene).
    * ``0``: local collision group (collides with other assets in the same environment).
    """

    debug_vis: bool = False
    """Whether to enable debug visualization for the asset. Defaults to ``False``."""

    disable_shape_checks: bool | None = None
    """Disable shape/dtype validation in setter and writer methods.

    When ``True``, :meth:`~AssetBase.assert_shape_and_dtype` and
    :meth:`~AssetBase.assert_shape_and_dtype_mask` become no-ops,
    eliminating per-call assertion overhead.

    When ``False``, shape checks are always enabled, even under ``python -O``.

    When ``None`` (the default), shape checks follow Python's ``__debug__``
    flag — enabled in normal mode, disabled with ``python -O``.
    """

    def _post_spawn(self, stage: Any) -> None:
        """Hook invoked by :class:`~isaaclab.assets.Asset` after its spawner returns a valid prim.

        The default implementation is a no-op. Subclasses that need to author additional
        USD schemas tied to this asset (for example, :class:`~isaaclab.assets.ArticulationCfg`
        which authors ``NewtonActuator`` prims from its ``actuators`` mapping) should
        override this method.

        Args:
            stage: The USD stage on which the asset was spawned.
        """
        pass