Source code for isaaclab.sensors.ray_caster.ray_caster_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

"""Configuration for the ray-cast sensor."""

from __future__ import annotations

from dataclasses import MISSING
from typing import TYPE_CHECKING, Literal

from isaaclab.markers import VisualizationMarkersCfg
from isaaclab.markers.config import RAY_CASTER_MARKER_CFG
from isaaclab.sim.spawners.sensors.sensors_cfg import SensorFrameCfg
from isaaclab.utils.configclass import configclass

from ..sensor_base_cfg import SensorBaseCfg
from .patterns.patterns_cfg import PatternBaseCfg

if TYPE_CHECKING:
    from .ray_caster import RayCaster




@configclass
class RayCasterCfg(SensorBaseCfg):
    """Configuration for the ray-cast sensor."""



    @configclass
    class OffsetCfg:
        """The offset pose of the sensor's frame from the sensor's parent frame."""

        pos: tuple[float, float, float] = (0.0, 0.0, 0.0)
        """Translation w.r.t. the parent 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) w.r.t. the parent frame. Defaults to (0.0, 0.0, 0.0, 1.0)."""


    class_type: type[RayCaster] | str = "{DIR}.ray_caster:RayCaster"

    spawn: SensorFrameCfg | None = SensorFrameCfg()
    """Spawn configuration for the sensor Xform prim.

    A plain USD Xform is created at :attr:`prim_path` before initialization, matching the
    pattern used by :class:`~isaaclab.sensors.camera.camera_cfg.CameraCfg` (which spawns a
    Camera prim). The :attr:`prim_path` can be either:

    - A **new** child path under a parent link (e.g. ``{ENV_REGEX_NS}/Robot/base``).
    - A **physics body** path (e.g. ``{ENV_REGEX_NS}/Robot/base``). In this case, the sensor
      will automatically create a child Xform at ``{prim_path}``.

    If ``None``, the prim at :attr:`prim_path` must already exist on the USD stage and must
    **not** be a physics body.
    """

    mesh_prim_paths: list[str] = MISSING
    """The list of mesh primitive paths to ray cast against.

    .. note::
        Currently, only a single static mesh is supported. We are working on supporting multiple
        static meshes and dynamic meshes.
    """

    offset: OffsetCfg = OffsetCfg()
    """The offset pose of the sensor's frame from the sensor's parent frame. Defaults to identity."""

    ray_alignment: Literal["base", "yaw", "world"] = "base"
    """Specify in what frame the rays are projected onto the ground. Default is "base".

    The options are:

    * ``base`` if the rays' starting positions and directions track the full root position and orientation.
    * ``yaw`` if the rays' starting positions track root position and the yaw component of the orientation,
      while ray directions remain fixed in world frame. This is useful for ray-casting height maps where
      the scan footprint should follow the body heading without tilting when the body pitches or rolls.
    * ``world`` if rays' starting positions and directions are always fixed. This is useful in combination
      with a mapping package on the robot and querying ray-casts in a global frame.
    """

    pattern_cfg: PatternBaseCfg = MISSING
    """The pattern that defines the local ray starting positions and directions."""

    max_distance: float = 1e6
    """Maximum distance (in meters) from the sensor to ray cast to. Defaults to 1e6."""

    drift_range: tuple[float, float] = (0.0, 0.0)
    """The range of drift (in meters) to add to the ray starting positions (xyz) in world frame. Defaults to (0.0, 0.0).

    For floating base robots, this is useful for simulating drift in the robot's pose estimation.
    """

    ray_cast_drift_range: dict[str, tuple[float, float]] = {"x": (0.0, 0.0), "y": (0.0, 0.0), "z": (0.0, 0.0)}
    """The range of drift (in meters) to add to the projected ray points in local projection frame. Defaults to
    a dictionary with zero drift for each x, y and z axis.

    For floating base robots, this is useful for simulating drift in the robot's pose estimation.
    """

    visualizer_cfg: VisualizationMarkersCfg = RAY_CASTER_MARKER_CFG.replace(prim_path="/Visuals/RayCaster")
    """The configuration object for the visualization markers. Defaults to RAY_CASTER_MARKER_CFG.

    .. note::
        This attribute is only used when debug visualization is enabled.
    """