# Enable AprilTag Pipeline with `sample_apriltag`
The `sample_apriltag` is a ROS package that provides 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) on GitHub.
## Pipeline flow for `sample_apriltag`
- 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 via `/tf`.
## ROS nodes used in the `sample_apriltag` pipeline
| ROS node | Description |
| --- | --- |
| [qrb_ros::camera::CameraNode](https://github.com/qualcomm-qrb-ros/qrb_ros_camera) | It's a 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) | It's a ROS node that converts image from nv12 to rgb8 format. |
| [image_proc::RectifyNode](https://github.com/ros-perception/image_pipeline/tree/rolling/image_proc) | Subscribes to the unrectified image and camera calibration metadata to make 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
| ROS Topic | Type | Published by |
| --- | --- | --- |
| `/apriltag/image_nv12` | `sensor_msgs/msg/Image` | `qrb_ros::camera::CameraNode` |
| `/apriltag/camera_info` | `sensor_msgs/msg/CameraInfo` | `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 completed the settings in [Set up the environment for running sample applications](https://docs.qualcomm.com/doc/80-70023-265/topic/quick_start.html#setup-demo-qs).
## Run out-of-the-box `sample_apriltag`
1. On the development kit, run the following commands:
# setup runtime environment
(ssh) source /usr/share/qirp-setup.sh
# Set the ROS_DOMAIN_ID
(ssh) export ROS_DOMAIN_ID=123
# Set environment for color space convert node
(ssh) export XDG_RUNTIME_DIR=/dev/socket/weston
(ssh) export WAYLAND_DISPLAY=wayland-1
# Run apriltag pipeline
(ssh) ros2 launch sample_apriltag sample_apriltag.launch.py
Copy to clipboard
2. Place these AprilTag images in front of the camera:
| tagStandard41h12: 1 | tagStandard41h12: 2 | tagStandard41h12: 3 |
| --- | --- | --- |
|  |  |  |
3. In another terminal of the development kit, run the following commands:
1. Start a terminal and run the following commands to check the apriltag detection result.
(ssh) source /usr/share/qirp-setup.sh
(ssh) export ROS_DOMAIN_ID=123
(ssh) ros2 topic echo /apriltag/detections
Copy to clipboard
The pipeline outputs the detection results with `/apriltag/detections` and detects the tag pose with `/tf`.
2. To check the topic output, run the following command:
(ssh) ros2 topic echo /apriltag/detections
Copy to clipboard
**Result:**
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 and run `sample_apriltag`
1. In a terminal of the host computer, run the following commands:
1. Build the sample application project.
cd
source setup.sh
# build sample
cd qirp-samples/robotics/sample_apriltag
colcon build
Copy to clipboard
2. Package and push the sample application to the device.
# package and push build result of sample
cd qirp-samples/robotics/sample_apriltag/install/sample_apriltag
tar -czvf sample_apriltag.tar.gz share
scp sample_apriltag.tar.gz root@[ip-addr]:/opt/
Copy to clipboard
2. On the development kit, run the following commands:
1. Install the sample application.
# Remount the /usr directory with read-write permissions
(ssh) mount -o remount rw /usr
# Install sample package
(ssh) tar --no-overwrite-dir --no-same-owner -zxf /opt/sample_apriltag.tar.gz -C /usr/
Copy to clipboard
2. Run the sample application with the steps in [Run out-of-the-box sample\_apriltag](https://docs.qualcomm.com/doc/80-70023-265/topic/sample_apriltag.html#run-sample-apriltag).
Last Published: Dec 29, 2025
[Previous Topic
Enable people tracking with](https://docs.qualcomm.com/bundle/publicresource/80-70023-265/topics/followme.md) [Next Topic
Enable people tracking in the simulator with](https://docs.qualcomm.com/bundle/publicresource/80-70023-265/topics/simulation_followme.md)