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

:ir_github:`<isaac_ros_argus_camera> <isaac_ros_argus_camera>`

Quickstart
----------

Set Up Development Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /_snippets/set_up_dev_env.rst

Build |package_name|
^^^^^^^^^^^^^^^^^^^^

.. tabs::

   .. tab:: Binary Package

      1. Launch the Docker container using the ``run_dev.sh`` script:

         .. code:: bash

            cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
            ./scripts/run_dev.sh

      2. Install the prebuilt Debian package:

         :ir_apt:

         .. code:: bash

            sudo apt-get install -y ros-humble-isaac-ros-argus-camera

   .. tab:: Build from Source

      1. Clone this repository under ``${ISAAC_ROS_WS}/src``:

         .. code:: bash

            cd ${ISAAC_ROS_WS}/src && \
               git clone :ir_clone:`<isaac_ros_argus_camera>`

      2. Launch the Docker container using the ``run_dev.sh`` script:

         .. code:: bash

            cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
            ./scripts/run_dev.sh

      3. Use ``rosdep`` to install the package's dependencies:

         :ir_apt:

         .. code:: bash

            rosdep update && rosdep install --from-paths ${ISAAC_ROS_WS}/src/isaac_ros_argus_camera/isaac_ros_argus_camera --ignore-src -y

      4. Build the package from source:

         .. code:: bash

            cd ${ISAAC_ROS_WS} && \
               colcon build --symlink-install --packages-up-to isaac_ros_argus_camera --base-paths ${ISAAC_ROS_WS}/src/isaac_ros_argus_camera/isaac_ros_argus_camera

      5. Source the ROS workspace:

         .. note::

            Make sure to repeat this step in **every** terminal created inside the Docker container.

            Because this package was built from source, the enclosing workspace must be sourced for ROS to be able to find the package's contents.

         .. code:: bash

            source install/setup.bash

Run Launch File
^^^^^^^^^^^^^^^

.. tabs::

    .. tab:: Hawk Camera

      #. Ensure that you have already set up your Hawk camera using the :doc:`Hawk setup tutorial </getting_started/hardware_setup/sensors/hawk_setup>`. If you have not, please set up the sensor and then restart this quickstart from the beginning.

      #. Continuing inside the Docker container, install the following dependencies:

         :ir_apt:

         .. code:: bash

            sudo apt-get install -y ros-humble-isaac-ros-examples

      #. Run the following launch file to spin up a demo of this package using a Hawk camera:

         .. code:: bash

            ros2 launch isaac_ros_examples isaac_ros_examples.launch.py launch_fragments:=argus_stereo

    .. tab:: Owl Camera

      #. Ensure that you have already set up your Owl camera. The :doc:`Hawk setup tutorial </getting_started/hardware_setup/sensors/hawk_setup>` can be followed for Owl also. If you have not, please set up the sensor and then restart this quickstart from the beginning.

      #. Continuing inside the Docker container, install the following dependencies:

         :ir_apt:

         .. code:: bash

            sudo apt-get install -y ros-humble-isaac-ros-examples

      #. Run the following launch file to spin up a demo of this package using a Owl camera:

         .. code:: bash

            ros2 launch isaac_ros_examples isaac_ros_examples.launch.py launch_fragments:=argus_mono

Visualize Results
^^^^^^^^^^^^^^^^^

.. tabs::

   .. tab:: Hawk Camera

      1. Open a **new** terminal inside the Docker container:

        .. code:: bash

            cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
              ./scripts/run_dev.sh

      2. Use ``image_saver`` to save the output images:

        .. code:: bash

            ros2 run image_view image_saver --ros-args -r image:=/left/image_raw -p filename_format:="left_image.jpg"

        Stop the node by pressing ``Ctrl+C`` after saving the left image.

        .. code:: bash

            ros2 run image_view image_saver --ros-args -r image:=/right/image_raw -p filename_format:="right_image.jpg"

        Stop the node by pressing ``Ctrl+C`` after saving the right image.

        Open the images in your preferred image viewer to visualize the results.

   .. tab:: Owl Camera

      1. Open a **new** terminal inside the Docker container:

        .. code:: bash

          cd ${ISAAC_ROS_WS}/src/isaac_ros_common && \
            ./scripts/run_dev.sh

      2. Use ``image_saver`` to save the output images:

        .. code:: bash

            ros2 run image_view image_saver --ros-args -r image:=/image_raw -r camera_info:=/left/camera_info -p filename_format:="left_image.jpg"

        Stop the node by pressing ``Ctrl+C`` after saving the image.

        Open the images in your preferred image viewer to visualize the results.


