企业官网建设流程全解析

• 计算机视觉
• AI 应用

EyeGestures 是一款基于普通摄像头（webcam）的开源眼动追踪（eye tracking）软件库，无需昂贵硬件就能实现"用眼睛控制光标"。但很多新手第一次运行 examples/simple_example_v4.py 时，常常遇到摄像头打不开、依赖缺失、检测不到人脸等问题。本文整理出 EyeGestures 眼动追踪最易踩的 5 个坑位，并给出完整的排查清单与解决方案，照着一步步检查即可快速修复。

一分钟速查表：

坑位一：Python 版本不匹配，导致 Rust 引擎加载失败

🔍典型症状：程序能跑，但光标不动，控制台输出类似Caugh error: ...的报错，或直接报ImportError。

EyeGestures v4 的核心算法是一个 Rust 编写的引擎（源码位于 engine/src/），通过预编译的动态库接入 Python。仓库中自带的预编译文件只覆盖特定版本：

• EyegesturesEngine.cpython-313-x86_64-linux-gnu.so
• EyegesturesEngine.cpython-314-x86_64-linux-gnu.so

而 pyproject.toml 中明确声明requires-python = ">=3.13"。在 eyeGestures/init.py 中可以看到，如果导入 Rust 引擎失败，代码会静默回退为RustEyeGesturesEngine = None——此时程序不会立刻崩溃，而是让眼动追踪"看起来能运行但完全失灵"。

✅解决方法：

1. 确认 Python 版本：python3 --version，应使用 3.13 或 3.14；
2. 用对应版本创建虚拟环境后再安装，例如：python3.13 -m venv .venv && source .venv/bin/activate；
3. 安装 EyeGestures 后，可运行python3 examples/simple_example_v4.py验证光标是否出现。

坑位二：mediapipe 等依赖没有随包安装

🔍典型症状：pip install eyeGestures成功后，运行示例仍报ModuleNotFoundError: No module named 'mediapipe'等错误。

这是官方 README "Troubleshooting" 一节中记录的高频问题：mediapipe、scikit-learn或opencv有时不会随 eyeGestures 一起装上。核心依赖声明可见 pyproject.toml（mediapipe与opencv-python），示例代码还需要pygame、numpy。

✅解决方法：手动补装缺失的依赖：

python3 -m pip install mediapipe opencv-python scikit-learn numpy pygame

版本要求可参考 eyeGestures/requirements.txt（mediapipe、opencv、scikit-learn 等）与根目录 requirements.txt。

💡 小技巧：先跑python3 examples/simple_example_v4.py，按报错提示缺什么装什么，通常一两轮就能补齐。

坑位三：摄像头打不开或被其他程序占用

🔍典型症状：启动后立即打印Was unable to open camera: 0.，或程序黑屏、卡住不动。

摄像头读取逻辑封装在 eyeGestures/utils.py 的VideoCapture类中。当指定编号的摄像头打开失败时，它会打印提示并尝试下一个编号（见 utils.py 的__openCam）。最常见的两种原因：

1. 摄像头被别的程序占用：视频会议软件、相机 App、甚至另一个跑着 EyeGestures 的终端，都会锁住设备；
2. 编号不对：接了两个摄像头（内置 + 外接）时，VideoCapture(0)不一定是你想用的那一个。

✅解决方法：

1. 关闭所有可能占用摄像头的程序（Zoom、微信视频、系统相机等），再运行python3 examples/simple_example_v4.py；
2. 换一个设备编号试试，例如把VideoCapture(0)改为VideoCapture(1)；
3. 项目提供了专门的摄像头排查示例 examples/troubleshooting_camera.py，可先跑它确认摄像头本身是否正常出画面。

坑位四：No face landmarks detected，检测不到人脸

🔍典型症状：控制台反复输出No face landmarks detected或Exception in FaceFinder，光标无反应。

眼动追踪的第一步是人脸关键点定位，这一步在 eyeGestures/init.py 中检测失败会直接抛出ValueError("No face landmarks detected")；人脸搜索逻辑在 eyeGestures/face.py 中，基于 mediapipe 的 FaceLandmarker 模型。

⚠️ 注意一个容易被忽略的细节：首次运行时程序会自动从网络下载人脸模型文件（face_landmarker.task，见 face.py）。如果机器没有外网，首次启动就会在这里失败。模型也可以预先下载后放到eyeGestures/face_landmarker_v2_with_blendshapes.task，或通过环境变量EYEGESTURES_FACE_LANDMARKER_MODEL指定本地路径。

✅解决方法（按顺序检查）：

1. 光照：补光或调整角度，避免逆光、脸过暗；
2. 距离：官方建议摄像头或笔记本放在约一臂（arm's length）的距离，太近人脸占满画面、太远人脸太小，都会导致检测失败；
3. 首次运行保证联网，让模型文件成功下载；
4. 检查摄像头画面是否模糊、镜头是否被遮挡。

坑位五：校准完成后光标漂移或不跟眼

🔍典型症状：程序能识别人脸，但校准时圆点难以"跟上"，或校准完成后光标位置偏移明显、跟眼不灵敏。

Rust 引擎的校准设计在 engine/src/eyegestures.rs 中：校准共需要25 个点（calib_max: 25），校准期间引擎会记录你的初始头部位置与面部大小作为参照系（head_start、start_width）。这意味着：

• 校准时头动幅度大 → 参照系不稳定 → 校准数据失真；
• 校准前后离屏幕距离变化明显 → 缩放比例改变 → 光标整体漂移。

✅解决方法：

1. 校准时保持头部基本不动，只让眼睛去"看"屏幕上的目标点，等圆点稳定后再移动视线；
2. 校准前后保持同一坐姿和距离（一臂左右），不要忽远忽近；
3. 若光标整体性偏移（比如总是偏右），重新做一次校准通常比调参数更有效；
4. 提醒一点：eyeGestures/init.py 的step方法带@recoverable装饰器，内部异常会被捕获并打印Caugh error: ...后返回空结果。调试时盯紧控制台输出，这是定位问题最快的一手信息。

完整排查清单（按顺序执行）

写在最后

EyeGestures 用普通摄像头就能实现眼动追踪，排障思路也可以概括为一句话：先保环境（Python 版本 + 依赖），再保输入（摄像头 + 人脸可见），最后保校准（姿势稳定）。

更多入口参考：

• 入门示例：examples/simple_example_v4.py（V4 Rust 引擎）、examples/simple_example_v3.py
• 摄像头排查：examples/troubleshooting_camera.py
• 核心算法：eyeGestures/init.py、engine/src/eyegestures.rs
• 旧版纯 Python 引擎示例：examples/legacy/

照清单走完一轮仍无法解决，可以把控制台的完整报错信息保存下来，对照项目 Issue 渠道反馈，通常能快速定位到根因。

• 计算机视觉
• AI 应用