Source code for isaaclab.sensors.contact_sensor.contact_sensor_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 typing import TYPE_CHECKING, cast
from isaaclab.markers import VisualizationMarkersCfg
from isaaclab.markers.config import BLUE_ARROW_X_MARKER_CFG, CONTACT_SENSOR_MARKER_CFG, RED_ARROW_X_MARKER_CFG
from isaaclab.utils import configclass
from ..sensor_base_cfg import SensorBaseCfg
if TYPE_CHECKING:
from isaaclab.sim.spawners.from_files.from_files_cfg import UsdFileCfg
from .contact_sensor import ContactSensor
[docs]
@configclass
class ContactSensorCfg(SensorBaseCfg):
"""Configuration for the contact sensor.
Sensing bodies are selected via :attr:`SensorBaseCfg.prim_path`. Filter bodies for
per-partner force reporting are selected via :attr:`filter_prim_paths_expr`.
Only body-level sensing and filtering are supported. For shape-level granularity,
see ``NewtonContactSensorCfg`` in ``isaaclab_newton``.
"""
class_type: type["ContactSensor"] | str = "{DIR}.contact_sensor:ContactSensor"
track_pose: bool = False
"""Whether to track the pose of the sensor's origin. Defaults to False."""
track_contact_points: bool = False
"""Whether to track the contact point locations. Defaults to False."""
track_friction_forces: bool = False
"""Whether to track friction contact forces. Defaults to False.
Newton reports aggregate and per-filter friction forces. PhysX reports per-filter friction
forces only and therefore requires :attr:`filter_prim_paths_expr`.
"""
max_contact_data_count_per_prim: int | None = None
"""The maximum number of contacts across all batches of the sensor to keep track of. Default is 4, where supported.
This parameter sets the total maximum counts of the simulation across all bodies and environments. The total number
of contacts allowed is max_contact_data_count_per_prim*num_envs*num_sensor_bodies.
.. note::
If the environment is very contact rich it is suggested to increase this parameter to avoid out of bounds memory
errors and loss of contact data leading to inaccurate measurements.
"""
track_air_time: bool = False
"""Whether to track the air/contact time of the bodies (time between contacts). Defaults to False."""
force_threshold: float | None = None
"""The threshold on the norm of the contact force that determines whether two bodies are in collision or not.
Defaults to None, in which case the sensor backend chooses an appropriate value.
This value is only used for tracking the mode duration (the time in contact or in air),
if :attr:`track_air_time` is True.
"""
history_length: int = 0
"""Number of past frames to store in the sensor buffers. Defaults to 0, which means that only
the current data is stored (no history).
A positive value updates the sensor buffers at :attr:`update_period` during scene updates,
including when the scene uses lazy sensor updates. This preserves physics-step contact history
until it is read at a later environment step.
"""
filter_prim_paths_expr: list[str] = []
"""List of body prim path expressions to filter contacts against. Defaults to empty,
meaning contacts with all bodies are aggregated into the net force.
If provided, a per-partner force matrix (:attr:`ContactSensorData.normal_force_matrix_w`) is
reported in addition to the net force. Each expression is matched against body prim paths
in the scene.
For shape-level filtering, see ``NewtonContactSensorCfg`` in ``isaaclab_newton``.
.. note::
Expressions can contain the environment namespace regex ``{ENV_REGEX_NS}``, which
is replaced with the environment namespace.
Example: ``{ENV_REGEX_NS}/Object`` becomes ``/World/envs/env_[^/]+/Object``.
.. attention::
Filtered contact reporting only works when :attr:`SensorBaseCfg.prim_path` matches a
single primitive per environment. For many-to-many filtering, see
``NewtonContactSensorCfg`` in ``isaaclab_newton``.
"""
sensor_shape_prim_expr: list[str] = []
"""List of shape prim path expressions for shape-level contact sensing. Defaults to empty,
meaning sensing is at the body level (via :attr:`~isaaclab.sensors.SensorBaseCfg.prim_path`).
**Newton backend only** (ignored by the PhysX and OvPhysX backends). A shape is an individual
collision geometry attached to a body. If non-empty, :attr:`prim_path` is ignored for the
sensing objects and these shape expressions are used instead.
Full-matched against shape paths, so an expression naming a body selects nothing:
write ``{ENV_REGEX_NS}/Box[^/]*/.*`` to reach the shapes below it.
"""
filter_shape_prim_expr: list[str] = []
"""List of shape prim path expressions to filter contacts against at the shape level. Defaults to
empty, meaning filter partners are resolved at the body level (via :attr:`filter_prim_paths_expr`).
**Newton backend only** (ignored by the PhysX and OvPhysX backends). If provided, the force
matrix reports per-shape contact forces; mutually exclusive with :attr:`filter_prim_paths_expr`.
Matched against shape paths on the same terms as :attr:`sensor_shape_prim_expr`.
"""
visualizer_cfg: VisualizationMarkersCfg = CONTACT_SENSOR_MARKER_CFG.replace(prim_path="/Visuals/ContactSensor")
"""The configuration object for the visualization markers. Defaults to CONTACT_SENSOR_MARKER_CFG.
.. note::
This attribute is only used when debug visualization is enabled.
"""
normal_force_visualizer_cfg: VisualizationMarkersCfg = BLUE_ARROW_X_MARKER_CFG.replace(
prim_path="/Visuals/ContactSensor"
)
"""Configuration for net normal-force arrows."""
cast("UsdFileCfg", normal_force_visualizer_cfg.markers["arrow"]).scale = (0.04, 0.04, 0.2)
friction_force_visualizer_cfg: VisualizationMarkersCfg = RED_ARROW_X_MARKER_CFG.replace(
prim_path="/Visuals/ContactSensor"
)
"""Configuration for net friction-force arrows."""
cast("UsdFileCfg", friction_force_visualizer_cfg.markers["arrow"]).scale = (0.04, 0.04, 0.2)
force_visualization_scale: float = 0.01
"""Arrow length per force magnitude [m/N]."""