🔬 视觉疲劳与姿势智能监测

def calculate_EAR(self, eye_points):
    """眼睛纵横比 (Eye Aspect Ratio)

    基于眼睛6个关键点的距离比值，判断眼睛开合程度。

            ● p1
       p2 ●       ● p6
       p3 ●       ● p5
            ● p4

       EAR = (||p2-p6|| + ||p3-p5||) / (2 × ||p1-p4||)

    技术要点：
    - EAR为比值量纲，对头部轻微晃动（±15°）具有天然鲁棒性
    - 左右眼独立计算后取均值，消除单侧遮挡或检测误差
    - EAR < 0.25 认定为闭眼状态（基于人脸解剖学比例）
    """
    A = np.linalg.norm(eye_points[1] - eye_points[5])
    B = np.linalg.norm(eye_points[2] - eye_points[4])
    C = np.linalg.norm(eye_points[0] - eye_points[3])
    ear = (A + B) / (2.0 * C)
    return ear

def apply_clahe(self, bgr_frame):
    """CLAHE 限制对比度自适应直方图均衡化

    化学实验室护目镜（PC镜片）产生高强度镜面反射（像素值≥240），
    直接覆盖眼部特征区域，导致MediaPipe检测失败率高达约42%。

    处理流程:
      BGR帧 → LAB色彩空间分离 → L通道CLAHE → 合并LAB → 还原BGR

    效果对比（实测数据）：
      无预处理（原始RGB）:  检测成功率约58%  |  额外延迟 0ms
      全局直方图均衡化:      检测成功率约71%  |  额外延迟约2ms
      LAB-CLAHE（本方案）:   检测成功率约93%  |  额外延迟约4ms
    """
    lab = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2LAB)
    l, a, b = cv2.split(lab)
    l_eq = self.clahe.apply(l)
    lab_eq = cv2.merge([l_eq, a, b])
    return cv2.cvtColor(lab_eq, cv2.COLOR_LAB2BGR)

def estimate_head_pose(self, mesh_points, frame_shape):
    """基于6个面部基准点的3D头部姿态解算

    选取MediaPipe 468点中最稳定的6个标志点：
      #1(鼻尖) #152(下颌) #33(左眼角) #263(右眼角) #61(左嘴角) #291(右嘴角)

    3D面部模型坐标（mm级，基于东亚成年人平均面部几何）：
      鼻尖(0,0,0)  下颌(0,-330,-65)
      左眼角(-225,170,-135)  右眼角(225,170,-135)
      左嘴角(-150,-150,-125)  右嘴角(150,-150,-125)

    相机内参矩阵 K_int = [[w,0,w/2],[0,w,h/2],[0,0,1]]
    焦距≈图像宽度（Webcam标准针孔模型近似）

    输出三个欧拉角 + 面部距离估算：
      Pitch(抬头角) Yaw(偏头角) Roll(歪头角)
      Distance = (焦距 × 人脸实际高度200mm) / 像素人脸高度
    """
    h, w = frame_shape[:2]
    image_points = mesh_points[self.FACE_LANDMARKS_2D].astype(np.float64)
    camera_matrix = np.array(
        [[w, 0, w / 2], [0, w, h / 2], [0, 0, 1]], dtype=np.float64
    )
    try:
        success, rvec, _ = cv2.solvePnP(
            self.FACE_MODEL_3D, image_points,
            camera_matrix, self.dist_coeffs,
            flags=cv2.SOLVEPNP_ITERATIVE
        )
        if success:
            self.pitch, self.yaw, self.roll = self._rvec_to_euler(rvec)
    except cv2.error:
        pass
    # 针孔相机模型距离估算
    y_coords = mesh_points[:, 1]
    h_pixel = y_coords.max() - y_coords.min()
    if h_pixel > 1:
        self.distance_mm = (w * self.REAL_FACE_HEIGHT_MM) / h_pixel

@staticmethod
def _rvec_to_euler(rvec):
    """Rodrigues旋转向量 → 欧拉角（Pitch/Yaw/Roll）"""
    R, _ = cv2.Rodrigues(rvec)
    pitch = np.degrees(np.arctan2(R[2, 1], R[2, 2]))
    yaw   = np.degrees(np.arctan2(R[2, 0],
                     np.sqrt(R[0, 0]**2 + R[1, 0]**2)))
    roll  = np.degrees(np.arctan2(R[1, 0], R[0, 0]))
    return pitch, yaw, roll

def update_perclos(self, ear_value):
    """瞳孔闭合时间比例 (PERCLOS) 滑动窗口更新

    在60秒滑动窗口内统计EAR低于阈值的帧数占比：
      PERCLOS = (EAR < 0.25的帧数 / 窗口总帧数) × 100%

    技术要点：
    - 窗口容量: 1800帧 (60s × 30fps)
    - 刷新频率: 每秒1次 (每30帧)，避免逐帧抖动
    - 数据结构: collections.deque, O(1)入队/出队
    - 分级标准: <15%正常 | 15-30%轻度 | ≥30%重度
    """
    self.ear_buffer.append(ear_value)
    self.perclos_frame_counter += 1
    if self.perclos_frame_counter % self.UPDATE_INTERVAL == 0:
        below = sum(1 for e in self.ear_buffer if e < self.EAR_THRESH)
        total = len(self.ear_buffer)
        self.perclos = (below / total * 100.0) if total > 0 else 0.0

# ===== 通道一：疲劳预警 =====
# 条件：双眼EAR均值 < 0.25，连续 ≥ 20帧（约667ms）
if avg_ear < self.EAR_THRESH:
    self.counter += 1
else:
    self.counter = 0   # EAR恢复正常时立即归零，避免累积误报

if self.counter >= self.CLOSED_EYES_FRAME:
    # 屏幕叠加红色背景：⚠ 疲劳预警：请立即休息！
    # 20帧阈值 ≈ 667ms，可区分正常眨眼（150-400ms）与疲劳微睡眠

# ===== 通道二：安全预警 =====
# 条件：面部距离 < 200mm（20cm）AND |Pitch| > 25° AND 持续 ≥ 90帧（3秒）
if (self.distance_mm < self.DANGER_DISTANCE_MM
    and abs(self.pitch) > self.DANGER_PITCH_DEG):
    self.danger_counter += 1
else:
    self.danger_counter = 0

if self.danger_counter >= self.DANGER_DURATION_FRAMES:
    # 屏幕叠加橙色背景：⚠ 安全预警：头部过于靠近！
    # 双条件AND逻辑防止单纯凑近或单纯前倾的误报
    # 90帧防抖缓冲（3秒）避免短暂姿势调整触发误报