> ## 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 是一个 ROS 包，为 Qualcomm 机器人平台提供 AprilTag 管线示例。

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

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/apriltag.gif" alt="Live camera view of AprilTag markers being detected, each overlaid with its tag outline and identifier." />
</Frame>

## `sample_apriltag` 的管线流程

下图展示了 `sample_apriltag` 的管线流程。

<Frame caption="sample_apriltag 管线。">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/apriltag-architecture.png" alt="AprilTag pipeline from camera capture through color space conversion and rectification to tag detection and pose output." />
</Frame>

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

## `sample_apriltag` 管线中使用的 ROS 节点

下表列出了 `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) | 提供一个 ROS 节点，用于将图像从 nv12 转换为 rgb8 格式。                       |
| [`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` 库检测图像中的 AprilTag，并发布其位姿、ID 和其他元数据。 |

## `sample_apriltag` 管线中使用的 ROS topic

下表列出了 `sample_apriltag` 管线中使用的 ROS topic，以及消息类型和发布每个 topic 的节点。

| ROS topic               | 类型                                         | 发布者                                                  |
| ----------------------- | ------------------------------------------ | ---------------------------------------------------- |
| `/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`                         |

## 前提条件

您已根据 [安装 QIR SDK](./install-the-qir-sdk) 在设备上完成设备设置、安装 ROS2 Jazzy 和 Qualcomm Intelligent Robotics (QIR) SDK。

## 运行开箱即用的 `sample_apriltag`

<Steps>
  <Step title="安装依赖项">
    ```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
    ```
  </Step>

  <Step title="安装 sample_apriltag 软件包">
    ```bash Install the packages theme={null}
    sudo apt install ros-jazzy-sample-apriltag
    ```
  </Step>

  <Step title="启动 AprilTag 管线示例">
    ```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
    ```
  </Step>

  <Step title="将以下 AprilTag 图像放置在摄像头前">
    | `tagStandard41h12: 1`                                                                                                                                                                              | `tagStandard41h12: 2`                                                                                                                                                                              | `tagStandard41h12: 3`                                                                                                                                                                              |
    | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/april-tag1.png" alt="AprilTag marker from the tagStandard41h12 family encoding identifier 1." /> | <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/april-tag2.png" alt="AprilTag marker from the tagStandard41h12 family encoding identifier 2." /> | <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/april-tag3.png" alt="AprilTag marker from the tagStandard41h12 family encoding identifier 3." /> |
  </Step>

  <Step title="在开发套件的另一个终端中，运行以下命令">
    a. 启动一个终端并运行以下命令以检查 apriltag 检测结果。

    ```bash theme={null}
    (ssh) export ROS_DOMAIN_ID=123
    (ssh) ros2 topic echo /apriltag/detections
    ```

    管线通过 `/apriltag/detections` 输出检测结果，并通过 `/tf` 检测标签位姿。

    b. 要检查 topic 输出，请运行以下命令：

    ```bash theme={null}
    (ssh) ros2 topic echo /apriltag/detections
    ```

    **结果：**

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

    结果显示检测到的标签为 `tagStandard41h12`，标签 ID 为 `1`。
  </Step>
</Steps>

## 从 `sample_apriltag` 的源代码构建

当您需要修改示例代码时，可以从源代码构建 `sample_apriltag`。设备端步骤包括安装依赖项、克隆源代码仓库并构建软件包。

### 设备端步骤

<Steps>
  <Step title="安装依赖项">
    ```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
    ```
  </Step>

  <Step title="从 qrb-ros-sample 仓库下载源代码">
    ```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
    ```
  </Step>

  <Step title="从源代码构建示例">
    ```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
    ```
  </Step>

  <Step title="运行并测试">
    根据 [运行开箱即用的 sample\_apriltag](./enable-apriltag-pipeline-with-sample-apriltag#run-out-of-the-box-sample_apriltag) 的第 2-4 步运行并测试。
  </Step>
</Steps>