Это инструментарий для распознавания AprilTag на основе библиотеки pupil-apriltags, предназначенный для обнаружения и отслеживания 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 поддерживает следующие семейства тегов:
Требуется установить C-библиотеку AprilTag:
sudo apt-get update
sudo apt-get install -y libapriltag-dev
Пользователям Windows необходимо самостоятельно скомпилировать или скачать предварительно собранные бинарные файлы, убедившись, что 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
Этот инструмент предоставляет следующие опции:
Просто следуйте подсказкам меню для завершения всего процесса.
Перед детектированием AprilTag рекомендуется выполнить калибровку камеры:
# 首先生成棋盘格标定板
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: Количество внутренних углов шахматной доски, ширинаxвысота (по умолчанию: 9x6)--square: Размер квадрата шахматной доски в метрах (по умолчанию: 0.025)--output: Путь для сохранения файла (по умолчанию: config/camera/HSK_200W53_1080P.yaml)--camera: ID устройства камеры (по умолчанию: 0)--width: Ширина захвата камеры (по умолчанию: 1280)--height: Высота захвата камеры (по умолчанию: 720)--samples: Количество необходимых образцов для калибровки (по умолчанию: 20)--preview: Просмотр эффекта коррекции после калибровкиПроцесс калибровки:
После калибровки можно запустить программу детектирования AprilTag:
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 не найдена
Убедитесь, что библиотека 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, без зависимостей от ROS, но с сохранением основной функциональности. Используются следующие технологии:
Проект распространяется под лицензией 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]
}
}
}
Через конфигурационный файл можно:
require_initialization в false пропускает шаг инициализации)Запуск системы с настройками по умолчанию:
python table_tracking.py
Запуск системы с пользовательским конфигурационным файлом:
python table_tracking.py --config путь_к_пользовательскому_файлу
Ручная инициализация: во время работы системы нажмите клавишу 'i'
Убедитесь, что все теги видны во время инициализации, система запомнит их относительное положение. После инициализации система сможет правильно оценить положение всех тегов, даже если некоторые перекрыты.