【Python】OpenCV ArUco 使用指南1. ArUco 介绍ArUco 是一种方形人工视觉标记fiducial marker。它不是用于存放网址或长文本的通用二维码而是为了让计算机稳定地获得以下信息这个标记是谁它在图像中的什么位置四个有序角点和中心点它朝向哪里编码可以消除 0°、90°、180°、270°之间的旋转歧义它相对相机的三维位置和姿态在已知标记尺寸及相机内参时通过 PnP 求解。ArUco 是机器人视觉中常用的技术栈其原始项目是一个基于 OpenCV 的独立 C 库后来其核心能力进入 OpenCV 的aruco模块。典型处理链如下相机图像 ↓ 检测候选方形轮廓 ↓ 透视展开并读取内部黑白编码 ↓ 在指定字典中识别 ID 和旋转方向 ↓ 获得 ID、四个有序角点、中心点 ↓可选已知相机内参和标记尺寸 solvePnP ↓ 获得标记相对相机的三维旋转和平移2. 一个 ArUco 码长什么样一个标准 ArUco 标记包含正方形外形连续的黑色边框用于快速寻找候选轮廓内部N × N黑白编码单元标记外部的白色留白用于与背景分离。以DICT_4X4_50为例4X4表示内部编码矩阵为 4×4而50表示该字典中共有 50 个合法 ID即049。黑色外框不计入 4×4 的编码矩阵。需要特别注意字典名是编码协议的一部分。DICT_4X4_50的 ID 0 和其他字典的 ID 0 并不是同一个图案。生成端与检测端必须选择完全相同的字典。3. ArUco 是如何工作的OpenCV 的经典检测过程可以简化为两个阶段。3.1 定位检测器先对图像进行自适应阈值处理再寻找轮廓并排除不满足要求的候选例如不是凸四边形面积过小或过大四个角距离不合理距离图像边缘太近与其他候选过于接近。这一步只说明“它看起来像一个方形标记”还不能确定它是合法 ArUco。3.2 解码对每个候选四边形检测器会通过透视变换把候选区域展开成正方形对展开图进行二值化按编码网格读取每个黑白单元检查黑色边框将读取结果的四种旋转与字典中的合法编码比较根据汉明距离完成识别和有限的错误校正。由于会比较四种旋转检测器不仅能得到 ID还能恢复标记的标准方向。OpenCV 随后按标记自身的标准方向返回四个角0标准左上角 1标准右上角 2标准右下角 3标准左下角4. 携带信息ArUco 内部编码的主要输出是字典 ID。业务层一般建立一张映射表MARKER_TYPES{0:机器人基座,1:抓取工位,2:放置工位,3:工件A,4:工件B,}这种做法的优势是编码紧凑、解码稳健适合数量有限且含义预先约定的对象。其限制也很明确可以表达有限的 ID 或类型不能像 QR Code 一样直接保存网址、JSON 或长序列号业务系统必须知道“字典 ID”与业务含义的映射如果映射会变更应在配置或数据库中维护而不要散落在算法代码中。如果现场需要标记直接携带较长信息可以让二维码负责业务数据另加 ArUco/AprilTag 负责高效定位也可以只在标签上打印短 ID再由系统查询数据库。OpenCV 提供了多组预定义字典常见的有字典内部网格ID 数量适合场景DICT_4X4_504×450类型不多、标记较小、入门验证DICT_4X4_1004×4100需要 50100 个 IDDICT_5X5_1005×5100希望比 4×4 有更大的编码区分空间DICT_6X6_2506×6250ID 较多、图像分辨率和标记尺寸充足DICT_7X7_10007×71000大规模编号要求每个单元仍有足够像素DICT_ARUCO_ORIGINAL原始 ArUco1024兼容历史项目DICT_APRILTAG_36h11AprilTag 族587用 OpenCV API 检测 AprilTag 编码选择原则不是“位数越高越好”而是先确定业务所需的 ID 数量选择能容纳这些 ID 的尽量小的字典再根据打印尺寸、最远距离和相机分辨率决定网格大小用真实相机和真实光照做检出率、误识别率及角点抖动测试。同样的物理尺寸下7×7 的单元比 4×4 更小。远距离成像时每个编码单元可能只剩很少像素网格更多反而可能更难识别。OpenCV 官方也建议选择能够满足应用规模的较小字典因为较小字典通常可以保留更好的码间距离。5. 开发测试5.1 运行环境先检查当前 OpenCV 是否包含arucoimportcv2print(cv2.__version__)print(hasattr(cv2,aruco))print(hasattr(cv2.aruco,ArucoDetector))本文使用环境的输出为4.13.0 True True一些较早的 Python 安装只包含基础 OpenCV可能没有cv2.aruco。项目已有固定环境时不应为解决这一问题直接升级或混装依赖应先核对现有依赖约束和部署环境。5.2 生成码下面生成DICT_4X4_50字典中的 ID 0frompathlibimportPathimportcv2 output_pathPath(aruco_dict4x4_50_id0.png)dictionarycv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)markerdictionary.generateImageMarker(0,800)# 白边不属于 ArUco 编码但有利于黑色外框与环境分离。printablecv2.copyMakeBorder(marker,120,120,120,120,cv2.BORDER_CONSTANT,value255)ifnotcv2.imwrite(str(output_path),printable):raiseRuntimeError(f保存标记失败{output_path})参数含义DICT_4X4_50使用的字典0字典中的 ID800生成图像中黑色标记主体的边长单位是像素120额外添加的白色留边打印尺寸应另行控制。不要从网页截图后打印也不要用会产生模糊插值的方式缩放。用于测量时优先输出足够分辨率的图像或矢量标定板并关闭打印软件的“适应页面”“缩放填充”等选项。5.3 检测示例importcv2 imagecv2.imread(camera_image.png)ifimageisNone:raiseFileNotFoundError(camera_image.png)dictionarycv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)parameterscv2.aruco.DetectorParameters()detectorcv2.aruco.ArucoDetector(dictionary,parameters)corners,ids,rejecteddetector.detectMarkers(image)ifidsisNone:print(没有检测到 ArUco 标记)else:formarker_id,marker_cornersinzip(ids.flatten(),corners):pointsmarker_corners.reshape(4,2)print(fID{int(marker_id)})print(points)cv2.aruco.drawDetectedMarkers(image,corners,ids)cv2.imwrite(detection_result.png,image)三个输出分别是corners每个已识别标记的四个有序角点ids与corners一一对应的 IDrejected外观像方形标记、但未通过字典解码的候选区域主要用于调试。
【Python】OpenCV ArUco 使用指南1. ArUco 介绍ArUco 是一种方形人工视觉标记fiducial marker。它不是用于存放网址或长文本的通用二维码而是为了让计算机稳定地获得以下信息这个标记是谁它在图像中的什么位置四个有序角点和中心点它朝向哪里编码可以消除 0°、90°、180°、270°之间的旋转歧义它相对相机的三维位置和姿态在已知标记尺寸及相机内参时通过 PnP 求解。ArUco 是机器人视觉中常用的技术栈其原始项目是一个基于 OpenCV 的独立 C 库后来其核心能力进入 OpenCV 的aruco模块。典型处理链如下相机图像 ↓ 检测候选方形轮廓 ↓ 透视展开并读取内部黑白编码 ↓ 在指定字典中识别 ID 和旋转方向 ↓ 获得 ID、四个有序角点、中心点 ↓可选已知相机内参和标记尺寸 solvePnP ↓ 获得标记相对相机的三维旋转和平移2. 一个 ArUco 码长什么样一个标准 ArUco 标记包含正方形外形连续的黑色边框用于快速寻找候选轮廓内部N × N黑白编码单元标记外部的白色留白用于与背景分离。以DICT_4X4_50为例4X4表示内部编码矩阵为 4×4而50表示该字典中共有 50 个合法 ID即049。黑色外框不计入 4×4 的编码矩阵。需要特别注意字典名是编码协议的一部分。DICT_4X4_50的 ID 0 和其他字典的 ID 0 并不是同一个图案。生成端与检测端必须选择完全相同的字典。3. ArUco 是如何工作的OpenCV 的经典检测过程可以简化为两个阶段。3.1 定位检测器先对图像进行自适应阈值处理再寻找轮廓并排除不满足要求的候选例如不是凸四边形面积过小或过大四个角距离不合理距离图像边缘太近与其他候选过于接近。这一步只说明“它看起来像一个方形标记”还不能确定它是合法 ArUco。3.2 解码对每个候选四边形检测器会通过透视变换把候选区域展开成正方形对展开图进行二值化按编码网格读取每个黑白单元检查黑色边框将读取结果的四种旋转与字典中的合法编码比较根据汉明距离完成识别和有限的错误校正。由于会比较四种旋转检测器不仅能得到 ID还能恢复标记的标准方向。OpenCV 随后按标记自身的标准方向返回四个角0标准左上角 1标准右上角 2标准右下角 3标准左下角4. 携带信息ArUco 内部编码的主要输出是字典 ID。业务层一般建立一张映射表MARKER_TYPES{0:机器人基座,1:抓取工位,2:放置工位,3:工件A,4:工件B,}这种做法的优势是编码紧凑、解码稳健适合数量有限且含义预先约定的对象。其限制也很明确可以表达有限的 ID 或类型不能像 QR Code 一样直接保存网址、JSON 或长序列号业务系统必须知道“字典 ID”与业务含义的映射如果映射会变更应在配置或数据库中维护而不要散落在算法代码中。如果现场需要标记直接携带较长信息可以让二维码负责业务数据另加 ArUco/AprilTag 负责高效定位也可以只在标签上打印短 ID再由系统查询数据库。OpenCV 提供了多组预定义字典常见的有字典内部网格ID 数量适合场景DICT_4X4_504×450类型不多、标记较小、入门验证DICT_4X4_1004×4100需要 50100 个 IDDICT_5X5_1005×5100希望比 4×4 有更大的编码区分空间DICT_6X6_2506×6250ID 较多、图像分辨率和标记尺寸充足DICT_7X7_10007×71000大规模编号要求每个单元仍有足够像素DICT_ARUCO_ORIGINAL原始 ArUco1024兼容历史项目DICT_APRILTAG_36h11AprilTag 族587用 OpenCV API 检测 AprilTag 编码选择原则不是“位数越高越好”而是先确定业务所需的 ID 数量选择能容纳这些 ID 的尽量小的字典再根据打印尺寸、最远距离和相机分辨率决定网格大小用真实相机和真实光照做检出率、误识别率及角点抖动测试。同样的物理尺寸下7×7 的单元比 4×4 更小。远距离成像时每个编码单元可能只剩很少像素网格更多反而可能更难识别。OpenCV 官方也建议选择能够满足应用规模的较小字典因为较小字典通常可以保留更好的码间距离。5. 开发测试5.1 运行环境先检查当前 OpenCV 是否包含arucoimportcv2print(cv2.__version__)print(hasattr(cv2,aruco))print(hasattr(cv2.aruco,ArucoDetector))本文使用环境的输出为4.13.0 True True一些较早的 Python 安装只包含基础 OpenCV可能没有cv2.aruco。项目已有固定环境时不应为解决这一问题直接升级或混装依赖应先核对现有依赖约束和部署环境。5.2 生成码下面生成DICT_4X4_50字典中的 ID 0frompathlibimportPathimportcv2 output_pathPath(aruco_dict4x4_50_id0.png)dictionarycv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)markerdictionary.generateImageMarker(0,800)# 白边不属于 ArUco 编码但有利于黑色外框与环境分离。printablecv2.copyMakeBorder(marker,120,120,120,120,cv2.BORDER_CONSTANT,value255)ifnotcv2.imwrite(str(output_path),printable):raiseRuntimeError(f保存标记失败{output_path})参数含义DICT_4X4_50使用的字典0字典中的 ID800生成图像中黑色标记主体的边长单位是像素120额外添加的白色留边打印尺寸应另行控制。不要从网页截图后打印也不要用会产生模糊插值的方式缩放。用于测量时优先输出足够分辨率的图像或矢量标定板并关闭打印软件的“适应页面”“缩放填充”等选项。5.3 检测示例importcv2 imagecv2.imread(camera_image.png)ifimageisNone:raiseFileNotFoundError(camera_image.png)dictionarycv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)parameterscv2.aruco.DetectorParameters()detectorcv2.aruco.ArucoDetector(dictionary,parameters)corners,ids,rejecteddetector.detectMarkers(image)ifidsisNone:print(没有检测到 ArUco 标记)else:formarker_id,marker_cornersinzip(ids.flatten(),corners):pointsmarker_corners.reshape(4,2)print(fID{int(marker_id)})print(points)cv2.aruco.drawDetectedMarkers(image,corners,ids)cv2.imwrite(detection_result.png,image)三个输出分别是corners每个已识别标记的四个有序角点ids与corners一一对应的 IDrejected外观像方形标记、但未通过字典解码的候选区域主要用于调试。
