Merge pull request #4 from NVIDIA-ISAAC-ROS/release-3.0

Isaac ROS 3.0.1

README.md

@@ -7,22 +7,44 @@ NVIDIA accelerated packages for arm motion planning and control
 ## Overview
 
 [Isaac ROS cuMotion](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_cumotion) provides CUDA-accelerated manipulation
-capabilities for robots in ROS 2, enabling faster processing speeds and real-time performance
-that are crucial to complex robotics tasks such as motion planning.
-It provides two main capabilities, motion generation for robot
-arms via an integration of cuMotion into MoveIt 2 and segmentation of robot from depth streams
-using cuMotion’s kinematics and geometry processing functions to accurately identify and filter robot parts.
-This allows one to reconstruct obstacles in the environment without spurious contributions from the robot itself.
+capabilities for robots in ROS 2.  It provides two main capabilities:
+
+1. Motion generation for robot arms via integration of [cuMotion](https://nvidia-isaac-ros.github.io/concepts/manipulation/index.html#concept-cumotion)
+   into MoveIt 2
+2. Segmentation of robots from depth streams using cuMotion’s kinematics and geometry
+   processing functions to accurately identify and filter out parts of the robot.
+   This allows reconstruction of obstacles in the environment without spurious contributions
+   from the robot itself.
 
 The key advantages of using Isaac ROS cuMotion are:
 
-* Increased Efficiency: CUDA acceleration significantly speeds up processing times,
-  allowing for complex computation, such as collision avoidance, occurring at real-time.
-* Enhanced Precision: Accurate motion planning and segmentation allow for better
-  performance in tasks requiring fine manipulation and detailed environmental interaction.
-* Improved Flexibility: Modular design allows easy integration with existing ROS 2 setups,
-  such as configurations using MoveIt 2, enabling customization and scalability using familiar
-  tooling.
+* **Improved cycle times:** cuMotion produces smooth, optimal-time trajectories in the
+  presence of obstacles, generally reducing motion times compared to previous
+  state-of-the-art planners.  In cluttered environments and other challenging scenarios,
+  cuMotion can often produce a valid trajectory when other planners might fail altogether.
+* **Improved planning times:** cuMotion takes advantage of CUDA acceleration to produce
+  collision-free, optimal-time trajectories in a fraction of a second.
+* **Avoidance of obstacles captured by depth camera(s):** cuMotion optionally leverages
+  [nvblox](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_nvblox/index.html) to perform 3D reconstruction of an environment from one or more depth image
+  streams.  The environment is represented as a signed distance field (SDF) for
+  efficient obstacle-aware planning.  Support is provided for segmenting and filtering
+  the robot itself from the depth stream(s).
+* **Flexibility:** A modular design simplifies integration with existing ROS 2 workflows,
+  especially those already using MoveIt 2.
+
+> [!Warning]
+> Before using or developing with cuMotion or other Isaac Manipulator software, please read and
+> familiarize yourself with the associated safety information that is provided by your robot
+> manufacturer.
+
+> In addition, we provide the following best practices:
+
+> 1. Familiarize yourself with the location of the emergency stop buttons, and be prepared to apply if necessary.
+> 2. Before operation, ensure the working area is free of any persons or other potential hazards.
+> 3. Before operation, alert all persons near the working area that robot operation is about to begin.
+> 4. Before and during operation, be aware of any persons entering the vicinity around the working area,
+>    and be prepared to give necessary warnings, instructions, or take other necessary actions.
+> 5. Take extra caution when testing or deploying new features or code.
 
 The Isaac ROS cuMotion repository currently contains the following packages:
 
@@ -50,6 +72,8 @@ Please visit the [Isaac ROS Documentation](https://nvidia-isaac-ros.github.io/re
 * [`isaac_ros_cumotion`](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion/index.html)
   * [Motion Generation](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion/index.html#motion-generation)
   * [Robot Segmentation](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion/index.html#robot-segmentation)
+  * [Troubleshooting](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion/index.html#troubleshooting)
+  * [API](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion/index.html#api)
 * [`isaac_ros_cumotion_moveit`](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion_moveit/index.html)
   * [Quickstart](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion_moveit/index.html#quickstart)
   * [Try More Examples](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_cumotion/isaac_ros_cumotion_moveit/index.html#try-more-examples)

curobo_core/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>curobo_core</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>This package wraps the cuRobo library as a ROS 2 package. cuRobo serves as the current backend for cuMotion.</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>NVIDIA Isaac ROS Software License</license>

isaac_ros_cumotion/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_cumotion</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>Package adds a cuMotion planner node</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>NVIDIA Isaac ROS Software License</license>

isaac_ros_cumotion_examples/isaac_sim_scripts/start_isaac_sim_franka.py

@@ -1,16 +1,6 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) 2020-2024, NVIDIA CORPORATION.  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.
-#
-# Portions contributed by PickNik, LLC under BSD 3-Clause License
-#
-# Copyright (c) 2023, PickNik, LLC.
-# All rights reserved.
+# Copyright (c) 2020-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# Copyright (c) 2023 PickNik, LLC. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -36,7 +26,7 @@
 # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-#
+
 # This Isaac Sim example is derived from
 # https://github.com/ros-planning/moveit2_tutorials/blob/efef1d3/doc/how_to_guides/isaac_panda/launch/isaac_moveit.py
 # which in turn was derived from an example provided with Isaac Sim 2022.2.1, found at
@@ -50,7 +40,13 @@
 
 import carb
 import numpy as np
-from omni.isaac.kit import SimulationApp
+
+# In older versions of Isaac Sim (prior to 4.0), SimulationApp is imported from
+# omni.isaac.kit rather than isaacsim.
+try:
+    from isaacsim import SimulationApp
+except:
+    from omni.isaac.kit import SimulationApp
 
 FRANKA_STAGE_PATH = "/Franka"
 FRANKA_USD_PATH = "/Isaac/Robots/Franka/franka_alt_fingers.usd"
@@ -62,10 +58,14 @@
 
 CONFIG = {"renderer": "RayTracedLighting", "headless": False}
 
-# Example ROS2 bridge sample demonstrating the manual loading of stages
-# and creation of ROS components
 simulation_app = SimulationApp(CONFIG)
 
+from omni.isaac.version import get_version
+
+# Check the major version number of Isaac Sim to see if it's four digits, corresponding
+# to Isaac Sim 2023.1.1 or older.  The version numbering scheme changed with the
+# Isaac Sim 4.0 release in 2024.
+is_legacy_isaacsim = (len(get_version()[2]) == 4)
 
 # More imports that need to compare after we create the app
 from omni.isaac.core import SimulationContext  # noqa E402
@@ -158,8 +158,32 @@
     print("ROS_DOMAIN_ID environment variable is not set. Setting value to 0")
     ros_domain_id = 0
 
-# Creating a action graph with ROS component nodes
+# Create an action graph with ROS component nodes
 try:
+    og_keys_set_values = [
+        ("Context.inputs:domain_id", ros_domain_id),
+        # Set the /Franka target prim to Articulation Controller node
+        ("ArticulationController.inputs:robotPath", FRANKA_STAGE_PATH),
+        ("PublishJointState.inputs:topicName", "isaac_joint_states"),
+        ("SubscribeJointState.inputs:topicName", "isaac_joint_commands"),
+        ("createViewport.inputs:name", REALSENSE_VIEWPORT_NAME),
+        ("createViewport.inputs:viewportId", 1),
+        ("cameraHelperRgb.inputs:frameId", "sim_camera"),
+        ("cameraHelperRgb.inputs:topicName", "rgb"),
+        ("cameraHelperRgb.inputs:type", "rgb"),
+        ("cameraHelperInfo.inputs:frameId", "sim_camera"),
+        ("cameraHelperInfo.inputs:topicName", "camera_info"),
+        ("cameraHelperInfo.inputs:type", "camera_info"),
+        ("cameraHelperDepth.inputs:frameId", "sim_camera"),
+        ("cameraHelperDepth.inputs:topicName", "depth"),
+        ("cameraHelperDepth.inputs:type", "depth"),
+    ]
+
+    # In older versions of Isaac Sim, the articulation controller node contained a
+    # "usePath" checkbox input that should be enabled.
+    if is_legacy_isaacsim:
+        og_keys_set_values.insert(1, ("ArticulationController.inputs:usePath", True))
+
     og.Controller.edit(
         {"graph_path": GRAPH_PATH, "evaluator_name": "execution"},
         {
@@ -247,25 +271,7 @@
                     "cameraHelperDepth.inputs:renderProductPath",
                 ),
             ],
-            og.Controller.Keys.SET_VALUES: [
-                ("Context.inputs:domain_id", ros_domain_id),
-                # Setting the /Franka target prim to Articulation Controller node
-                ("ArticulationController.inputs:usePath", True),
-                ("ArticulationController.inputs:robotPath", FRANKA_STAGE_PATH),
-                ("PublishJointState.inputs:topicName", "isaac_joint_states"),
-                ("SubscribeJointState.inputs:topicName", "isaac_joint_commands"),
-                ("createViewport.inputs:name", REALSENSE_VIEWPORT_NAME),
-                ("createViewport.inputs:viewportId", 1),
-                ("cameraHelperRgb.inputs:frameId", "sim_camera"),
-                ("cameraHelperRgb.inputs:topicName", "rgb"),
-                ("cameraHelperRgb.inputs:type", "rgb"),
-                ("cameraHelperInfo.inputs:frameId", "sim_camera"),
-                ("cameraHelperInfo.inputs:topicName", "camera_info"),
-                ("cameraHelperInfo.inputs:type", "camera_info"),
-                ("cameraHelperDepth.inputs:frameId", "sim_camera"),
-                ("cameraHelperDepth.inputs:topicName", "depth"),
-                ("cameraHelperDepth.inputs:type", "depth"),
-            ],
+            og.Controller.Keys.SET_VALUES: og_keys_set_values,
         },
     )
 except Exception as e:

isaac_ros_cumotion_examples/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_cumotion_examples</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>Examples demonstrating Isaac ROS cuMotion with MoveIt</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>Apache-2.0</license>

isaac_ros_cumotion_moveit/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_cumotion_moveit</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>Package adds a cuMotion planner plugin to MoveIt</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>Apache-2.0</license>

isaac_ros_cumotion_robot_description/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_cumotion_robot_description</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>Package containing XRDF (extended robot description format) files for various robots</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>Apache-2.0</license>

isaac_ros_esdf_visualizer/package.xml

@@ -2,7 +2,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_esdf_visualizer</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>Package for ESDF Voxel visualizer.</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>Apache-2.0</license>

isaac_ros_goal_setter_interfaces/package.xml

@@ -21,7 +21,7 @@
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_goal_setter_interfaces</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>Interfaces for Isaac ROS Goal Setter</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>Apache-2.0</license>

isaac_ros_moveit_goal_setter/package.xml

@@ -21,7 +21,7 @@ SPDX-License-Identifier: Apache-2.0
 <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>isaac_ros_moveit_goal_setter</name>
-  <version>3.0.0</version>
+  <version>3.0.1</version>
   <description>This package sets the goal for MoveIt</description>
   <maintainer email="[email protected]">Isaac ROS Maintainers</maintainer>
   <license>Apache-2.0</license>