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

# 使用 sample_apriltag 启用 AprilTag 流水线

`sample_apriltag` 是一个为 Qualcomm 机器人平台提供 AprilTag 流水线示例的 ROS 包。

<Note>
  **注意**

  有关更多信息，请参见 GitHub 上的 [sample\_apriltag](https://github.com/qualcomm-qrb-ros/qrb_ros_samples/tree/main/robotics/sample_apriltag)。
</Note>

<video
  autoPlay
  muted
  loop
  playsInline
  width={720}
  height={456}
  src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/sample-apriltag.mp4"
  style={{
width: "90%",
display: "block",
margin: "0 auto" }}
/>

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  图：`sample_apriltag` 的示例结果
</p>

## `sample_apriltag` 的流水线流程

<img
  src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/sample-apriltag-pipeline-regenerate.svg"
  style={{
width: "100%",
display: "block",
margin: "0 auto" }}
/>

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  图：`sample_apriltag` 的流水线流程
</p>

* 该流水线从 `qrb_ros_camera` 接收 NV12 图像并将色彩空间转换为 RGB8 格式。
* 然后，它使用 `image_proc` 对图像进行校正，并输出 `/apriltag/image_rect`。
* `Apriltag` 节点检测标签并计算它们的位姿，这些位姿通过 `/tf` 发布。

## `sample_apriltag` 流水线中使用的 ROS 节点

| **ROS 节点**                                                                                                              | **说明**                                                        |
| :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| [qrb\_ros::camera::CameraNode](https://github.com/qualcomm-qrb-ros/qrb_ros_camera)                                      | 这是一个 Qualcomm ROS 2 包，使用参数捕获图像并将其发布到 ROS topic。               |
| [qrb\_ros::colorspace\_convert::ColorspaceConvertNode](https://github.com/qualcomm-qrb-ros/qrb_ros_color_space_convert) | 这是一个将图像从 nv12 转换为 rgb8 格式的 ROS 节点。                            |
| [image\_proc::RectifyNode](https://github.com/ros-perception/image_pipeline/tree/rolling/image_proc)                    | 订阅未校正图像和摄像头标定元数据以进行校正。                                        |
| [apriltag\_ros::AprilTagNode](https://github.com/christianrauch/apriltag_ros)                                           | 此 ROS 2 节点使用 `AprilTag` 库检测图像中的 AprilTags，并发布它们的位姿、ID 和其他元数据。 |

## `sample_apriltag` 流水线中使用的 ROS topic

<table>
  <thead>
    <tr>
      <th style={{ width: '25%' }}>ROS topic</th>
      <th style={{ width: '35%' }}>类型</th>
      <th style={{ width: '40%' }}>发布者</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`/apriltag/image_nv12`</td>
      <td>`sensor_msgs/msg/Image`</td>
      <td>`qrb_ros::camera::CameraNode`</td>
    </tr>

    <tr>
      <td>`/apriltag/camera_info`</td>
      <td>`sensor_msgs/msg/CameraInfo`</td>
      <td>`qrb_ros::camera::CameraNode`</td>
    </tr>

    <tr>
      <td>`/apriltag/image_rgb8`</td>
      <td>`sensor_msgs/msg/Image`</td>
      <td>`qrb_ros::colorspace_convert::ColorspaceConvertNode`</td>
    </tr>

    <tr>
      <td>`/apriltag/image_rect`</td>
      <td>`sensor_msgs/msg/Image`</td>
      <td>`image_proc::RectifyNode`</td>
    </tr>

    <tr>
      <td>`/apriltag/detections`</td>
      <td>`apriltag_msgs/msg/AprilTagDetectionArray`</td>
      <td>`apriltag_ros::AprilTagNode`</td>
    </tr>

    <tr>
      <td>`/tf`</td>
      <td>`tf2_msgs/msg/TFMessage`</td>
      <td>`apriltag_ros::AprilTagNode`</td>
    </tr>
  </tbody>
</table>

## 前提条件

你已完成 [设置运行示例应用的环境](./set-up-env-for-sample-app) 中的设置。

## 开箱即用运行 `sample_apriltag`

<Accordion title="试一试">
  <Steps>
    <Step title="在开发套件上运行示例">
      ```bash title="SSH Session" theme={null}
      # 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
      ```
    </Step>

    <Step title="将 AprilTag 图像放置在摄像头前">
      <table>
        <tr>
          <th align="center">
            <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/april-tag1.png" alt="tagStandard41h12-1" width="150" />
          </th>

          <th align="center">
            <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/april-tag2.png" alt="tagStandard41h12-2" width="150" />
          </th>

          <th align="center">
            <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/april-tag3.png" alt="tagStandard41h12-3" width="150" />
          </th>
        </tr>

        <tr>
          <td align="center">tagStandard41h12: 1</td>
          <td align="center">tagStandard41h12: 2</td>
          <td align="center">tagStandard41h12: 3</td>
        </tr>
      </table>
    </Step>

    <Step title="检查检测结果">
      1. 启动一个终端并运行以下命令来检查 apriltag 检测结果。
         ```bash title="SSH Session" theme={null}
         source /usr/share/qirp-setup.sh
         export ROS_DOMAIN_ID=123
         ros2 topic echo /apriltag/detections
         ```
         该流水线通过 `/apriltag/detections` 输出检测结果，并通过 `/tf` 检测标签位姿。
      2. 要检查 topic 输出，请运行以下命令：
         ```bash title="SSH Session" theme={null}
         ros2 topic echo /apriltag/detections
         ```
         **结果：**
         ```bash 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
         ...
         ```

      结果显示：

      * 检测到的标签：`tagStandard41h12`

      * 标签 ID：`1`
    </Step>
  </Steps>
</Accordion>

## 构建并运行 `sample_apriltag`

<Accordion title="试一试">
  <Steps>
    <Step title="在主机计算机上构建并打包">
      1. 构建示例应用项目。
         ```bash theme={null}
         cd <qirp_decompressed_workspace>
         source setup.sh
         # build sample
         cd qirp-samples/robotics/sample_apriltag
         colcon build
         ```
      2. 打包并将示例应用推送到设备。
         ```bash theme={null}
         # 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/
         ```
    </Step>

    <Step title="在开发套件上安装并运行">
      1. 安装示例应用。
         ```bash title="SSH Session" theme={null}
         # 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/
         ```
      2. 按照 [开箱即用运行 sample\_apriltag](#run-out-of-the-box-sample_apriltag) 中的步骤运行示例应用。
    </Step>
  </Steps>
</Accordion>