> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable AprilTag pipeline with sample_apriltag

> The sample_apriltag is the ROS package to provide AprilTag pipeline samples for Qualcomm robotics platforms.

<Note>
  For more information, see [sample\_apriltag](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/edit/main/robotics/sample_apriltag) GitHub repository.
</Note>

<Frame>
  <img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/SDKs/QIR-SDK-Ubuntu/images/apriltag.gif?s=2f3396ae00a7cae20d24b5c11875b487" alt="Live camera view of AprilTag markers being detected, each overlaid with its tag outline and identifier." width="720" height="456" data-path="archives/2.1/SDKs/QIR-SDK-Ubuntu/images/apriltag.gif" />
</Frame>

## Pipeline flow for `sample_apriltag`

The following figure shows the pipeline flow for `sample_apriltag`.

<Frame caption="The sample_apriltag pipeline.">
  <img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/SDKs/QIR-SDK-Ubuntu/images/apriltag-architecture.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=543497cfbd6f6b789905f13d6a8541bf" alt="AprilTag pipeline from camera capture through color space conversion and rectification to tag detection and pose output." width="1547" height="322" data-path="archives/2.1/SDKs/QIR-SDK-Ubuntu/images/apriltag-architecture.png" />
</Frame>

* The pipeline accepts an NV12 image from `qrb_ros_camera` and converts the color space to RGB8 format.
* Then, it uses `image_proc` to rectify the image, and outputs `/image_rect`.
* The `Apriltag` node detects tags and calculates their poses, which are published through `/tf`.

## ROS nodes used in the `sample_apriltag` pipeline

The following table lists the ROS nodes used in the `sample_apriltag` pipeline and describes what each node does.