Troubleshooting
---------------

Isaac ROS Troubleshooting
^^^^^^^^^^^^^^^^^^^^^^^^^

For solutions to problems with Isaac ROS, see :doc:`troubleshooting </troubleshooting/index>`.

.. include:: /repositories_and_packages/isaac_ros_nova/isaac_ros_hawk/troubleshooting_argus.rst


API
----

Usage
^^^^^

.. code:: bash

   ros2 launch isaac_ros_argus_camera isaac_ros_argus_camera_mono.launch.py

.. code:: bash

   ros2 launch isaac_ros_argus_camera isaac_ros_argus_camera_stereo.launch.py

Argus Camera Mono Node
^^^^^^^^^^^^^^^^^^^^^^

ROS Parameters
~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - ROS Parameter
     - Type
     - Default
     - Description

   * - ``camera_id``
     - ``uint``
     - ``0``
     - The video device index E.g. ``/dev/video0``

   * - ``module_id``
     - ``int``
     - ``-1``
     - The camera module index in the device tree when there is more than one of the same camera module connected, leaving as -1 means use the first camera module found

   * - ``mode``
     - ``uint``
     - ``0``
     - The resolution mode supported by the camera sensor and driver. Currently only 1920x1200 (mode 0) is supported.

   * - ``fsync_type``
     - ``uint``
     - ``1``
     -  Specifies what kind of Frame Synchronization to use, supported values are 0 for internal and 1 for external. For e3653 boards choose 0, for p3762 boards choose 1

   * - ``camera_link_frame_name``
     - ``string``
     - ``camera``
     - The frame name associated with the origin of the camera body.

   * - ``optical_frame_name``
     - ``string``
     - ``left_cam``
     - The frame name associated with the imager inside camera body.

   * - ``camera_info_url``
     - ``string``
     - N/A
     - Optional URL of a camera info ``.yaml`` file for monocular camera to read intrinsic information.

   * - ``use_hw_timestamp``
     - ``bool``
     - ``false``
     - Flag to use hardware timestamps, else use less accurate software timestamps. Hardware timestamps are in their own time domain and require translation to ROS time domain for many use cases. If you are using a supported camera, then this translation can be done for you by using the :ref:`Isaac Ros Hawk/Owl packages. <repositories_and_packages/isaac_ros_nova/isaac_ros_hawk/index:quickstart>`

ROS Topics Published
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - ROS Topic
     - Interface
     - Description

   * - ``left/image_raw``
     - `sensor_msgs/Image <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg>`__
     - The image from mono camera.

   * - ``left/camera_info``
     - `sensor_msgs/CameraInfo <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg>`__
     - The camera model.

   * - ``/tf_static``
     - `tf2_msgs/TFMessage <https://github.com/ros2/geometry2/blob/rolling/tf2_msgs/msg/TFMessage.msg>`__
     - The static transform between available camera frames.

Argus Camera Stereo Node
^^^^^^^^^^^^^^^^^^^^^^^^

