This is an AprilTag recognition toolkit based on the pupil-apriltags library, designed for detecting and tracking AprilTags in camera feeds.
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)
A simple test script is provided to verify AprilTag detection functionality:
python test_apriltag.py
This will open the default computer camera and detect AprilTags in real-time. Press 'q' to exit.
The pupil-apriltags library supports the following tag families:
The AprilTag C library is required. Follow these steps:
sudo apt-get update
sudo apt-get install -y libapriltag-dev
Windows users need to compile from source or download pre-built binaries, ensuring apriltag.dll is in system PATH or current directory.
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
The simplest way is to use the integrated tool with interactive menu guidance:
python apriltag_tool.py
This tool provides menu options:
Follow the menu prompts to complete the entire process.
Before AprilTag detection, perform camera calibration for accurate camera parameters:
# 首先生成棋盘格标定板
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
Parameter descriptions:
Chessboard Generator (create_chessboard.py):
--size: Chessboard inner corner count, width×height (default: 9x6)--square: Square size in pixels (default: 100)--output: Output file path (default: chessboard.png)--dpi: Output image DPI (default: 300), affects print sizeCamera Calibration (camera_calibration.py):
--size: Chessboard inner corner count, width×height (default: 9x6)--square: Chessboard square size in meters (default: 0.025)--output: Output file path (default: config/camera/HSK_200W53_1080P.yaml)--camera: Camera device ID (default: 0)--width: Capture width (default: 1280)--height: Capture height (default: 720)--samples: Required calibration samples (default: 20)--preview: Preview correction effect after calibrationCalibration process:
After calibration, run AprilTag detection:
python apriltag_detector.py
python apriltag_detector.py [配置文件路径] --camera 相机ID --width 宽度 --height 高度 --camera_info 相机参数文件
Parameter descriptions:
Config file path: AprilTag config file path (default: config/vision/tags_36h11_all.json)--camera: Camera device ID (default: 0)--camera_info: Camera intrinsic file path (default: config/camera/HSK_200W53_1080P.yaml)--width: Capture width (default: 1280)--height: Capture height (default: 720)q: Quit programAll system configurations can be set in 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]
}
}
}
Configuration options:
require_initialization to false to skip)Simple one-command startup:
python table_tracking.py
For custom config files:
python table_tracking.py --config 自定义配置文件路径
Press 'i' during runtime to manually trigger initialization.
Cannot find apriltag library
Ensure proper installation and library path accessibility.
Camera fails to open
Verify device ID and check for other programs using the camera.
Inaccurate detection
Confirm proper camera calibration and correct tag size in configuration.
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依赖
This project is a ROS-independent port of the ROS AprilTag detection package, retaining core functionality using:
MIT License
New capabilities include:
Initialization Capture: System automatically records:
Occlusion Handling: After initialization:
Multi-Tag Tracking: Simultaneously tracks multiple mobile tags (default IDs 4,5,6)
All settings configurable in 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]
}
}
}
Customizable options:
require_initialization to false to skip)Default configuration:
python table_tracking.py
Custom configuration:
python table_tracking.py --config custom_config_path
Manual initialization: Press 'i' during runtime
Ensure all tags are visible during initialization to record relative positions. After initialization, the system can estimate positions even with partial occlusion.