运行CVZone手部检测ASL项目时遇回溯错误，寻求解决方法

问题背景 #

运行基于CVZone的美式手语手部检测项目时出现回溯错误，怀疑是CVZone模块导入问题，已尝试重装教程同款版本的相关包但无效。

项目代码 #

import cv2
from cvzone.HandTrackingModule import HandDetector
import numpy as np
import math
import time

cap = cv2.VideoCapture(0)
detector = HandDetector(maxHands=1)

offset = 20
imgSize = 300

folder = "Data/C"
counter = 0

while True:
    success, img = cap.read()
    hands, img = detector.findHands(img)
    if hands:
        hand = hands[0]
        x, y, w, h = hand['bbox']

        imgWhite = np.ones((imgSize, imgSize, 3), np.uint8) * 255
        imgCrop = img[y - offset:y + h + offset, x - offset:x + w + offset]

        imgCropShape = imgCrop.shape

        aspectRatio = h / w

        if aspectRatio > 1:
            k = imgSize / h
            wCal = math.ceil(k * w)
            imgResize = cv2.resize(imgCrop, (wCal, imgSize))
            imgResizeShape = imgResize.shape
            wGap = math.ceil((imgSize - wCal) / 2)
            imgWhite[:, wGap:wCal + wGap] = imgResize

        else:
            k = imgSize / w
            hCal = math.ceil(k * h)
            imgResize = cv2.resize(imgCrop, (imgSize, hCal))
            imgResizeShape = imgResize.shape
            hGap = math.ceil((imgSize - hCal) / 2)
            imgWhite[hGap:hCal + hGap, :] = imgResize

        cv2.imshow("ImageCrop", imgCrop)
        cv2.imshow("ImageWhite", imgWhite)

    cv2.imshow("Image", img)
    key = cv2.waitKey(1)
    if key == ord("s"):
        counter += 1
        cv2.imwrite(f'{folder}/Image_{time.time()}.jpg', imgWhite)
        print(counter)

错误情况 #

附上显示导入/运行时回溯信息的错误截图

解决方案 #

1. 排查CVZone版本与导入路径 #

• 检查当前CVZone版本：执行pip show cvzone，若版本与教程差异较大，尝试降级到教程使用的版本（如4.1.0）：pip install cvzone==4.1.0
• 若使用新版本CVZone（如>=5.x），HandDetector的导入路径已变更，需修改导入语句为：from cvzone.HandTracking import HandDetector

2. 确认依赖包完整性 #

CVZone依赖mediapipe和opencv-python，确保这两个包正确安装且版本匹配：

pip install mediapipe opencv-python --upgrade

3. 验证基础导入 #

编写极简测试脚本，确认模块是否能正常导入：

import cv2
# 根据版本选择导入语句
from cvzone.HandTrackingModule import HandDetector  # 旧版本
# from cvzone.HandTracking import HandDetector  # 新版本
detector = HandDetector(maxHands=1)
print("模块导入成功")

若脚本报错，直接定位导入问题；若成功，继续排查原代码。

4. 适配findHands方法返回值 #

部分CVZone版本中，findHands方法仅返回处理后的图像，手部数据需通过detector.hands获取，修改原代码对应部分：

img = detector.findHands(img)
hands = detector.hands

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