cv2.aruco模块无drawFrameAxes属性报错问题排查

• 开发环境：VSCode 1.68.1、Ubuntu 20.04
• 实现功能：基于ArUco标记实现3D位姿估计
• 触发报错：运行代码aruco.drawFrameAxes(dst1, mtx, dist, rvec[i, :, :], tvec[i, :, :],0.03)时抛出异常AttributeError: module 'cv2.aruco' has no attribute 'drawFrameAxes'
• 已尝试无效方案：
  • 将接口替换为aruco.drawaxis调用，仍报相同错误
  • 卸载opencv-python、opencv-contrib-python后通过pip3重新安装，报错未解决

1. OpenCV版本迭代导致API归属变更：4.7.0及以上版本中，drawFrameAxes接口从cv2.aruco子模块迁移到了cv2顶层模块，原调用路径失效
2. OpenCV包混装：Ubuntu 20.04默认apt源内置的python3-opencv版本为4.2，该版本aruco模块无drawFrameAxes接口；若未清理干净apt安装的版本、或pip安装的opencv主包与contrib包版本号不一致，会导致模块加载不全，接口找不到
3. 替换接口时拼写错误：旧版接口名为drawAxis（驼峰命名，A大写，无复数后缀s），写成drawaxis会因大小写不匹配触发找不到属性的错误

1. 彻底清理所有OpenCV相关残留包，避免混装
   执行以下命令删除apt安装的OpenCV、所有pip渠道安装的OpenCV变体包：

   sudo apt remove python3-opencv -y
   pip3 uninstall opencv-python opencv-contrib-python opencv-python-headless opencv-contrib-python-headless -y
   

   清理完成后执行pip3 list | grep opencv，无任何输出则代表清理干净。

2. 选择对应方案安装/调整代码

   • 方案一：安装适配旧教程API的稳定版本（无需修改原有教程代码）
     执行命令安装版本完全匹配的OpenCV包（两个包版本号必须一致，否则contrib模块无法正常加载）：

     pip3 install opencv-python==4.6.0.66 opencv-contrib-python==4.6.0.66
     

     安装完成后原有代码无需修改即可正常运行。
   • 方案二：使用高版本OpenCV（无需降级）
     安装最新版OpenCV：

     pip3 install opencv-python opencv-contrib-python
     

     将原代码中的aruco.drawFrameAxes调用替换为cv2.drawFrameAxes，传入参数保持完全一致即可，修改后代码示例：

     cv2.drawFrameAxes(dst1, mtx, dist, rvec[i, :, :], tvec[i, :, :],0.03)
     

进入Python3交互环境执行以下代码，返回对应True即代表接口可用：

import cv2
# 查看当前安装的OpenCV版本
print(cv2.__version__)
# 若使用4.6.x版本，执行以下语句返回True即为正常
print(hasattr(cv2.aruco, 'drawFrameAxes'))
# 若使用4.7+版本，执行以下语句返回True即为正常
print(hasattr(cv2, 'drawFrameAxes'))

注意：不要在虚拟环境和系统环境中重复安装OpenCV，避免Python导入时加载到错误版本的包。

内容的提问来源于stack exchange，提问作者Manpreet