Adds documentation on sensors (#5)

* adds sensor docs
* adds docs for array ops
* fixes docs about the device used for camera

docs/conf.py

@@ -78,7 +78,7 @@ autodoc_default_options = {
 # generate links to the documentation of objects in external projects
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
+    "numpy": ("http://docs.scipy.org/doc/numpy", None),
     "torch": ("https://pytorch.org/docs/stable/", None),
 }
 
@@ -94,6 +94,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md", "licenses/*
 autodoc_mock_imports = [
     "torch",
     "numpy",
+    "matplotlib",
     "scipy",
     "carb",
     "warp",

docs/requirements.txt

@@ -10,3 +10,4 @@ sphinx-copybutton
 # basic python
 numpy
 matplotlib
+warp-lang

docs/source/_static/refs.bib

@@ -86,3 +86,14 @@
   pages={2497-2503},
   doi={10.1109/IROS47612.2022.9981198}
 }
+
+@ARTICLE{frankhauser2018probabilistic,
+  author={Fankhauser, Péter and Bloesch, Michael and Hutter, Marco},
+  journal={IEEE Robotics and Automation Letters},
+  title={Probabilistic Terrain Mapping for Mobile Robots With Uncertain Localization},
+  year={2018},
+  volume={3},
+  number={4},
+  pages={3019-3026},
+  doi={10.1109/LRA.2018.2849506}
+}

docs/source/api/index.rst

@@ -14,6 +14,7 @@ omni.isaac.orbit extension
    orbit.objects.articulated
    orbit.objects.rigid
    orbit.robots
+   orbit.sensors
    orbit.utils
    orbit.utils.assets
    orbit.utils.kit

docs/source/api/orbit.sensors.rst

+omni.isaac.orbit.sensors
+========================
+
+Sensor Base
+-----------
+
+.. automodule:: omni.isaac.orbit.sensors.sensor_base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Camera
+------
+
+.. autoclass:: omni.isaac.orbit.sensors.camera.camera.Camera
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Data
+^^^^
+
+.. autoclass:: omni.isaac.orbit.sensors.camera.camera.CameraData
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Configuration
+^^^^^^^^^^^^^
+
+.. automodule:: omni.isaac.orbit.sensors.camera.camera_cfg
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utilities
+^^^^^^^^^
+
+.. automodule:: omni.isaac.orbit.sensors.camera.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Height Scanner
+--------------
+
+.. autoclass:: omni.isaac.orbit.sensors.height_scanner.height_scanner.HeightScanner
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Data
+^^^^
+
+.. autoclass:: omni.isaac.orbit.sensors.height_scanner.height_scanner.HeightScannerData
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Configuration
+^^^^^^^^^^^^^
+
+.. automodule:: omni.isaac.orbit.sensors.height_scanner.height_scanner_cfg
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utilities
+^^^^^^^^^
+
+.. automodule:: omni.isaac.orbit.sensors.height_scanner.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/orbit.utils.rst

@@ -19,6 +19,14 @@ Loading and saving data
    :undoc-members:
    :show-inheritance:
 
+Array operations
+~~~~~~~~~~~~~~~~
+
+.. automodule:: omni.isaac.orbit.utils.array
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Dictionary operations
 ~~~~~~~~~~~~~~~~~~~~~
 

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/camera/__init__.py

@@ -4,7 +4,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 """
-Camera.
+Camera wrapper around USD camera prim to provide an interface that follows the robotics convention.
 """
 
 from .camera import Camera, CameraData

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/camera/camera_cfg.py

@@ -12,25 +12,12 @@ from typing import List, Tuple
 # omni-isaac-orbit
 from omni.isaac.orbit.utils import configclass
 
+__all__ = ["PinholeCameraCfg", "FisheyeCameraCfg"]
+
 
 @configclass
 class PinholeCameraCfg:
-    """Configuration for a pinhole camera sensor.
-
-    The following sensor types are supported:
-
-        - "rgb": A rendered color image.
-        - "distance_to_camera": An image containing the distance to camera optical center.
-        - "distance_to_image_plane": An image containing distances of 3D points from camera plane along camera's z-axis.
-        - "normals": An image containing the local surface normal vectors at each pixel.
-        - "motion_vectors": An image containing the motion vector data at each pixel.
-        - "instance_segmentation": The instance segmentation data.
-        - "semantic_segmentation": The semantic segmentation data.
-        - "bounding_box_2d_tight": The tight 2D bounding box data (only contains non-occluded regions).
-        - "bounding_box_2d_loose": The loose 2D bounding box data (contains occluded regions).
-        - "bounding_box_3d": The 3D view space bounding box data.
-        - "occlusion": The occlusion information (such as instance id, semantic id and occluded ratio).
-    """
+    """Configuration for a pinhole camera sensor."""
 
     sensor_tick: float = 0.0
     """Simulation seconds between sensor buffers. Defaults to 0.0."""
@@ -43,7 +30,7 @@ class PinholeCameraCfg:
     semantic_types: List[str] = ["class"]
     """List of allowed semantic types the types. Defaults to ["class"].
 
-    For example, if `semantic_types` is [“class”], only the bounding boxes for prims with semantics of
+    For example, if semantic types is [“class”], only the bounding boxes for prims with semantics of
     type “class” will be retrieved.
 
     More information available at:
@@ -52,9 +39,8 @@ class PinholeCameraCfg:
 
     @configclass
     class UsdCameraCfg:
-        """USD related configuration for the sensor.
+        """USD related configuration of the sensor.
 
-        Note:
         The parameter is kept default from USD if it is set to :obj:`None`. This includes the default
         parameters (in case the sensor is created) or the ones set by the user (in case the sensor is
         loaded from existing USD stage).
@@ -91,37 +77,10 @@ class PinholeCameraCfg:
 
 @configclass
 class FisheyeCameraCfg(PinholeCameraCfg):
-    """Configuration for a fisheye camera sensor.
-
-    The following sensor types are supported:
-
-        - "rgb": A rendered color image.
-        - "distance_to_camera": An image containing the distance to camera optical center.
-        - "distance_to_image_plane": An image containing distances of 3D points from camera plane along camera's z-axis.
-        - "normals": An image containing the local surface normal vectors at each pixel.
-        - "motion_vectors": An image containing the motion vector data at each pixel.
-        - "instance_segmentation": The instance segmentation data.
-        - "semantic_segmentation": The semantic segmentation data.
-        - "bounding_box_2d_tight": The tight 2D bounding box data (only contains non-occluded regions).
-        - "bounding_box_2d_loose": The loose 2D bounding box data (contains occluded regions).
-        - "bounding_box_3d": The 3D view space bounding box data.
-        - "occlusion": The occlusion information (such as instance id, semantic id and occluded ratio).
-
-    """
+    """Configuration for a fisheye camera sensor."""
 
     @configclass
     class UsdCameraCfg(PinholeCameraCfg.UsdCameraCfg):
-        """USD related configuration for the sensor.
-
-        Note:
-            The parameter is kept default from USD if it is set to :obj:`None`. This includes the default
-            parameters (in case the sensor is created) or the ones set by the user (in case the sensor is
-            loaded from existing USD stage).
-
-        Reference:
-            * https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/manual_replicator_composer_parameter_list.html#camera-parameters
-            * https://graphics.pixar.com/usd/docs/api/class_usd_geom_camera.html
-        """
 
         fisheye_nominal_width: float = None
         """Nominal width of fisheye lens model."""

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/height_scanner/__init__.py

@@ -4,7 +4,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 """
-Height-scanner.
+Height-scanner based on ray-casting operations using PhysX ray-caster.
 """
 
 from .height_scanner import HeightScanner, HeightScannerData

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/height_scanner/height_scanner.py

@@ -3,19 +3,11 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-"""
-@author     Mayank Mittal
-@email      mittalma@ethz.ch
-@author     David Hoeller
-@email      dhoeller@nvidia.com
-
-@brief      Height-map scanner in Omniverse workflows.
-"""
 
 import numpy as np
 import scipy.spatial.transform as tf
 from dataclasses import dataclass
-from typing import List, Union
+from typing import List, Sequence
 
 import omni
 import omni.isaac.core.utils.prims as prim_utils
@@ -29,6 +21,8 @@ from ..sensor_base import SensorBase
 from .height_scanner_cfg import HeightScannerCfg
 from .height_scanner_marker import HeightScannerMarker
 
+__all__ = ["HeightScanner", "HeightScannerData"]
+
 
 @dataclass
 class HeightScannerData:
@@ -37,13 +31,19 @@ class HeightScannerData:
     position: np.ndarray = None
     """Position of the sensor origin in world frame."""
     orientation: np.ndarray = None
-    """Orientation of the sensor origin in quaternion (w, x, y, z) in world frame."""
+    """Orientation of the sensor origin in quaternion ``(w, x, y, z)`` in world frame."""
     hit_points: np.ndarray = None
-    """The end point locations of ray-casted rays."""
+    """The end point locations of ray-casted rays. Shape is (N, 3), where ``N`` is
+    the number of scan points."""
     hit_distance: np.ndarray = None
-    """The ray-cast travel distance from query point."""
+    """The ray-cast travel distance from query point. Shape is (N,), where ``N`` is
+    the number of scan points."""
     hit_status: np.ndarray = None
-    """Whether the ray hit an object or not."""
+    """Whether the ray hit an object or not. Shape is (N,), where ``N`` is
+    the number of scan points.
+
+    It is set to ``1`` if the ray hit an object, and ``0`` otherwise.
+    """
 
 
 class HeightScanner(SensorBase):
@@ -53,27 +53,20 @@ class HeightScanner(SensorBase):
     often we care about the terrain for locomotion. The height-map, also called elevation map, simplifies the
     terrain as a two-dimensional surface. Each grid-cell represents the height of the terrain.
 
-    Unlike algorithms which fuse depth measurements to create an elevation map [1], in this method we directly use
-    the PhysX API for ray-casting and query the height of the terrain from a set of query scan points. These points
-    represent the location of the grid cells.
+    Unlike algorithms which fuse depth measurements to create an elevation map :cite:p:`frankhauser2018probabilistic`,
+    in this method we directly use the PhysX API for ray-casting and query the height of the terrain from a set
+    of query scan points. These points represent the location of the grid cells.
 
     The height-scanner uses PhysX for ray-casting to collision bodies. To prevent the casting to certain prims
     in the scene (such as the robot on which height-scanner is present), one needs to provide the names of the
     prims to not check collision with as a part of the dictionary config.
 
-    The scanner offset :math:`(x_o, y_o, z_o)` is the offset of the sensor from the frame it is attached to. During the
-    `update(...)` or `buffer(...)`, the pose of the mounted frame needs to be provided.
+    The scanner offset :math:`(x_o, y_o, z_o)` is the offset of the sensor from the frame it is attached to.
+    During the :meth:`update` or :meth:`buffer`, the pose of the mounted frame needs to be provided.
 
     If visualization is enabled, rays that have a hit are displayed in red, while a miss is displayed in blue.
     During a miss, the point's distance is set to the maximum ray-casting distance.
 
-    References:
-        [1] Fankhauser, P., Bloesch, M., & Hutter, M. (2018). Probabilistic terrain mapping for mobile robots
-            with uncertain localization. IEEE Robotics and Automation Letters, 3(4), 3019-3026.
-
-    TODO:
-        Move this class to use generic range sensor from Isaac Sim.
-        Reference: https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/ext_omni_isaac_range_sensor.html#isaac-sim-generic-range-sensor-example
     """
 
     def __init__(self, cfg: HeightScannerCfg):
@@ -82,6 +75,8 @@ class HeightScanner(SensorBase):
         Args:
             cfg (HeightScannerCfg): The configuration parameters.
         """
+        # TODO: Use generic range sensor from Isaac Sim?
+        # Reference: https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/ext_omni_isaac_range_sensor.html#isaac-sim-generic-range-sensor-example
         # store inputs
         self.cfg = cfg
         # initialize base class
@@ -122,12 +117,12 @@ class HeightScanner(SensorBase):
 
     @property
     def prim_path(self) -> str:
-        """Returns: The path to the height-map sensor."""
+        """The path to the height-map sensor."""
         return self._sensor_prim.prim_paths[0]
 
     @property
     def data(self) -> HeightScannerData:
-        """Returns: Data related to height scanner."""
+        """Data related to height scanner."""
         return self._data
 
     """
@@ -137,8 +132,8 @@ class HeightScanner(SensorBase):
     def set_visibility(self, visible: bool):
         """Enables drawing of the scan points in the viewport.
 
-        Arguments:
-            visible {bool} -- Whether to draw scan points or not. (default: {True})
+        Args:
+            visible (bool) -- Whether to draw scan points or not.
         """
         # copy argument
         self._visualize = visible
@@ -151,7 +146,7 @@ class HeightScanner(SensorBase):
         If None is passed into argument, then no filtering is performed.
 
         Args:
-            names (List[str]): A list of prim names to ignore raycast collisions with.
+            names (List[str]): A list of prim names to ignore ray-cast collisions with.
         """
         # default
         if names is None:
@@ -202,27 +197,26 @@ class HeightScanner(SensorBase):
         self._data.position = None
         self._data.orientation = None
 
-    def update(self, dt: float, pos: Union[np.ndarray, List[float]], quat: Union[np.ndarray, List[float]]):
+    def update(self, dt: float, pos: Sequence[float], quat: Sequence[float]):
         """Updates the buffers at sensor frequency.
 
         Args:
             dt (float): The simulation time-step.
-            pos (Union[np.ndarray, List[float]]): Position of the frame to which the sensor is attached.
-            quat (Union[np.ndarray, List[float]]): Quaternion (w, x, y, z) of the frame to which the sensor is attached.
+            pos (Sequence[float]): Position of the frame to which the sensor is attached.
+            quat (Sequence[float]): Quaternion (w, x, y, z) of the frame to which the sensor is attached.
         """
         super().update(dt, pos, quat)
 
-    def buffer(self, pos: Union[np.ndarray, List[float]], quat: Union[np.ndarray, List[float]]):
+    def buffer(self, pos: Sequence[float], quat: Sequence[float]):
         """Fills the buffers of the sensor data.
 
-        This function does not perform any time-based checks and directly fills the data into the data container.
-
-        Warning:
-            Although this method is public, `update(dt)` should be the preferred way of filling buffers.
+        This function uses the input position and orientation to compute the ray-casting queries
+        and fill the buffers. If a collision is detected, then the hit distance is stored in the buffer.
+        Otherwise, the hit distance is set to the maximum value specified in the configuration.
 
         Args:
-            pos (Union[np.ndarray, List[float]]): Position of the frame to which the sensor is attached.
-            quat (Union[np.ndarray, List[float]]): Quaternion (w, x, y, z) of the frame to which the sensor is attached.
+            pos (Sequence[float]): Position of the frame to which the sensor is attached.
+            quat (Sequence[float]): Quaternion (w, x, y, z) of the frame to which the sensor is attached.
         """
         # convert to numpy for sanity
         pos = np.asarray(pos)

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/height_scanner/height_scanner_marker.py

@@ -19,12 +19,12 @@ class HeightScannerMarker:
     It creates two spherical markers of different colors. Based on the indices provided the referenced
     marker is activated.
 
-    Proto Indices (status):
-        - 0 -> ray miss (blue sphere).
-        - 1 -> successful ray hit (red sphere).
-        - 2 -> invisible ray (disabled visualization)
+    The status marker (proto-indices) of the point instancer is used to store the following information:
+
+    - :obj:`0` -> ray miss (blue sphere).
+    - :obj:`1` -> successful ray hit (red sphere).
+    - :obj:`2` -> invisible ray (disabled visualization)
 
-    TODO: Make this generic marker for all and put inside the `omni.isaac.orbit.marker` directory.
     """
 
     def __init__(self, prim_path: str, count: int, radius: float = 1.0) -> None:
@@ -44,6 +44,7 @@ class HeightScannerMarker:
         self._radius = radius
         # create manager for handling instancing of frame markers
         self._instancer_manager = UsdGeom.PointInstancer.Define(stage, prim_path)
+        # TODO: Make this generic marker for all and put inside the `omni.isaac.orbit.marker` directory.
         # create a child prim for the marker
         # -- target missed
         prim = prim_utils.create_prim(f"{prim_path}/point_miss", "Sphere", attributes={"radius": self._radius})

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/height_scanner/utils.py

@@ -16,23 +16,24 @@ __all__ = ["create_points_from_grid", "plot_height_grid"]
 
 
 def create_points_from_grid(size: Tuple[float, float], resolution: float) -> np.ndarray:
-    """Creates a list of points from 2D meshgrid.
+    """Creates a list of points from 2D mesh-grid.
 
     The terrain scan is approximated with a grid map of the input resolution.
-
-        By default, we consider the origin as the center of the local map and the scan size (X, Y) is the map size.
-        Given these settings, the elevation map spans from: `(- X / 2, - Y / 2)` to `(+ X / 2, + Y / 2)`.
+    By default, we consider the origin as the center of the local map and the scan size ``(X, Y)`` is the
+    map size. Given these settings, the elevation map spans from: ``(- X / 2, - Y / 2)`` to
+    ``(+ X / 2, + Y / 2)``.
 
     Example:
         For a grid of size (0.2, 0.2) with resolution of 0.1, the created points will first x-axis fixed, while the
         y-axis changes, i.e.:
-            ```
+
+        .. code-block:: none
+
             [
                 [-0.1, -0.1], [-0.1, 0.0], [-0.1, 0.1],
                 [0.0, -0.1], [0.0, 0.], [0.0, 0.1],
                 [0.1, -0.1], [0.1, 0.0], [0.1, 0.1],
             ]
-            ```
 
     Args:
         size (Tuple[float, float]): The 2D scan region along x and y directions (in meters).
@@ -57,9 +58,11 @@ def plot_height_grid(
 ) -> AxesImage:
     """Plots the sensor height-map distances using matplotlib.
 
+    If the axes is not provided, a new figure is created.
+
     Note:
         This method currently only supports if the grid is evenly spaced, i.e. the scan points are created using
-        `create_points_from_grid(...)` method.
+        :meth:`create_points_from_grid` method.
 
     Args:
         hit_distance (dict): The ray hit distance measured from the sensor.

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sensors/sensor_base.py

@@ -3,9 +3,10 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-"""Base class for sensors in Omniverse workflows.
+"""Base class for sensors.
 
-This class defines an interface similar to how the RobotBase class works.
+This class defines an interface for sensors similar to how the :class:`omni.isaac.orbit.robot.robot_base.RobotBase` class works.
+Each sensor class should inherit from this class and implement the abstract methods.
 """
 
 
@@ -14,21 +15,18 @@ from typing import Any
 
 
 class SensorBase:
-    """
-    The base class for implementation of a sensor.
+    """The base class for implementing a sensor.
 
     Note:
         These sensors are not vectorized yet.
-
-    Attributes:
-        frame (int) - Frame number when the measurement took place.
-        timestamp (float) - Simulation time of the measurement (in seconds).
-        sensor_tick (float) - Simulation seconds between sensor buffers (ticks).
     """
 
     def __init__(self, sensor_tick: float = 0.0):
         """Initialize the sensor class.
 
+        The sensor tick is the time between two sensor buffers. If the sensor tick is zero, then the sensor
+        buffers are filled at every simulation step.
+
         Args:
             sensor_tick (float, optional): Simulation seconds between sensor buffers. Defaults to 0.0.
         """
@@ -109,6 +107,10 @@ class SensorBase:
     def update(self, dt: float, *args, **kwargs):
         """Updates the buffers at sensor frequency.
 
+        This function performs time-based checks and fills the data into the data container. It
+        calls the function :meth:`buffer()` to fill the data. The function :meth:`buffer()` should
+        not be called directly.
+
         Args:
             dt (float): The simulation time-step.
             args (tuple): Other positional arguments passed to function :meth:`buffer()`.

source/extensions/omni.isaac.orbit/omni/isaac/orbit/utils/math.py

@@ -28,22 +28,26 @@ __all__ = [
     # General
     "wrap_to_pi",
     "saturate",
+    "copysign",
+    # General-Isaac Sim
     "normalize",
     "scale_transform",
     "unscale_transform",
-    "copysign",
     # Rotation
-    "quat_mul",
+    "matrix_from_quat",
     "quat_inv",
-    "quat_conjugate",
-    "quat_apply",
-    "quat_rotate",
-    "quat_rotate_inverse",
     "quat_from_euler_xyz",
     "quat_apply_yaw",
     "quat_box_minus",
     "euler_xyz_from_quat",
     "axis_angle_from_quat",
+    # Rotation-Isaac Sim
+    "quat_apply",
+    "quat_from_angle_axis",
+    "quat_mul",
+    "quat_conjugate",
+    "quat_rotate",
+    "quat_rotate_inverse",
     # Transformations
     "combine_frame_transforms",
     "subtract_frame_transforms",