Merge pull request #5 from NVIDIA-ISAAC-ROS/release-dp-2

Isaac ROS 0.20.0 (DP2)

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Isaac ROS Contribution Rules
+
+Any contribution that you make to this repository will
+be under the Apache 2 License, as dictated by that
+[license](http://www.apache.org/licenses/LICENSE-2.0.html):
+
+> **5. Submission of Contributions.** Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+Contributors must sign-off each commit by adding a `Signed-off-by: ...`
+line to commit messages to certify that they have the right to submit
+the code they are contributing to the project according to the
+[Developer Certificate of Origin (DCO)](https://developercertificate.org/).
+
+[//]: # (202201002)

docs/bi3d-example.md

@@ -1,6 +1,6 @@
 # Example Usage of Isaac ROS Proximity Segmentation
 
-This is an example use case of Isaac ROS Proximity Segmentation, which includes monitoring the forward zones of an autonomous mobile robot (AMR) using a HAWK stereo camera. Consider three zones in front of the robot (Zones 1-3), corresponding to different alerts and actions the robot must take if an object breaches the zone. Zone 3 generates a warning, Zone 2 sends a signal for the robot to slow, and Zone 1 results in the robot stopping immediately. 
+This is an example use case of Isaac ROS Proximity Segmentation, which includes monitoring the forward zones of an autonomous mobile robot (AMR) using a HAWK stereo camera. Consider three zones in front of the robot (Zones 1-3), corresponding to different alerts and actions the robot must take if an object breaches the zone. Zone 3 generates a warning, Zone 2 sends a signal for the robot to slow, and Zone 1 results in the robot stopping immediately.
 
 <div align="center"><img src="../resources/safety_zones.png" width="400px"/></div>
 

docs/tutorial-bi3d-freespace-isaac-sim.md

@@ -0,0 +1,46 @@
+# Tutorial for Freespace Segmentation with Isaac Sim
+<div align="center"><img src="../resources/Isaac_sim_tutorial.gif" width="600px"/></div></br>
+
+## Overview
+This tutorial demonstrates how to use a [Isaac Sim](https://developer.nvidia.com/isaac-sim) and [isaac_ros_bi3d_freespace](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_proximity_segmentation) to create a local occupancy grid.
+
+## Tutorial Walkthrough
+1. Complete steps 1-7 listed in the [Quickstart section](../README.md#quickstart) of the main README.
+2. Install and launch Isaac Sim following the steps in the [Isaac ROS Isaac Sim Setup Guide](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/isaac-sim-sil-setup.md)
+3. Open the Isaac ROS Common USD scene (using the **Content** window) located at:
+
+   `omniverse://localhost/NVIDIA/Assets/Isaac/2022.1/Isaac/Samples/ROS2/Scenario/carter_warehouse_apriltags_worker.usd`.
+
+   And wait for it to load completely.
+   > **Note:** To use a different server, replace `localhost` with `<your_nucleus_server>`
+4. Go to the **Stage** tab and select `/World/Carter_ROS/ROS_Cameras/ros2_create_camera_right_info`. In the **Property** tab, change the **Compute Node -> Inputs -> stereoOffset -> X** value from `0` to `-175.92`.
+    <div align="center"><img src="../resources/Isaac_sim_set_stereo_offset.png" width="500px"/></div></br>
+5.  Enable the right camera for a stereo image pair. Go to the **Stage** tab and select `/World/Carter_ROS/ROS_Cameras/enable_camera_right`, then tick the **Condition** checkbox.
+    <div align="center"><img src="../resources/Isaac_sim_enable_stereo.png" width="500px"/></div></br>
+6. Project the `base_link` frame to the ground floor so that we can anchor our occupancy grid. Go to the **Stage** tab and select `/World/Carter_ROS/chassis_link/base_link`. In the **Property** tab, change the **Transform -> Translate -> Z** value from `0` to `-0.24`.
+    <div align="center"><img src="../resources/Isaac_sim_change_base_link.png" width="500px"/></div></br>
+
+7.  Disable the clock reset when simulation is stopped. Go to the **Stage** tab and select `/World/Clock/isaac_read_simulation_time`, then untick the **Reset On Stop** checkbox.
+    <div align="center"><img src="../resources/Isaac_sim_disable_clock_reset.png" width="500px"/></div></br>
+8.  Press **Play** to start publishing data from the Isaac Sim application.
+    <div align="center"><img src="../resources/Isaac_sim_play.png" width="800px"/></div></br>
+9.  Open a second terminal and attach to the container:
+    ```bash
+    cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
+    ./scripts/run_dev.sh
+    ```
+10. In the second terminal, start the `isaac_ros_bi3d` node using the launch files:
+    ```bash
+    ros2 launch isaac_ros_bi3d_freespace isaac_ros_bi3d_freespace_isaac_sim.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:=32
+    ```
+    You should see a RViz window, as shown below:
+    <div align="center"><img src="../resources/Isaac_sim_rviz.png" width="500px"/></div></br>
+
+11. Optionally, you can run the visualizer script to visualize the disparity image.
+    ```bash
+    ros2 run isaac_ros_bi3d isaac_ros_bi3d_visualizer.py --disparity_topic bi3d_mask
+    ```
+    <div align="center"><img src="../resources/Visualizer_isaac_sim.png" width="500px"/></div>

docs/tutorial-bi3d-freespace-realsense.md

@@ -0,0 +1,77 @@
+# Tutorial for Freespace Segmentation using a RealSense Camera
+
+<div align="center"><img src="../resources/realsense_example.gif"  width="600px"/></div>
+
+## Overview
+
+This tutorial demonstrates how to use a [RealSense](https://www.intel.com/content/www/us/en/architecture-and-technology/realsense-overview.html) camera and [isaac_ros_bi3d_freespace](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_proximity_segmentation) to create a local occupancy grid.
+
+> Note: This tutorial has been tested with a RealSense D455/D435 connected to an x86 PC with an NVIDIA graphics card, as well as a Jetson Xavier AGX.
+
+## Tutorial Walkthrough
+
+1. Complete the [RealSense setup tutorial](https://github.com/NVIDIA-ISAAC-ROS/.github/blob/main/profile/realsense-setup.md).
+2. Complete steps 1-7 described in the [Quickstart Guide](../README.md#quickstart).
+3. Open a new terminal and launch the Docker container using the `run_dev.sh` script:
+
+    ```bash
+    cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
+      ./scripts/run_dev.sh
+    ```
+
+4. Build and source the workspace:
+
+    ```bash
+    cd /workspaces/isaac_ros-dev && \
+      colcon build --symlink-install && \
+      source install/setup.bash
+    ```
+
+5. Please 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 launch file [here](../isaac_ros_bi3d_freespace/launch/isaac_ros_bi3d_freespace_realsense.launch.py#L144-157), according to the placement of your camera with respect to a occupancy grid origin frame.
+
+    <div align="center"><img src="../resources/realsense_camera_position.jpg"  width="400px"/></div>
+
+6. Run the launch file, which launches the example:
+
+    ```bash
+    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
+    ```
+
+7. Open a second terminal and attach to the container:
+
+    ```bash
+    cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
+    ./scripts/run_dev.sh
+    ```
+
+8. Optionally, you can run the visualizer script to visualize the disparity image.
+
+    ```bash
+    ros2 run isaac_ros_bi3d isaac_ros_bi3d_visualizer.py --disparity_topic bi3d_mask
+    ```
+
+    <div align="center"><img src="../resources/visualizer_realsense.png" width="500px"/></div>
+
+    <div align="center"><img src="../resources/visualizer_realsense_mono_pair.png" width="500px"/></div>
+    > Note: For more information on how to interpret the output, refer to the [interpreting the output section](../README.md#interpreting-the-output) of the main readme.
+
+9. Open a third terminal and attach to the container:
+
+    ```bash
+    cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
+    ./scripts/run_dev.sh
+    ```
+
+10. Visualize the occupancy grid in RViz.
+
+    Start RViz:
+
+    ```bash
+    rviz2
+    ```
+
+    In the left pane, change the **Fixed Frame** to `base_link`.
+
+    In the left pane, click the **Add** button, then select **By topic** followed by **Map** to add the occupancy grid. You should see an ouput similar to the one shown at the top of this page.

docs/tutorial-bi3d-isaac-sim.md

@@ -0,0 +1,50 @@
+# Tutorial for Bi3D with Isaac Sim
+
+<div align="center"><img src="../resources/Rviz.png" width="800px"/></div></br>
+
+## Overview
+
+This tutorial walks through setting up a pipeline to [segment stereo image pairs](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_proximity_segmentation) generated by Isaac Sim by depth disparity levels. For more details on the output please refer to the [interpreting the output](../README.md#interpreting-the-output) section of the [main readme](../README.md).
+
+## Tutorial Walkthrough
+
+1. Complete steps 1-7 listed in the [Quickstart section](../README.md#quickstart) of the main README.
+2. Install and launch Isaac Sim following the steps in the [Isaac ROS Isaac Sim Setup Guide](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/isaac-sim-sil-setup.md)
+3. Open the Isaac ROS Common USD scene (using the **Content** window) located at:
+
+   `omniverse://localhost/NVIDIA/Assets/Isaac/2022.1/Isaac/Samples/ROS2/Scenario/carter_warehouse_apriltags_worker.usd`.
+
+   And wait for it to load completely.
+   > **Note:** To use a different server, replace `localhost` with `<your_nucleus_server>`
+4. Go to the **Stage** tab and select `/World/Carter_ROS/ROS_Cameras/ros2_create_camera_right_info`. In the **Property** tab, change the **Compute Node -> Inputs -> stereoOffset -> X** value from `0` to `-175.92`.
+    <div align="center"><img src="../resources/Isaac_sim_set_stereo_offset.png" width="500px"/></div></br>
+
+5. Enable the right camera for a stereo image pair. Go to the **Stage** tab and select `/World/Carter_ROS/ROS_Cameras/enable_camera_right`, then tick the **Condition** checkbox.
+    <div align="center"><img src="../resources/Isaac_sim_enable_stereo.png" width="500px"/></div></br>
+6. Press **Play** to start publishing data from the Isaac Sim application.
+    <div align="center"><img src="../resources/Isaac_sim_play.png" width="800px"/></div></br>
+7. Open a second terminal and attach to the container:
+
+    ```bash
+    cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
+    ./scripts/run_dev.sh
+    ```
+
+8. In the second terminal, start the `isaac_ros_bi3d` node using the launch files:
+
+    ```bash
+    ros2 launch isaac_ros_bi3d isaac_ros_bi3d_isaac_sim.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:=32
+    ```
+
+    You should see a RViz window, as shown at the top of this page.
+
+9. Optionally, you can run the visualizer script to visualize the disparity image.
+
+    ```bash
+    ros2 run isaac_ros_bi3d isaac_ros_bi3d_visualizer.py
+    ```
+
+    <div align="center"><img src="../resources/Visualizer_isaac_sim.png" width="500px"/></div>

isaac_ros_bi3d/CMakeLists.txt

@@ -1,10 +1,19 @@
-# Copyright (c) 2022, NVIDIA CORPORATION.  All rights reserved.
+# SPDX-FileCopyrightText: NVIDIA CORPORATION & AFFILIATES
+# Copyright (c) 2022 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
-# NVIDIA CORPORATION and its licensors retain all intellectual property
-# and proprietary rights in and to this software, related documentation
-# and any modifications thereto.  Any use, reproduction, disclosure or
-# distribution of this software and related documentation without an express
-# license agreement from NVIDIA CORPORATION is strictly prohibited.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.8)
 project(isaac_ros_bi3d)
@@ -31,38 +40,11 @@ message(STATUS "Architecture: ${ARCHITECTURE}")
 find_package(ament_cmake_auto REQUIRED)
 ament_auto_find_build_dependencies()
 
-# CVCore Bi3D extension library
-add_library(cvcore_bi3d SHARED IMPORTED)
-
-if(${ARCHITECTURE} STREQUAL "x86_64")
-  set_property(
-    TARGET cvcore_bi3d PROPERTY IMPORTED_LOCATION
-    ${CMAKE_CURRENT_SOURCE_DIR}/cvcore/cvcore_bi3d/lib/x86_64/libgxf_cvcore_bi3d.so)
-elseif(${ARCHITECTURE} STREQUAL "aarch64")
-  set_property(
-    TARGET cvcore_bi3d PROPERTY IMPORTED_LOCATION
-    ${CMAKE_CURRENT_SOURCE_DIR}/cvcore/cvcore_bi3d/lib/jetpack50/libgxf_cvcore_bi3d.so)
-endif()
-
-# Isaac ROS Bi3D postprocess extension library
-add_library(bi3d_postprocess SHARED IMPORTED)
-
-if(${ARCHITECTURE} STREQUAL "x86_64")
-  set_property(
-    TARGET bi3d_postprocess PROPERTY IMPORTED_LOCATION
-    ${CMAKE_CURRENT_SOURCE_DIR}/cvcore/cvcore_bi3d/lib/x86_64/libgxf_bi3d_postprocessor.so)
-elseif(${ARCHITECTURE} STREQUAL "aarch64")
-  set_property(
-    TARGET bi3d_postprocess PROPERTY IMPORTED_LOCATION
-    ${CMAKE_CURRENT_SOURCE_DIR}/cvcore/cvcore_bi3d/lib/jetpack50/libgxf_bi3d_postprocessor.so)
-endif()
-
 # bi3d_node
 ament_auto_add_library(bi3d_node SHARED src/bi3d_node.cpp)
 target_compile_definitions(bi3d_node
   PRIVATE "COMPOSITION_BUILDING_DLL"
 )
-target_link_libraries(bi3d_node cvcore_bi3d bi3d_postprocess)
 rclcpp_components_register_nodes(bi3d_node "nvidia::isaac_ros::bi3d::Bi3DNode")
 set(node_plugins "${node_plugins}nvidia::isaac_ros::bi3d::Bi3DNode;$<TARGET_FILE:bi3d_node>\n")
 
@@ -72,13 +54,6 @@ install(
   DESTINATION share/${PROJECT_NAME}
 )
 
-# Install extensions directory
-if(${ARCHITECTURE} STREQUAL "x86_64")
-  install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/cvcore/cvcore_bi3d/lib/x86_64/ DESTINATION share/${PROJECT_NAME}/cvcore_bi3d)
-elseif(${ARCHITECTURE} STREQUAL "aarch64")
-  install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/cvcore/cvcore_bi3d/lib/jetpack50/ DESTINATION share/${PROJECT_NAME}/cvcore_bi3d)
-endif()
-
 set_target_properties(bi3d_node PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE)
 install(TARGETS bi3d_node
   ARCHIVE DESTINATION lib
@@ -88,10 +63,6 @@ install(TARGETS bi3d_node
 
 if(BUILD_TESTING)
   find_package(ament_lint_auto REQUIRED)
-
-  # Ignore copyright notices since we use custom NVIDIA Isaac ROS Software License
-  set(ament_cmake_copyright_FOUND TRUE)
-
   ament_lint_auto_find_test_dependencies()
 
   find_package(launch_testing_ament_cmake REQUIRED)
@@ -103,4 +74,4 @@ install(PROGRAMS
   DESTINATION lib/${PROJECT_NAME}
 )
 
-ament_auto_package(INSTALL_TO_SHARE launch)
+ament_auto_package(INSTALL_TO_SHARE launch config)