这是一个基于pupil-apriltags库的AprilTag识别工具包，用于摄像头中AprilTag的检测和跟踪。
Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский | 中文
pip install opencv-python numpy pupil-apriltags
import cv2
from apriltag import Detector, DetectorOptions
# 创建检测器
options = DetectorOptions(
families="tag36h11", # 标签家族
border=1, # 标签边框大小
nthreads=4, # 线程数量
quad_decimate=1.0, # 图像下采样系数
quad_blur=0.0, # 高斯模糊系数
refine_edges=True # 是否精细化边缘
)
detector = Detector(options)
# 读取图像
img = cv2.imread("test_image.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# 检测AprilTag
detections = detector.detect(gray)
# 显示检测结果
for detection in detections:
print(f"标签家族: {detection.tag_family}, ID: {detection.tag_id}")
print(f"位置: {detection.center}")
print(f"角点: {detection.corners}")
import numpy as np
from apriltag import draw_detection_results
# 相机内参矩阵和畸变系数
K = np.array([[800, 0, 320], [0, 800, 240], [0, 0, 1]], dtype=np.float32)
D = np.zeros((4, 1), dtype=np.float32)
# 绘制检测结果
result_img = draw_detection_results(img, detections, K, D, tag_size=0.1)
# 显示结果
cv2.imshow("AprilTag检测", result_img)
cv2.waitKey(0)
提供简易测试脚本用于验证AprilTag检测功能：
python test_apriltag.py
该脚本将调用默认摄像头进行实时AprilTag检测，按"q"键退出程序。
pupil-apriltags库支持以下标签系列：
必须安装AprilTag的C语言库：
sudo apt-get update
sudo apt-get install -y libapriltag-dev
需自行编译或获取预编译版本，确保apriltag.dll位于系统PATH或当前目录。
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
pip install pupil-apriltags -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
集成工具提供交互式菜单引导完成全流程：
python apriltag_tool.py
菜单选项包含：
建议在使用前完成相机标定：
# 首先生成棋盘格标定板
python create_chessboard.py --size 9x6 --square 100 --output chessboard.png --dpi 300
# 打印棋盘格并测量实际方格大小，然后进行标定
python camera_calibration.py --size 9x6 --square 0.025 --output config/camera/HSK_200W53_1080P.yaml
参数说明:
棋盘格生成工具 (create_chessboard.py):
--size: 棋盘格内角点数(宽x高，默认:9x6)--square: 单格像素尺寸(默认:100)--output: 输出路径(默认:chessboard.png)--dpi: 输出图像DPI(默认:300)，影响打印尺寸标定程序 (camera_calibration.py):
--size: 内角点数(默认:9x6)--square: 实际棋盘格尺寸(单位:米，默认:0.025)--output: 输出配置文件(默认:config/camera/HSK_200W53_1080P.yaml)--camera: 摄像头ID(默认:0)--width: 采集宽度(默认:1280)--height: 采集高度(默认:720)--samples: 标定样本数(默认:20)--preview: 标定后预览校正效果标定步骤：
标定完成后运行检测程序：
python apriltag_detector.py
python apriltag_detector.py [配置文件路径] --camera 相机ID --width 宽度 --height 高度 --camera_info 相机参数文件
参数说明:
配置文件路径: AprilTag配置(默认:config/vision/tags_36h11_all.json)--camera: 摄像头ID(默认:0)--camera_info: 相机内参文件(默认:config/camera/HSK_200W53_1080P.yaml)--width: 采集宽度(默认:1280)--height: 采集高度(默认:720)q: 退出程序系统配置通过config/vision/table_setup.json文件管理：
{
"AprilTagConfig": {
"family": "tag36h11", // 标签家族
"size": 0.05, // 标签物理尺寸（单位：米）
"threads": 2, // 处理线程数
"max_hamming": 0, // 最大汉明距离
"z_up": true, // Z轴朝上
"decimate": 1.0, // 图像下采样系数
"blur": 0.8, // 模糊系数
"refine_edges": 1, // 是否精细化边缘
"debug": 0 // 是否打开调试
},
"Camera": {
"device_id": 0, // 相机设备ID
"width": 1280, // 相机宽度分辨率
"height": 720, // 相机高度分辨率
"camera_info_path": "config/camera/HSK_200W53_1080P.yaml" // 相机标定参数文件
},
"Archive": {
"enable": true, // 是否启用数据存档
"preview": true, // 是否显示预览窗口
"save_raw": false, // 是否保存原始图像
"save_pred": false, // 是否保存预测图像
"path": "./data/table_tracking" // 数据保存路径
},
"TableConfig": {
"reference_tags": [0, 1, 2, 3], // 参考标签ID列表
"moving_tags": [4, 5, 6], // 移动标签ID列表
"require_initialization": true, // 是否需要初始化
"tag_positions": { // 预设标签位置（如果有）
"0": [0.0, 0.0, 0.0],
"1": [0.5, 0.0, 0.0],
"2": [0.5, 0.5, 0.0],
"3": [0.0, 0.5, 0.0]
}
}
}
可配置项包括：
require_initialization设为false可跳过)基础启动命令：
python table_tracking.py
自定义配置文件启动：
python table_tracking.py --config 自定义配置文件路径
运行时按'i'键可手动触发初始化。
apriltag库缺失
确认库已正确安装且路径可访问。
摄像头异常
检查设备ID及占用情况。
检测精度问题
确保相机标定准确且标签尺寸配置正确。
apriltag_standalone/
├── apriltag.py # AprilTag检测库核心代码
├── apriltag_detector.py # AprilTag检测主程序
├── apriltag_tool.py # 集成工具启动菜单
├── camera_calibration.py # 相机标定程序
├── create_chessboard.py # 棋盘格生成工具
├── configs.py # 配置文件处理
├── config/ # 配置目录
│ ├── camera/ # 相机配置
│ │ └── HSK_200W53_1080P.yaml # 相机参数
│ └── vision/ # 视觉配置
│ └── tags_36h11_all.json # AprilTag配置
├── README.md # 说明文档
└── requirements.txt # Python依赖
本项目为ROS AprilTag包的独立移植版，核心技术栈：
MIT许可证授权
新增功能特性：
自动初始化：系统启动时自动记录：
遮挡补偿：初始化后支持：
多目标追踪：默认支持ID 4,5,6移动标签：
通过config/vision/table_setup.json配置：
{
"TableConfig": {
"reference_tags": [0, 1, 2, 3], // 参考标签ID列表
"moving_tags": [4, 5, 6], // 移动标签ID列表
"require_initialization": true, // 是否需要初始化
"tag_positions": { // 预设标签位置（如果有）
"0": [0.0, 0.0, 0.0],
"1": [0.5, 0.0, 0.0],
"2": [0.5, 0.5, 0.0],
"3": [0.0, 0.5, 0.0]
}
}
}
主要配置项：
默认配置启动：
python table_tracking.py
自定义配置启动：
python table_tracking.py --config 自定义路径
手动初始化：运行时按'i'键
初始化时需确保所有标签可见，系统将记录相对位置关系。初始化后可支持部分遮挡场景下的稳定追踪。