ROS Parameters
~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - ROS Parameter
     - Type
     - Default
     - Description

   * - ``camera_id``
     - ``uint``
     - ``0``
     - The video device index E.g. ``/dev/video0``

   * - ``module_id``
     - ``int``
     - ``-1``
     - The camera module index in the device tree when there is more than one of the same camera module connected, leaving as -1 means use the first stereo camera module found

   * - ``mode``
     - ``uint``
     - ``0``
     - The resolution mode supported by the camera sensor and driver. Currently only 1920x1200 (mode 0) is supported.

   * - ``fsync_type``
     - ``uint``
     - ``1``
     -  Specifies what kind of Frame Synchronization to use, supported values are 0 for internal and 1 for external. For e3653 boards choose 0, for p3762 boards choose 1

   * - ``camera_link_frame_name``
     - ``string``
     - ``stereo_camera``
     - The frame name associated with the origin of the camera body.

   * - ``left_camera_frame_name``
     - ``string``
     - ``stereo_cameras_left``
     - The frame name associated with the left imager inside camera body (for stereo camera). An optical frame will also be created with the _optical suffix.

   * - ``right_camera_frame_name``
     - ``string``
     - ``stereo_cameras_right``
     - The frame name associated with the right imager inside camera body (for stereo camera). An optical frame will also be created with the _optical suffix.

   * - ``right_camera_info_url``
     - ``string``
     - N/A
     - Optional URL of a camera info ``.yaml`` file for the right imager of a stereo camera to read intrinsic information.

   * - ``left_camera_info_url``
     - ``string``
     - N/A
     - Optional URL of a camera info ``.yaml`` file for the left imager of a stereo camera to read intrinsic information.

   * - ``wide_fov``
     - ``boolean``
     - ``false``
     - Flag to output image with wide field of view.

   * - ``use_hw_timestamp``
     - ``bool``
     - ``false``
     - Flag to use hardware timestamps, else use less accurate software timestamps. Hardware timestamps are in their own time domain and require translation to ROS time domain for many use cases. If you are using a supported camera, then this translation can be done for you by using the :ref:`Isaac Ros Hawk/Owl packages. <repositories_and_packages/isaac_ros_nova/isaac_ros_hawk/index:quickstart>`


ROS Topics Published
~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - ROS Topic
     - Interface
     - Description

   * - ``left/image_raw``
     - `sensor_msgs/Image <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg>`__
     - The image from the left lens in the stereo camera.

   * - ``left/camera_info``
     - `sensor_msgs/CameraInfo <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg>`__
     - The left camera model.

   * - ``right/image_raw``
     - `sensor_msgs/Image <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/Image.msg>`__
     - The image from the right lens in the stereo camera.

   * - ``right/camera_info``
     - `sensor_msgs/CameraInfo <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg>`__
     - The right camera model.

   * - ``/tf_static``
     - `tf2_msgs/TFMessage <https://github.com/ros2/geometry2/blob/rolling/tf2_msgs/msg/TFMessage.msg>`__
     - The static transform between available camera frames.

Output Color Space Format
^^^^^^^^^^^^^^^^^^^^^^^^^

The Isaac ROS Argus node supports the ``YUV444`` and ``YUV420``
colorspaces from ``libargus`` and converts it to the ``RGB888``
colorspace as output.

.. _CameraInfo Message:

``CameraInfo`` Message
^^^^^^^^^^^^^^^^^^^^^^

The Isaac ROS Argus node uses the Argus Ext API to retrieve calibration
parameters from the camera through the Linux device driver and convert
it into
`CameraInfo <https://github.com/ros2/common_interfaces/blob/humble/sensor_msgs/msg/CameraInfo.msg>`__
messages. Refer to `this
page <https://docs.nvidia.com/jetson/l4t-multimedia/classArgus_1_1Ext_1_1ISyncSensorCalibrationData.html>`__
for the data structure of the calibration parameters.

.. note::

   Each camera module should have stored the calibration
   parameters in internal memory like EEPROM, and the device driver must
   support the Argus Ext API to extract those parameters. Contact your
   camera vendor to get the required drivers.
.. note::

   If your camera
   does not support the Argus Ext API, you can also specify a URL to a
   camera info ``.ini`` file parsable by the ROS
   `CameraInfoManager <http://wiki.ros.org/camera_info_manager>`__ using
   the ``camera_info_url`` parameter on the Isaac ROS Argus node. This
   will allow you to provide parameters you may have calibrated using
   the ROS Camera Calibration package, for example.
.. note::

   When the
   ``camera_info_url`` is provided, the loaded parameters override the
   ``CameraInfo`` from Argus Ext API.

.. |package_name| replace:: ``isaac_ros_argus_camera``