Enable AprilTag pipeline with sample_apriltag - Qualcomm Dragonwing Documentation

For more information, see sample_apriltag GitHub repository.

Live camera view of AprilTag markers being detected, each overlaid with its tag outline and identifier.

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. — 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`	Qualcomm ROS 2 package that captures images with parameters and publishes them to ROS topics.
`qrb_ros::colorspace_convert::ColorspaceConvertNode`	Provides a ROS node to convert image from nv12 to rgb8 format.
`image_proc::RectifyNode`	Subscribes to unrectified image and Camera calibration metadata to take 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

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.

Run out-of-the-box `sample_apriltag`

Install dependencies

Add the package repositories

sudo add-apt-repository ppa:ubuntu-qcom-iot/qcom-ppa
sudo add-apt-repository ppa:ubuntu-qcom-iot/qirp
sudo apt update

Install the sample_apriltag packages

Install the packages

sudo apt install ros-jazzy-sample-apriltag

Start the AprilTag pipeline sample

Start the pipeline

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

Place these AprilTag images in front of the camera

`tagStandard41h12: 1`	`tagStandard41h12: 2`	`tagStandard41h12: 3`

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.

(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:

(ssh) ros2 topic echo /apriltag/detections

Result:

Output

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

Install the dependencies

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

Download source code from qrb-ros-sample repository

Clone the sample repository

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

Build sample from source code

Build the sample

cd ~/qrb_ros_sample_ws/src/qrb_ros_samples/robotics/sample_apriltag
colcon build --packages-up-to sample_apriltag
source install/setup.bash

Run and test

Run and test according to steps 2-4 of 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 from the source of sample_apriltag

​Device steps

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 from the source of `sample_apriltag`

Device steps