| ROS Node | Description |
| - | - |
| [`qrb_ros::camera::CameraNode`](https://github.com/qualcomm-qrb-ros/qrb_ros_camera) | Qualcomm ROS 2 package that captures images with parameters and publishes them to ROS topics. |
| [`qrb_ros::colorspace_convert::ColorspaceConvertNode`](https://github.com/qualcomm-qrb-ros/qrb_ros_color_space_convert) | Provides a ROS node to convert image from nv12 to rgb8 format. |
| [`image_proc::RectifyNode`](https://github.com/ros-perception/image_pipeline/tree/rolling/image_proc) | Subscribes to unrectified image and Camera calibration metadata to take rectification. |
| [`apriltag_ros::AprilTagNode`](https://github.com/christianrauch/apriltag_ros) | This ROS 2 node uses the `AprilTag` library to detect AprilTags in images and publishes their poses, IDs and additional metadata. |

## ROS topics used in the `sample_apriltag` pipeline

The following table lists the ROS topics used in the `sample_apriltag` pipeline, with the message type and the node that publishes each topic.

| ROS Topic | Type | Published by |
| - | - | - |
| `/apriltag/image_nv12` | `sensor_msgs/msg/Image` | `qrb_ros::camera::CameraNode` |
| `/apriltag/camera_info` | `sensor_msgs/msg/CameraInfo.msg` | `qrb_ros::camera::CameraNode` |
| `/apriltag/image_rgb8` | `sensor_msgs/msg/Image` | `qrb_ros::colorspace_convert::ColorspaceConvertNode` |
| `/apriltag/image_rect` | `sensor_msgs/msg/Image` | `image_proc::RectifyNode` |
| `/apriltag/detections` | `apriltag_msgs/msg/AprilTagDetectionArray` | `apriltag_ros::AprilTagNode` |
| `/tf` | `tf2_msgs/msg/TFMessage` | `apriltag_ros::AprilTagNode` |

## Prerequisites

You have set up the device, installed ROS2 Jazzy and the Qualcomm Intelligent Robotics (QIR) SDK on the device according to [Install the QIR SDK](./install-the-qir-sdk).

## Run out-of-the-box `sample_apriltag`

<Steps>
  <Step title="Install dependencies">
    ```bash Add the package repositories theme={null}
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qcom-ppa
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qirp
    sudo apt update
    ```
  </Step>

  <Step title="Install the sample_apriltag packages">
    ```bash Install the packages theme={null}
    sudo apt install ros-jazzy-sample-apriltag
    ```
  </Step>

  <Step title="Start the AprilTag pipeline sample">
    ```bash Start the pipeline theme={null}
    export XDG_RUNTIME_DIR=/run/user/1000
    export WAYLAND_DISPLAY=wayland-1
    sudo systemctl start weston-autostart.service

    source /opt/ros/jazzy/setup.bash
    ros2 launch sample_apriltag sample_apriltag.launch.py
    ```
  </Step>

  <Step title="Place these AprilTag images in front of the camera">
    | `tagStandard41h12: 1` | `tagStandard41h12: 2` | `tagStandard41h12: 3` |
    | - | - | - |
    | <img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/SDKs/QIR-SDK-Ubuntu/images/april-tag1.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=9c0d38378aad6504fc0a9c5b0a00e04a" alt="AprilTag marker from the tagStandard41h12 family encoding identifier 1." width="575" height="575" data-path="archives/2.1/SDKs/QIR-SDK-Ubuntu/images/april-tag1.png" /> | <img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/SDKs/QIR-SDK-Ubuntu/images/april-tag2.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=a0f5fad8ef0fbfa0c4caded664663aac" alt="AprilTag marker from the tagStandard41h12 family encoding identifier 2." width="575" height="575" data-path="archives/2.1/SDKs/QIR-SDK-Ubuntu/images/april-tag2.png" /> | <img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/SDKs/QIR-SDK-Ubuntu/images/april-tag3.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=2e9a2fdb1f762ceb573658b590184a13" alt="AprilTag marker from the tagStandard41h12 family encoding identifier 3." width="575" height="575" data-path="archives/2.1/SDKs/QIR-SDK-Ubuntu/images/april-tag3.png" /> |
  </Step>

  <Step title="In another terminal of the development kit, run the following commands">
    a. Start a terminal and run the following commands to check the apriltag detection result.

    ```bash theme={null}
    (ssh) export ROS_DOMAIN_ID=123
    (ssh) ros2 topic echo /apriltag/detections
    ```

    The pipeline outputs the detection results with `/apriltag/detections` and detects the tag pose with `/tf`.

    b. To check the topic output, run the following command:

    ```bash theme={null}
    (ssh) ros2 topic echo /apriltag/detections
    ```

    **Result:**

    ```yaml Output theme={null}
    header:
      stamp:
        sec: 1756288539
        nanosec: 411482784
      frame_id: stream1_2625
    detections:
    - family: tagStandard41h12
      id: 1
      hamming: 0
      goodness: 0.0
      decision_margin: 153.66729736328125
      centre:
        x: 595.2331201546427
        y: 382.94486450729545
    ...
    ```

    The result shows the detected tag: `tagStandard41h12` and the tag ID is `1`.
  </Step>
</Steps>

## Build from the source of `sample_apriltag`

Build `sample_apriltag` from source when you need to change the sample code. The device steps install the dependencies, clone the source repository, and build the package.

### Device steps

<Steps>
  <Step title="Install the dependencies">
    ```bash Install the dependencies theme={null}
    sudo apt install ros-dev-tools \
      ros-jazzy-image-proc \
      ros-jazzy-apriltag-ros \
      ros-jazzy-qrb-ros-camera \
      ros-jazzy-qrb-ros-colorspace-convert
    ```
  </Step>

  <Step title="Download source code from qrb-ros-sample repository">
    ```bash Clone the sample repository theme={null}
    mkdir -p ~/qrb_ros_sample_ws/src && cd ~/qrb_ros_sample_ws/src
    source /opt/ros/jazzy/setup.bash
    git clone https://github.com/qualcomm-qrb-ros/qrb_ros_samples.git
    ```
  </Step>

  <Step title="Build sample from source code">
    ```bash Build the sample theme={null}
    cd ~/qrb_ros_sample_ws/src/qrb_ros_samples/robotics/sample_apriltag
    colcon build --packages-up-to sample_apriltag
    source install/setup.bash
    ```
  </Step>

  <Step title="Run and test">
    Run and test according to steps 2-4 of [Run out-of-the-box sample\_apriltag](./enable-apriltag-pipeline-with-sample-apriltag#run-out-of-the-box-sample_apriltag).
  </Step>
</Steps>