> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.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/tree/main/robotics/sample_apriltag) GitHub repository.

![Live camera view of AprilTag markers being detected, each overlaid with its tag outline and identifier.](https://mintcdn.com/qualcomm-prod/EDJV-hu6qJhZi4pm/SDKs/QIR-SDK-Ubuntu/images/apriltag.gif?s=8deaa1bbdb9d58e6427c020494c73895)

## Pipeline flow for `sample_apriltag`

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

![AprilTag pipeline from camera capture through color space conversion and rectification to tag detection and pose output.](https://mintcdn.com/qualcomm-prod/EDJV-hu6qJhZi4pm/SDKs/QIR-SDK-Ubuntu/images/apriltag-architecture.png?fit=max\&auto=format\&n=EDJV-hu6qJhZi4pm\&q=85\&s=3c4d92210c001484f04ce3ea76c053b8)

The sample\_apriltag pipeline.

* 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](https://dragonwingdocs.qualcomm.com/SDKs/QIR-SDK-Ubuntu/install-the-qir-sdk.md).

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

**1. 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
```

**2. Install the sample\_apriltag packages**

```bash Install the packages theme={null}
sudo apt install ros-jazzy-sample-apriltag
```

**3. 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
```

**4. Place these AprilTag images in front of the camera**

| `tagStandard41h12: 1` | `tagStandard41h12: 2` | `tagStandard41h12: 3` |
| - | - | - |
| ![AprilTag marker from the tagStandard41h12 family encoding identifier 1.](https://mintcdn.com/qualcomm-prod/EDJV-hu6qJhZi4pm/SDKs/QIR-SDK-Ubuntu/images/april-tag1.png?fit=max\&auto=format\&n=EDJV-hu6qJhZi4pm\&q=85\&s=4035be8518793c3a90e421d7d42f31a3) | ![AprilTag marker from the tagStandard41h12 family encoding identifier 2.](https://mintcdn.com/qualcomm-prod/EDJV-hu6qJhZi4pm/SDKs/QIR-SDK-Ubuntu/images/april-tag2.png?fit=max\&auto=format\&n=EDJV-hu6qJhZi4pm\&q=85\&s=df1df6a43d94f20467e1925c5133b512) | ![AprilTag marker from the tagStandard41h12 family encoding identifier 3.](https://mintcdn.com/qualcomm-prod/EDJV-hu6qJhZi4pm/SDKs/QIR-SDK-Ubuntu/images/april-tag3.png?fit=max\&auto=format\&n=EDJV-hu6qJhZi4pm\&q=85\&s=c9d266d46e98391c3d4c44c9dfcd9e77) |

**5. 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`.

## 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

**1. 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
```

**2. 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
```

**3. 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
```

**4. Run and test**

Run and test according to steps 2-4 of [Run out-of-the-box sample\_apriltag](https://dragonwingdocs.qualcomm.com/SDKs/QIR-SDK-Ubuntu/enable-apriltag-pipeline-with-sample-apriltag.md#run-out-of-the-box-sample_apriltag).
