import cv2  # 导入 OpenCV，用于视频捕获和图像处理
import mediapipe as mp  # 导入 MediaPipe，用于手部关键点检测

# =================== 初始化 MediaPipe 模块 ===================

# 获取 MediaPipe 手部识别模块
mp_hands = mp.solutions.hands

# 创建 Hands 对象，用于处理图像中的手部关键点
# 默认参数含义：
# - static_image_mode=False：处理连续视频流（非静态图片）
# - max_num_hands=2：最多检测2只手
# - min_detection_confidence=0.5：置信度低于0.5的检测结果将被忽略
hands = mp_hands.Hands()

# 获取用于绘制关键点和连接线的工具
mp_draw = mp.solutions.drawing_utils

# =================== 初始化摄像头 ===================

# 打开默认摄像头（设备编号为0）
cap = cv2.VideoCapture(0)

# =================== 主循环，逐帧处理 ===================

while True:
    # 捕获一帧图像
    ret, frame = cap.read()

    # 如果捕获失败，退出循环
    if not ret:
        break

    # 水平翻转图像（摄像头默认是镜像视角，翻转后更自然）
    frame = cv2.flip(frame, 1)

    # OpenCV 默认使用 BGR 格式，而 MediaPipe 要求输入 RGB 格式图像
    rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)

    # 使用 MediaPipe 的 hand 模块处理当前帧，检测手部关键点
    results = hands.process(rgb_frame)

    # =================== 处理检测结果 ===================

    # 如果检测到了手部
    if results.multi_hand_landmarks:
        # 遍历每只手
        for landmarks in results.multi_hand_landmarks:
            # 在原图上绘制21个关键点及其连接骨骼（HAND_CONNECTIONS）
            mp_draw.draw_landmarks(frame, landmarks, mp_hands.HAND_CONNECTIONS)

            # 提取21个关键点的 Landmark 对象（含 x, y, z 三维坐标）
            landmark_points = [landmarks.landmark[i] for i in range(21)]

            # =================== 手势识别部分（可拓展） ===================
            # 例如：判断是否为“比赞”手势（此处未实现具体函数）
            # if detect_thumb_up(landmark_points):
            #     cv2.putText(frame, "Thumb Up!", (50, 100),
            #                 cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

    # =================== 显示图像 ===================

    # 显示处理后的视频帧（窗口标题为 Hand Gesture Detection）
    cv2.imshow('Hand Gesture Detection', frame)

    # 等待键盘事件，如果按下 'q' 键则退出程序
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

# =================== 清理资源 ===================

# 释放摄像头
cap.release()

# 销毁所有 OpenCV 窗口
cv2.destroyAllWindows()