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

Isaac ROS 0.20.0 (DP2)
NVIDIA-ISAAC-ROS · Oct 19, 2022 · d2027fd · d2027fd
2 parents 2435b11 + 24661fb
commit d2027fd
Show file tree

Hide file tree

Showing 21 changed files with 582 additions and 205 deletions.
diff --git a/CONTRIBUTING.md b/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)
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,27 +1,31 @@
 # Isaac ROS Apriltag
 
 <div align="center"><img alt="Isaac ROS AprilTag Sample Output" src="resources/isaac_ros_apriltag_sample_crop.gif" width="550px"/></div>
-    
+
 ## Overview
+
 This ROS2 node uses the NVIDIA GPU-accelerated AprilTags library to detect AprilTags in images and publish their poses, IDs, and additional metadata. This has been tested on ROS2 (Humble) and should build and run on x86_64 and aarch64 (Jetson). It is modeled after and comparable to the ROS2 node for [CPU AprilTags detection](https://github.com/christianrauch/apriltag_ros.git).
 
 For more information on the Isaac GEM that this node is based off of, see the latest Isaac SDK documentation [here](https://docs.nvidia.com/isaac/packages/fiducials/doc/apriltags.html).
 
 For more information on AprilTags themselves, including the paper and the reference CPU implementation, click [here](https://april.eecs.umich.edu/software/apriltag.html).
 
-
 ### Isaac ROS NITROS Acceleration
-This package is powered by [NVIDIA Isaac Transport for ROS (NITROS)](https://developer.nvidia.com/blog/improve-perception-performance-for-ros-2-applications-with-nvidia-isaac-transport-for-ros/), which leverages type adaptation and negotiation to optimize message formats and dramatically accelerate communication between participating nodes. 
 
+This package is powered by [NVIDIA Isaac Transport for ROS (NITROS)](https://developer.nvidia.com/blog/improve-perception-performance-for-ros-2-applications-with-nvidia-isaac-transport-for-ros/), which leverages type adaptation and negotiation to optimize message formats and dramatically accelerate communication between participating nodes.
 
 ## Performance
-The performance results of benchmarking the prepared pipelines in this package on supported platforms are below: 
 
-| Pipeline                 | AGX Orin | AGX Xavier | x86_64 w/ RTX 3060 Ti |
-| ------------------------ | -------- | ---------- | --------------------- |
-| Isaac ROS Apriltag(720p) | 260 fps  | 150 fps    | 600 fps               |
+The performance results of benchmarking the prepared pipelines in this package on supported platforms are below:
+
+| Pipeline                 | AGX Orin           | Orin Nano        | x86_64 w/ RTX 3060 Ti |
+| ------------------------ | ------------------ | ---------------- | --------------------- |
+| Isaac ROS Apriltag(720p) | 248 fps <br> 5.5ms | 82 fps <br> 14ms | 600 fps <br> 2ms      |
+
+These data have been collected per the methodology described [here](https://github.com/NVIDIA-ISAAC-ROS/.github/blob/main/profile/performance-summary.md#methodology).
 
 ## Table of Contents
+
 - [Isaac ROS Apriltag](#isaac-ros-apriltag)
   - [Overview](#overview)
     - [Isaac ROS NITROS Acceleration](#isaac-ros-nitros-acceleration)
@@ -49,47 +53,51 @@ The performance results of benchmarking the prepared pipelines in this package o
 - [Updates](#updates)
 
 ## Latest Update
-Update 2022-08-31: Update to be compatible with JetPack 5.0.2
+
+Update 2022-10-19: Updated OSS licensing
 
 ## Supported Platforms
+
 This package is designed and tested to be compatible with ROS2 Humble running on [Jetson](https://developer.nvidia.com/embedded-computing) or an x86_64 system with an NVIDIA GPU.
 
 > **Note**: Versions of ROS2 earlier than Humble are **not** supported. This package depends on specific ROS2 implementation features that were only introduced beginning with the Humble release.
 
-| Platform | Hardware                                                                                                                                                                                                | Software                                                                                                             | Notes                                                                                                                                                                                   |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Jetson   | [Jetson Orin](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/)<br/>[Jetson Xavier](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-agx-xavier/) | [JetPack 5.0.2](https://developer.nvidia.com/embedded/jetpack)                                                       | For best performance, ensure that [power settings](https://docs.nvidia.com/jetson/archives/r34.1/DeveloperGuide/text/SD/PlatformPowerAndPerformance.html) are configured appropriately. |
-| x86_64   | NVIDIA GPU                                                                                                                                                                                              | [Ubuntu 20.04+](https://releases.ubuntu.com/20.04/) <br> [CUDA 11.6.1+](https://developer.nvidia.com/cuda-downloads) |
-
+| Platform | Hardware                                                                                                                                                                                                 | Software                                                                                                             | Notes                                                                                                                                                                                   |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Jetson   | [Jetson Orin](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/) <br> [Jetson Xavier](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-agx-xavier/) | [JetPack 5.0.2](https://developer.nvidia.com/embedded/jetpack)                                                       | For best performance, ensure that [power settings](https://docs.nvidia.com/jetson/archives/r34.1/DeveloperGuide/text/SD/PlatformPowerAndPerformance.html) are configured appropriately. |
+| x86_64   | NVIDIA GPU                                                                                                                                                                                               | [Ubuntu 20.04+](https://releases.ubuntu.com/20.04/) <br> [CUDA 11.6.1+](https://developer.nvidia.com/cuda-downloads) |
 
 ### Docker
+
 To simplify development, we strongly recommend leveraging the Isaac ROS Dev Docker images by following [these steps](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/dev-env-setup.md). This will streamline your development environment setup with the correct versions of dependencies on both Jetson and x86_64 platforms.
 
 > **Note:** All Isaac ROS Quickstarts, tutorials, and examples have been designed with the Isaac ROS Docker images as a prerequisite.
 
-
 ## Quickstart
+
 1. Set up your development environment by following the instructions [here](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/dev-env-setup.md).
 2. Clone this repository and its dependencies under `~/workspaces/isaac_ros-dev/src`.
+
     ```bash
     cd ~/workspaces/isaac_ros-dev/src
     ```
 
     ```bash
     git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common
-    ``` 
-    
+    ```
+
     ```bash
     git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_nitros
     ```
 
     ```bash
     git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_apriltag
     ```
-    
+
     ```bash
     git clone https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_image_pipeline
     ```
+
 3. Pull down a ROS Bag of sample data:
 
     ```bash
@@ -98,64 +106,87 @@ To simplify development, we strongly recommend leveraging the Isaac ROS Dev Dock
     ```
 
 4. Launch the Docker container using the `run_dev.sh` script:
+
     ```bash
     cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
       ./scripts/run_dev.sh
     ```
+
 5. Inside the container, build and source the workspace:  
+
     ```bash
     cd /workspaces/isaac_ros-dev && \
       colcon build --symlink-install && \
       source install/setup.bash
     ```
+
 6. (Optional) Run tests to verify complete and correct installation:  
+
     ```bash
     colcon test --executor sequential
     ```
-7. Run the following launch files to spin up a demo of this package: 
+
+7. Run the following launch files to spin up a demo of this package:
+
     ```bash
     ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py
     ```
+
 8. Open a **second** terminal inside the docker container:
+
     ```bash
     cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
       ./scripts/run_dev.sh
     ```
+
 9. Run the rosbag file to simulate an image stream:
+
     ```bash
     ros2 bag play --loop src/isaac_ros_apriltag/resources/rosbags/quickstart.bag
     ```
+
 10. Open a **third** terminal inside the docker container:
+
     ```bash
     cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
       ./scripts/run_dev.sh
     ```
-11. Observe the AprilTag detection output `/tag_detections` on a separate terminal with the command:   
+
+11. Observe the AprilTag detection output `/tag_detections` on a separate terminal with the command:
+
     ```bash
     source install/setup.bash && \
     ros2 topic echo /tag_detections
     ```
 
 ### Configuration
+
 You will need to calibrate the intrinsics of your camera if you want the node to determine 3D poses for tags instead of just detection and corners as 2D pixel coordinates. See [here](https://navigation.ros.org/tutorials/docs/camera_calibration.html) for more details.
 
 ## Next Steps
+
 ### Try More Examples
+
 To continue your exploration, check out the following suggested examples:
+
 - [Tutorial with a USB camera](./docs/tutorial-usb-cam.md)
 - [Tutorial with Isaac Sim](./docs/tutorial-isaac-sim.md)
 
 ### Try NITROS-Accelerated Graph with Argus
+
 If you have an Argus-compatible camera, you can launch the NITROS-accelerated graph by following the [tutorial](./docs/tutorial-nitros-graph.md).
 
 ### Customize your Dev Environment
+
 To customize your development environment, reference [this guide](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/modify-dockerfile.md).
 
 ## Replacing `apriltag_ros` with `isaac_ros_apriltag`
+
 1. Add a dependency on `isaac_ros_apriltag` to `your_package/package.xml` and `your_package/CMakeLists.txt`. The original `apriltag_ros` dependency may be removed entirely.
 2. Change the package and plugin names in any `*.launch.py` launch files to use `isaac_ros_apriltag` and `nvidia::isaac_ros::apriltag::AprilTagNode`, respectively.
 
 ### Supported Packages
+
 At this time, the packages under the standard `apriltag_ros` have the following support:
 
 | Existing Package | Isaac ROS Alternative          |
@@ -164,6 +195,7 @@ At this time, the packages under the standard `apriltag_ros` have the following
 | `image_pipeline` | See `isaac_ros_image_pipeline` |
 
 ## Package Reference
+
 ### `isaac_ros_apriltag`
 
 #### Usage
@@ -174,33 +206,36 @@ ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py --ros-args -p size:=
 
 #### ROS Parameters
 
-| ROS Parameter | Type     | Default | Description                                                             |
-| ------------- | -------- | ------- | ----------------------------------------------------------------------- |
-| `size`        | `double` | `0.22`  | The tag edge size in meters, assuming square markers. <br/> E.g. `0.22` |
-| `max_tags`    | `int`    | `64`    | The maximum number of tags to be detected. <br/> E.g. `64`              |
+| ROS Parameter | Type     | Default | Description                                                            |
+| ------------- | -------- | ------- | ---------------------------------------------------------------------- |
+| `size`        | `double` | `0.22`  | The tag edge size in meters, assuming square markers. <br> E.g. `0.22` |
+| `max_tags`    | `int`    | `64`    | The maximum number of tags to be detected. <br> E.g. `64`              |
 
 #### ROS Topics Subscribed
+
 | ROS Topic     | Interface                                                                                                      | Description                         |
 | ------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
 | `image`       | [sensor_msgs/Image](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg)           | The input camera stream.            |
 | `camera_info` | [sensor_msgs/CameraInfo](https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg) | The input camera intrinsics stream. |
 
 #### ROS Topics Published
+
 | ROS Topic        | Type                                                                                                                                                                                | Description                                                                      |
 | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
 | `tag_detections` | [isaac_ros_apriltag_interfaces/AprilTagDetectionArray](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/isaac_ros_apriltag_interfaces/msg/AprilTagDetectionArray.msg) | The detection message array.                                                     |
 | `tf`             | [tf2_msgs/TFMessage](https://github.com/ros2/geometry2/blob/ros2/tf2_msgs/msg/TFMessage.msg)                                                                                        | Pose of all detected apriltags(`TagFamily:ID`) wrt to the camera topic frame_id. |
 
 ## Troubleshooting
-### Isaac ROS Troubleshooting
-For solutions to problems with Isaac ROS, please check [here](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/troubleshooting.md).
 
+### Isaac ROS Troubleshooting
 
+For solutions to problems with Isaac ROS, please check [here](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common/blob/main/docs/troubleshooting.md).
 
 # Updates
 
 | Date       | Changes                                                                                 |
 | ---------- | --------------------------------------------------------------------------------------- |
+| 2022-10-19 | Updated OSS licensing                                                                   |
 | 2022-08-31 | Update to be compatible with JetPack 5.0.2                                              |
 | 2022-06-30 | Update to use NITROS for improved performance                                           |
 | 2021-11-15 | Isaac Sim HIL documentation update                                                      |

diff --git a/docs/tutorial-isaac-sim.md b/docs/tutorial-isaac-sim.md
@@ -1,35 +1,61 @@
-# Tutorial with Isaac Sim
+# Tutorial for AprilTag Detection with Isaac Sim
+
+<div align="center"><img src="../resources/Rviz_apriltag_output.png" width="800px"/></div>
+
+## Overview
+
+This tutorial walks you through a pipeline to estimate the 6DOF pose of [AprilTags](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_apriltag) using images from Isaac Sim.
+
+## Tutorial Walkthrough
 
 1. Complete the [Quickstart section](../README.md#quickstart) in the main README.
 2. Launch the Docker container using the `run_dev.sh` script:
+
     ```bash
     cd ~/workspaces/isaac_ros-dev/src/isaac_ros_common && \
       ./scripts/run_dev.sh
     ```
+
 3. Inside the container, build and source the workspace:  
+
     ```bash
     cd /workspaces/isaac_ros-dev && \
       colcon build --symlink-install && \
       source install/setup.bash
     ```
-4. Launch the pre-composed pipeline launchfile: 
-    ```bash 
+
+4. Launch the pre-composed pipeline launchfile:
+
+    ```bash
     ros2 launch isaac_ros_apriltag isaac_ros_apriltag_isaac_sim_pipeline.launch.py
     ```
+
 5. 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)
 6. Open up 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`
-   
+
    Wait for it to load completely.
    > **Note:** To use a different server, replace `localhost` with `<your_nucleus_server>`
 7. Press **Play** to start publishing data from Isaac Sim.
-<div align="center"><img src="../resources/Isaac_sim_april_tag.png" width="800px"/></div>
-
-7. In a separate terminal, run RViz to visualize the AprilTag detections:<br>
-    `rviz2`
-8.  Add the tf tree in the **Displays** RViz panel. <br> <div align="center"><img src="../resources/Rviz_add_tf.png" width="600px"/></div>
-9.  Set the **Fixed frame** in the **Global Options** to `chassis_link`. <br> <div align="center"><img src="../resources/Rviz_fixed_frame.png" width="300px"/></div>
-10.  You should see the pose of the tags in RVIZ: <br> <div align="center"><img src="../resources/Rviz_apriltag_output.png" width="800px"/></div>
-11.  If you prefer to observe the AprilTag output in text form, echo the contents of the `/tag_detections` topic with the following command in a separate terminal:   
-`ros2 topic echo /tag_detections` <br> <div align="center"><img src="../resources/Terminal_output.png" width="600px"/></div>
+   <div align="center"><img src="../resources/Isaac_sim_april_tag.png" width="800px"/></div>
+
+8. In a separate terminal, run RViz to visualize the AprilTag detections:  
+
+    ```bash
+    rviz2
+    ```
+
+9. Add the tf tree in the **Displays** RViz panel.
+   <div align="center"><img src="../resources/Rviz_add_tf.png" width="600px"/></div>
+10. Set the **Fixed frame** in the **Global Options** to `chassis_link`.
+    <div align="center"><img src="../resources/Rviz_fixed_frame.png" width="300px"/></div>
+11. You should see the pose of the tags in RVIZ:
+    <div align="center"><img src="../resources/Rviz_apriltag_output.png" width="800px"/></div>
+12. If you prefer to observe the AprilTag output in text form, echo the contents of the `/tag_detections` topic with the following command in a separate terminal:
+
+    ```bash
+    ros2 topic echo /tag_detections
+    ```
+
+    <div align="center"><img src="../resources/Terminal_output.png" width="600px"/></div>