==============
|package_name|
==============

:ir_github:`<isaac_ros_nitros> <isaac_ros_nitros>`

Quickstart
----------

.. _Creating Graphs with NITROS-Accelerated Nodes:

Creating Graphs with NITROS-Accelerated Nodes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Besides the fully tested :ref:`graphs <concepts/nitros/index:NITROS-Accelerated Graphs>`,
it is also possible to construct your own graphs with any of the Isaac ROS NITROS-accelerated
nodes to enjoy the performance benefit of NITROS.

The key to successfully constructing a NITROS-accelerated graph is to
ensure that all NITROS-accelerated nodes start in the same process
(which permits zero-copy between nodes). To do so, follow the steps
below to create your own launch file:

1. Create a Python ROS 2 launch file following the official
   `guide <https://docs.ros.org/en/humble/How-To-Guides/Launching-composable-nodes.html>`__.

2. Create NITROS-accelerated nodes using ``ComposableNode``. Taking
   ``ArgusMonoNode`` and ``RectifyNode`` as an example, the nodes can be
   created as follows:

   .. code:: python

      argus_mono_node = ComposableNode(
          name='argus_mono_node',
          package='isaac_ros_argus_camera',
          plugin='nvidia::isaac_ros::argus::ArgusMonoNode',
      )

      rectify_node = ComposableNode(
          name='rectify_node',
          package='isaac_ros_image_proc',
          plugin='nvidia::isaac_ros::image_proc::RectifyNode',
          parameters=[{
              'output_width': 1920,
              'output_height': 1200,
          }],
          remapping=[
              ('image_raw', 'left/image_raw'),
              ('camera_info', 'left/camerainfo')
          ],
      )

3. Place the created nodes in ``ComposableNodeContainer``:

   .. code:: python

      nitros_container = ComposableNodeContainer(
          name='nitros_container',
          package='rclcpp_components',
          executable='component_container_mt',
          composable_node_descriptions=[argus_mono_node, rectify_node],
      )

   ..

      **Note:** It is crucial that the ``executable`` field is set to be
      ``component_container_mt`` so that the created nodes can be
      started and communicated correctly within the same process.

4. Finally, place the created composable node container in
   ``LaunchDescription`` to finalize the launch script.

   .. code:: python

      return launch.LaunchDescription([nitros_container])


Using NITROS-Accelerated Nodes in Existing Non-NITROS Graphs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is also possible to use any NITROS-accelerated nodes in an existing
ROS 2 graph, as all Isaac ROS nodes are compatible with non-NITROS ROS 2
nodes.

Follow these steps to integrate one or more NITROS-accelerated nodes
into your graph:

1. Follow the same steps introduced in the :ref:`previous section <Creating Graphs with NITROS-Accelerated Nodes>` to create
   a ``ComposableNodeContainer`` that contains all the
   NITROS-accelerated nodes with multi-thread enabled
   (i.e. ``executable='component_container_mt'``).

2. Place the created composable node container in ``LaunchDescription``
   together with your own, regular ROS 2 node or composable node
   container declarations.

Now the NITROS-accelerated nodes will be able to choose the best
compatible way to communicate with their adjacent nodes.

-  When connected to non-NITROS nodes, NITROS-accelerated nodes will
   function like regular ROS 2 nodes.
-  When connected to NITROS-accelerated nodes, zero-copy data
   transmission via type adaptation and type negotiation will be
   adopted.

Please visit the link below for an example graph that consists of
NITROS-accelerated and non-NITROS nodes:

-  :doc:`NITROS-accelerated AprilTag node + non-NITROS USB camera node </concepts/fiducials/apriltag/tutorial_usb_cam>`

.. |package_name| replace:: ``isaac_ros_nitros``