Pupil Core 常见问题与解决方案

随着眼动追踪在科研、UX 测试、AR/VR 交互等领域的广泛应用，越来越多的用户开始使用 Pupil Core 平台。在使用过程中，经常会遇到硬件连接、校准失败、数据录制与回放等方面的挑战。本文基于 Pupil Labs 社区（Discord）中大量真实提问，提炼出最常见的问题及对应的解决方案，帮助你快速排查与修复。

1. 双目摄像头在 Mac M1 / macOS Ventura 上只能同时工作一个

问题描述 在 MacBook Pro M1（macOS Ventura）上启动 Pupil Capture 时，仅有一个眼部摄像头能被识别并工作，另一个一启用就断开。

解决方案

• 以管理员权限运行：在 macOS Monterey 及以上版本，必须通过终端以 sudo 来启动 Pupil Capture： bash复制编辑sudo /Applications/Pupil\ Capture.app/Contents/MacOS/Pupil\ Capture
• 使用原厂数据线：确保使用随机附带的、质量合格的 USB-C/Thunderbolt 转接线。第三方线材或不良接口可能导致供电不足或数据丢帧。.
• 切换端口：尝试将头戴设备插入不同的雷电（Thunderbolt）接口，以排除单个接口故障。

2. 校准界面标记不移动或校准失败

问题描述 在 Linux 或 Windows 上使用 Capture 的校准功能时，屏幕上的校准标记始终保持红色，并且不随步骤移动，最终显示“Calibration Failed”。

解决方案

1. 视野内只保留一个标记
   • 校准流程仅识别一个标记，如果场景中出现其他类似图形也会被误检。移除所有额外的图案或标记。
2. 尝试其他校准模式
   • 默认是 9 点校准，可在 Capture 的 plugin 设置中切换到 2 点或 5 点校准。
3. 调整摄像头视角与距离
   • 确保场景摄像头对整个屏幕可见，一般距离在 50–70 cm 效果最佳。标记大小建议占屏幕对角线的 5–10%。

3. 录制目录中出现 .writing 文件，无法在 Pupil Player 打开

问题描述 录制结束后，在录制文件夹中出现 world.mp4.writing 而非标准的 world.mp4，Pupil Player 无法加载。

解决方案

• 检查磁盘空间与权限：确保目标磁盘剩余空间足够，且对该目录具有写入权限。
• 完整关闭 Capture：在停止录制后，等待 Capture 自动结束写盘，切勿强制关机或拔线。
• 手动重命名与修复：如文件名后缀长时间未更新，可先将 .writing 去掉，再用 VLC 播放或通过 FFmpeg 重封装： bash复制编辑ffmpeg -i world.mp4.writing -c copy world_repaired.mp4

4. 在不同电脑/操作系统上播放录制视频失败

问题描述 在 macOS 13 上录制的视频文件，上传至 Google Drive、再在 macOS 12 上下载后，用 QuickTime 无法打开，但用 VLC 正常。

解决方案

• 避免网络转码：使用外接硬盘或 USB 驱动器从原机直接拷贝，防止云盘在上传/下载过程中重新压码。
• 安装必要的编解码器：在目标机器上安装或更新对 H.264/H.265 的支持插件，如 Perian（QuickTime 第三方扩展）或 macOS 内置编码包最新版。

5. 现场环境（室外/直射阳光）下无法稳定追踪

问题描述 在户外强光环境下，眼部摄像头频繁丢帧或追踪失败。

解决方案

• 使用遮光罩：为头戴设备加装遮阳罩，避免直射阳光进入眼部摄像头镜头。
• 调节红外发射功率：在 Pupil Capture 的 video source 设置里，适当提高 IR 强度参数，以提升瞳孔对比度。
• 选择合适的曝光与增益：在专业模式（Manual Camera Selection）中自行设定更高的曝光与增益。

6. 场景（World）摄像头连接不稳或丢帧

问题描述 使用 pyuvc 或手动切换摄像头时，场景摄像头偶发 TimeoutError，或在切换 USB 接口时无法恢复。

解决方案

• 更换线缆与接口：场景摄像头对带宽要求更高，须使用官方随机附带的“头部万向线缆”（Cable Tree），并插在主板直连端口。
• 避免长线过度拉伸：如果需要延长，可使用 USB3.0 集线器作为中继，但确保整个链路的带宽和供电充足。
• 检查硬件损伤：打开线缆树连接器端，确认无弯折或断针。

7. 自定义第三方摄像头接入失败

问题描述 在修改 camera_models.py、eye.py 后，Capture 仍然只能识别 Pupil Core 自带摄像头。

解决方案

• 启用“手动摄像头选择”：在 Pupil Capture 窗口右侧的摄像头图标设置中，勾选 “Manual Camera Selection”，即可在下拉菜单中看到并选用任意 UVC 摄像头。
• 使用统一分辨率与帧率：确保第三方摄像头驱动 UVC 协议下输出格式（如 1280×720 @ 60 fps）与 Capture 支持的参数一致。

8. MATLAB 等外部系统发送触发标注

问题描述 希望在 MATLAB 中通过 send_annotations.m 发送事件触发（Annotation）到 Pupil Capture，但两台电脑无法联网或只有一台有网络。

解决方案

• 局域网直连：两台电脑无需 Internet，只要在同一 LAN（有线或 Wi‑Fi）中，即可通过 ZeroMQ TCP/IP 互通。
• 指定 Pupil Remote IP：在示例脚本中，将默认 127.0.0.1 替换为 Capture 电脑的局域网 IP 地址，如： matlab复制编辑endpoint = 'tcp://192.168.1.42:50020'; send_annotation(endpoint, timestamp, 'StimulusOn');

结语

本文基于 Pupil Labs 社区真实案例，汇总了 Pupil Core 使用中最常见的 8 大问题及应对策略。希望能帮助你快速排查与解决常见故障，提高科研和产品研发效率。 如果在实践中依然遇到未能覆盖的特殊问题，欢迎访问 Pupil Labs 官方文档（https://docs.pupil-labs.com/core/）或联系 info@pupil-labs.com 寻求支持。

关键词：Pupil Core、眼动追踪、常见问题、解决方案、Pupil Capture、Pupil Player