作者：科采通

---

Pupil Labs 是一款开源、可扩展的视线追踪（眼动追踪）设备，广泛应用于人机交互、心理学实验、教育行为研究等领域。其核心设备 Pupil Core 可以输出包括瞳孔信息、注视点位置、视频流及时间戳在内的多种原始数据。

本篇文章将详尽介绍 Pupil Core 数据采集后的文件结构与各类数据的字段含义，并提供 Python 解析建议，帮助开发者与研究人员更加高效地使用其数据。

---

一、数据文件夹结构说明

一次完整的录制数据通常如下所示：

20XX_XXXX/             # 主数据目录，可自定义
├── 000/               # 每次录制的数据编号，从001开始
│   ├── world.mp4           # 外部摄像头视频
│   ├── eye0.mp4            # 内部摄像头（右眼）
│   ├── world_timestamps.npy
│   ├── eye0_timestamps.npy
│   ├── info.csv            # 采集设备与软件信息
│   ├── user_info.csv       # 可自定义填写的用户信息
│   ├── pupil_data/         # 原始数据
│   ├── camera_calibration/ # 摄像头标定参数
│   └── exports/            # Pupil Player 导出的数据
│       ├── pupil_positions.csv
│       ├── gaze_positions.csv
│       └── pupil_gaze_positions_info.txt

---

二、各文件功能简述

文件名	描述
info.csv	记录设备信息、帧率、时间戳等元数据
user_info.csv	记录用户（受试者）信息，可自定义
world.mp4 / eye0.mp4	录像数据（世界视角 / 眼球摄像头）
*_timestamps.npy	视频帧对应的时间戳（NumPy 数组）
pupil_positions.csv	每一帧检测到的瞳孔参数
gaze_positions.csv	注视点的 2D/3D 空间位置等信息
camera_calibration	校准参数（如相机内参矩阵）
pupil_data/	包含 MsgPack 原始格式的数据包

---

三、pupil_positions.csv 字段说明（瞳孔检测数据）

该文件记录的是 Pupil Capture 通过眼部摄像头检测到的瞳孔特征点与三维几何拟合参数。

字段	含义
timestamp	当前帧时间戳
id	眼别：0 = 右眼，1 = 左眼
confidence	检测置信度，建议 >0.6 为可靠数据
norm_pos_x / y	归一化坐标（相对于摄像头图像）
diameter	瞳孔在图像中的像素直径
ellipse_center_x / y	拟合椭圆的中心
ellipse_axis_a / b	长轴 / 短轴长度
ellipse_angle	椭圆角度（弧度）
diameter_3d	三维空间中估计的瞳孔直径（单位 mm）
circle_3d_center_x / y / z	三维瞳孔中心坐标
circle_3d_normal_x / y / z	三维空间中瞳孔法向量
circle_3d_radius	三维瞳孔半径
model_confidence	三维模型拟合可信度（0或1）

---

四、gaze_positions.csv 字段说明（注视点追踪）

该文件记录的是注视点（gaze）在世界视角下的 2D 和 3D 空间位置。

字段	含义
timestamp	当前帧时间戳
confidence	注视点追踪可靠性（0或1）
norm_pos_x / y	注视点的图像坐标（归一化）
gaze_point_3d_x / y / z	gaze 点在三维空间的坐标
eye_center0_3d_x / y / z	右眼眼球中心的三维位置
gaze_normal0_x / y / z	右眼视线方向向量
eye_center1_*, gaze_normal1_*	左眼数据（如果使用双眼追踪设备）

如果仅使用单眼采集设备，则第二组字段可能为空。

---

五、info.csv 字段示例

该文件记录本次录制的环境信息。

字段	示例内容
System Info	用户名 / 设备型号
Start Time / Start Date	精确时间戳
Duration Time	录制时长（秒）
World Camera Resolution	分辨率如 1280×720
Capture Software Version	如 v3.5.2
Data Format Version	如 1.9

---

六、Python 读取 pupil_data 示例

pupil_data 文件夹中是使用 msgpack 编码的原始数据流，可用以下代码读取：

import msgpack

def read_pupil_data(path):
    with open(path, 'rb') as f:
        unpacker = msgpack.Unpacker(f, raw=False)
        data = [msg for msg in unpacker]
    return data

data = read_pupil_data("pupil_data/000/pupil_data")

---

七、数据使用建议

• 瞳孔直径分析：可用于 Pupillometry（认知负荷、生理反应）研究；

• 热图生成：用 gaze_positions 计算注视点热力图；

• 行为对齐：结合外部事件数据（如 EEG、视频刺激）进行时间同步；

• 三维建模：使用 gaze 向量实现三维注视方向重建；

• 置信度过滤：剔除 confidence < 0.6 的低质量数据帧。

---

八、结语

理解和掌握 Pupil Labs 数据结构对于眼动研究和人机交互开发至关重要。配合 Python 脚本与 Player 工具，用户可以灵活地导出、分析和可视化多维眼动数据，应用于多模态脑机接口、教学实验评估、用户行为建模等多个科研场景。

如需配套的代码库、数据处理教程或与 EEG、LSL 的多模态整合方法，欢迎关注后续专栏更新或在评论区留言交流。

---

关键词：Pupil Labs、眼动追踪、注视点、瞳孔数据、Python、科研数据结构、gaze、pupillometry、眼动可视化

产品资料：

Pupil Labs 国内代理：Pupil Labs | 研究级模块化眼动追踪设备-科采通