Enable AprilTag Pipeline with sample_apriltag - Qualcomm Dragonwing Documentation

The sample_apriltag is a ROS package that provides AprilTag pipeline samples for Qualcomm robotics platforms.

NoteFor more information, see sample_apriltag on GitHub.

Figure: Sample results of sample_apriltag

Pipeline flow for `sample_apriltag`

Figure: 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 /apriltag/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	It’s a Qualcomm ROS 2 package that captures images with parameters and publishes them to ROS topics.
qrb_ros::colorspace_convert::ColorspaceConvertNode	It’s a ROS node that converts image from nv12 to rgb8 format.
image_proc::RectifyNode	Subscribes to the unrectified image and camera calibration metadata to make rectification.
apriltag_ros::AprilTagNode	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.

Run out-of-the-box `sample_apriltag`

Try me

Run the sample on the development kit

SSH Session

# setup runtime environment
source /usr/share/qirp-setup.sh
# Set the ROS_DOMAIN_ID
export ROS_DOMAIN_ID=123
# Set environment for color space convert node
export XDG_RUNTIME_DIR=/run/user/1000
export WAYLAND_DISPLAY=wayland-1
# Run apriltag pipeline
ros2 launch sample_apriltag sample_apriltag.launch.py

Place AprilTag images in front of the camera


tagStandard41h12: 1	tagStandard41h12: 2	tagStandard41h12: 3

Check the detection result

Start a terminal and run the following commands to check the apriltag detection result.
SSH Session
source /usr/share/qirp-setup.sh export ROS_DOMAIN_ID=123 ros2 topic echo /apriltag/detections
The pipeline outputs the detection results with /apriltag/detections and detects the tag pose with /tf.

To check the topic output, run the following command:

SSH Session

ros2 topic echo /apriltag/detections

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:

Detected tag: tagStandard41h12
Tag ID: 1

Build and run `sample_apriltag`

Try me

Build and package on the host computer

Build the sample application project.

cd <qirp_decompressed_workspace>
source setup.sh
# build sample
cd qirp-samples/robotics/sample_apriltag
colcon build

Package and push the sample application to the device.

# package and push build result of sample
cd <qirp_decompressed_workspace>
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/

Install and run on the development kit

Install the sample application.

SSH Session

# Remount the /usr directory with read-write permissions
# Install sample package
tar --no-overwrite-dir --no-same-owner -zxf /opt/sample_apriltag.tar.gz -C /usr/ros/jazzy/

Run the sample application with the steps in Run out-of-the-box sample_apriltag.

​Pipeline flow for sample_apriltag

​ROS nodes used in the sample_apriltag pipeline

​ROS topics used in the sample_apriltag pipeline

​Prerequisites

​Run out-of-the-box sample_apriltag

​Build and run sample_apriltag

Pipeline flow for `sample_apriltag`

ROS nodes used in the `sample_apriltag` pipeline

ROS topics used in the `sample_apriltag` pipeline

Prerequisites

Run out-of-the-box `sample_apriltag`

Build and run `sample_apriltag`