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

:ir_github:`<isaac_ros_apriltag> <isaac_ros_apriltag>`

Quickstart
----------

1.  Set up your development environment by following the instructions
    :doc:`here </getting_started/dev_env_setup>`.
2.  Clone ``isaac_ros_common`` and this repository under ``${ISAAC_ROS_WS}/src``.

    .. code:: bash

       cd ${ISAAC_ROS_WS}/src

    .. code:: bash

       git clone :ir_clone:`<isaac_ros_common>`

    .. code:: bash

       git clone :ir_clone:`<isaac_ros_apriltag>`

3.  Pull down a ROS Bag of sample data:

    .. code:: bash

       cd ${ISAAC_ROS_WS}/src/isaac_ros_apriltag && \ 
         git lfs pull -X "" -I "resources/rosbags/quickstart.bag"

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

    .. code:: bash

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

5.  Install this package's dependencies.

   :ir_apt:

   .. code:: bash

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

6.  Run the following launch files to spin up a demo of this package:

    .. code:: bash

       ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py

7.  Open a **second** terminal inside the docker container:

    .. code:: bash

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

8.  Run the rosbag file to simulate an image stream:

    .. code:: bash

       ros2 bag play --loop src/isaac_ros_apriltag/resources/rosbags/quickstart.bag

9.  Open a **third** terminal inside the docker container:

    .. code:: bash

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

10. Observe the AprilTag detection output ``/tag_detections`` on a
    separate terminal with the command:

    .. code:: bash

       ros2 topic echo /tag_detections

.. note::

   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.

Try More Examples
-----------------

To continue your exploration, check out the following suggested examples:

.. toctree::
   :maxdepth: 1
   
   Tutorial with a USB camera </concepts/fiducials/apriltag/tutorial_usb_cam>

   Tutorial with Isaac Sim </concepts/fiducials/apriltag/tutorial_isaac_sim>

   Tutorial with Argus Camera </concepts/fiducials/apriltag/tutorial_nitros_graph>

   Tutorial with Zed Camera </concepts/fiducials/apriltag/tutorial_apriltag_zed>

   Tutorial with NITROS ROS 1 Bridge </concepts/fiducials/apriltag/tutorial_apriltag_ros1_bridge>

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

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

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

API
----

Usage
^^^^^

.. code:: bash

   ros2 launch isaac_ros_apriltag isaac_ros_apriltag.launch.py

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
================== ================================
``apriltag_ros``   See ``isaac_ros_apriltag``
``image_pipeline`` See ``isaac_ros_image_pipeline``
================== ================================

ROS Parameters
^^^^^^^^^^^^^^

============= ========== ======== =====================================================================
ROS Parameter Type       Default  Description
============= ========== ======== =====================================================================
``size``      ``double`` ``0.22`` The tag edge size in meters, assuming square markers. More `details here <https://github.com/AprilRobotics/apriltag>`__. E.g. ``0.22``
``max_tags``  ``int``    ``64``   The maximum number of tags to be detected. E.g. ``64``
``tile_size`` ``uint``   ``4``    Tile/window size used for adaptive thresholding in pixels. E.g. ``4``
============= ========== ======== =====================================================================

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`` :ir_repo:`isaac_ros_apriltag_interfaces/AprilTagDetectionArray <isaac_ros_common> <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``) w.r.t to the camera topic ``frame_id``.
================== ====================================================================================================================================================================================== =========================================================================================


.. |package_name| replace:: ``isaac_ros_apriltag``