Attention

As of June 30, 2025, the Isaac ROS Buildfarm for Isaac ROS 2.1 on Ubuntu 20.04 Focal is no longer supported.

Due to an isolated infrastructure event, all ROS 2 Humble Debian packages that were previously built for Ubuntu 20.04 are no longer available in the Isaac Apt Repository. All artifacts for Isaac ROS 3.0 and later are built and maintained with a more robust pipeline.

Users are encouraged to migrate to the latest version of Isaac ROS. The source code for Isaac ROS 2.1 continues to be available on the release-2.1 branches of the Isaac ROS GitHub repositories.

The original documentation for Isaac ROS 2.1 is preserved below.

Tutorial for Freespace Segmentation using a RealSense Camera

https://media.githubusercontent.com/media/NVIDIA-ISAAC-ROS/.github/main/resources/isaac_ros_docs/repositories_and_packages/isaac_ros_freespace_segmentation/realsense_example.gif/

Overview

This tutorial demonstrates how to use a RealSense camera and isaac_ros_bi3d_freespace to create a local occupancy grid.

Note

This tutorial requires a compatible RealSense camera from the list of available cameras.

Tutorial Walkthrough

  1. Complete the RealSense setup tutorial.

  2. Complete steps 1-7 described in the Quickstart Guide.

  3. Open a new terminal and launch the Docker container using the run_dev.sh script:

    cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
      ./scripts/run_dev.sh
    
  4. Build and source the workspace:

    cd /workspaces/isaac_ros-dev && \
      colcon build --symlink-install && \
      source install/setup.bash
    
  5. Set your camera as shown in the image below, which is on a tripod ~10cm tall and parallel to the ground. Or you can change the static transform in the launch file here, according to the placement of your camera with respect to an occupancy grid origin frame.

https://media.githubusercontent.com/media/NVIDIA-ISAAC-ROS/.github/main/resources/isaac_ros_docs/repositories_and_packages/isaac_ros_freespace_segmentation/realsense_camera_position.jpg/
  1. Run the launch file, to launch the example:

    ros2 launch isaac_ros_bi3d_freespace isaac_ros_bi3d_freespace_realsense.launch.py featnet_engine_file_path:=/tmp/models/bi3d/bi3dnet_featnet.plan \
    segnet_engine_file_path:=/tmp/models/bi3d/bi3dnet_segnet.plan \
    max_disparity_values:=16
    
  2. Open a second terminal and attach to the container:

    cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
    ./scripts/run_dev.sh
    
  3. Optionally, you can run the visualizer script to visualize the disparity image:

    ros2 run isaac_ros_bi3d isaac_ros_bi3d_visualizer.py --disparity_topic bi3d_mask
    
    https://media.githubusercontent.com/media/NVIDIA-ISAAC-ROS/.github/main/resources/isaac_ros_docs/repositories_and_packages/isaac_ros_freespace_segmentation/visualizer_realsense.png/
    https://media.githubusercontent.com/media/NVIDIA-ISAAC-ROS/.github/main/resources/isaac_ros_docs/repositories_and_packages/isaac_ros_freespace_segmentation/visualizer_realsense_mono_pair.png/

    Note

    For more information on how to interpret the output, refer to the interpreting the output section.

  4. Open a third terminal and attach to the container:

    cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
    ./scripts/run_dev.sh
    
  5. Visualize the occupancy grid in RViz:

    Start RViz:

    rviz2
    

    In the left pane, change the Fixed Frame to base_link.

    In the left pane, click Add, select By topic followed by Map to add the occupancy grid. You should see an output similar to the one shown at the top of this page.