Source code for isaaclab.terrains.terrain_importer_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, Literal

import isaaclab.sim as sim_utils
from isaaclab.sim.spawners import materials
from isaaclab.utils import configclass

if TYPE_CHECKING:
    from .terrain_generator_cfg import TerrainGeneratorCfg
    from .terrain_importer import TerrainImporter




@configclass
class TerrainImporterCfg:
    """Configuration for the terrain manager."""

    class_type: type[TerrainImporter] | str = "{DIR}.terrain_importer:TerrainImporter"
    """The class to use for the terrain importer.

    Defaults to :class:`isaaclab.terrains.terrain_importer.TerrainImporter`.
    """

    collision_group: int = -1
    """The collision group of the terrain. Defaults to -1."""

    prim_path: str = MISSING
    """The absolute path of the USD terrain prim.

    All sub-terrains are imported relative to this prim path.
    """

    num_envs: int = 1
    """The number of environment origins to consider. Defaults to 1.

    In case, the :class:`~isaaclab.scene.InteractiveSceneCfg` is used, this parameter gets overridden by
    :attr:`isaaclab.scene.InteractiveSceneCfg.num_envs` attribute.
    """

    terrain_type: Literal["generator", "plane", "usd"] = "generator"
    """The type of terrain to generate. Defaults to "generator".

    Available options are "plane", "usd", and "generator".
    """

    terrain_generator: TerrainGeneratorCfg | None = None
    """The terrain generator configuration.

    Only used if ``terrain_type`` is set to "generator".
    """

    usd_path: str | None = None
    """The path to the USD file containing the terrain.

    Only used if ``terrain_type`` is set to "usd".
    """

    env_spacing: float | None = None
    """The spacing between environment origins when defined in a grid. Defaults to None.

    Note:
      This parameter is used only when the ``terrain_type`` is "plane" or "usd" or if
      :attr:`use_terrain_origins` is False.
    """

    use_terrain_origins: bool = True
    """Whether to set the environment origins based on the terrain origins or in a grid
    according to :attr:`env_spacing`. Defaults to True.

    Note:
      This parameter is used only when the :attr:`terrain type` is "generator".
    """

    visual_material: sim_utils.VisualMaterialCfg | None = MISSING
    """The visual material of the terrain. The default depends on :attr:`terrain_type`.

    This parameter is used for both the "generator" and "plane" terrains.

    - If the ``terrain_type`` is "generator", a dark material is used by default. The material is
      created at the path ``{prim_path}/visualMaterial`` and applied to all the sub-terrains.
    - If the ``terrain_type`` is "plane" and the material defines a diffuse color, then that color
      tints the imported ground plane. If no material is provided, the ground plane's authored
      appearance is preserved.

    Set this parameter to None explicitly to avoid binding a visual material to a generated terrain.
    """

    physics_material: (
        materials.RigidBodyMaterialBaseCfg
        | materials.RigidBodyMaterialFragment
        | list[materials.RigidBodyMaterialFragment]
    ) = materials.RigidBodyMaterialBaseCfg()
    """The physics material of the terrain. Defaults to a default physics material.

    The material is created at the path: ``{prim_path}/physicsMaterial``.

    .. note::
        This parameter is used only when the ``terrain_type`` is "generator" or "plane".

    Accepts a legacy rigid material cfg, a single rigid-material fragment, or a list of
    rigid-material fragments.
    """

    max_init_terrain_level: int | None = None
    """The maximum initial terrain level for defining environment origins. Defaults to None.

    The terrain levels are specified by the number of rows in the grid arrangement of
    sub-terrains. If None, then the initial terrain level is set to the maximum
    terrain level available (``num_rows - 1``).

    Note:
      This parameter is used only when sub-terrain origins are defined.
    """

    debug_vis: bool = False
    """Whether to enable visualization of terrain origins for the terrain. Defaults to False."""

    def __post_init__(self):
        """Resolve the terrain-type-specific visual material default."""
        if isinstance(self.visual_material, type(MISSING)):
            if self.terrain_type == "generator":
                self.visual_material = sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 0.0, 0.0))
            else:
                self.visual_material = None