PyGaze (眼动追踪)
- 关于
- 支持的眼球追踪器
- 安装PyGaze
- pip安装（所有平台）
- PyGaze OpenSesame 插件
- 示例
- 功能概述
- 类 eyetracker
- 函数 eyetracker.calibrate()
- 函数 eyetracker.close()
- 函数 eyetracker.connected()
- 函数 eyetracker.draw_calibration_target(x, y)
- 函数 eyetracker.draw_drift_correction_target(x, y)
- 函数 eyetracker.drift_correction(pos=None, fix_triggered=False)
- 函数 eyetracker.fix_triggered_drift_correction(pos=None, min_samples=30, max_dev=60, reset_threshold=10)
- 函数 eyetracker.get_eyetracker_clock_async()
- 函数 eyetracker.log(msg)
- 函数 eyetracker.log_var(var, val)
- 函数 eyetracker.pupil_size()
- 函数 eyetracker.sample()
- 函数 eyetracker.send_command(cmd)
- 函数 eyetracker.set_detection_type(eventdetection)
- 函数 eyetracker.set_draw_calibration_target_func(func)
- 函数 eyetracker.set_draw_drift_correction_target_func(func)
- 函数 eyetracker.set_eye_used()
- 函数 eyetracker.start_recording()
- 函数 eyetracker.status_msg(msg)
- 函数 eyetracker.stop_recording()
- 函数 eyetracker.wait_for_blink_end()
- 函数 eyetracker.wait_for_blink_start()
- 函数 eyetracker.wait_for_event(event)
- 函数 eyetracker.wait_for_fixation_end()
- 函数 eyetracker.wait_for_fixation_start()
- 函数 eyetracker.wait_for_saccade_end()
- 函数 eyetracker.wait_for_saccade_start()
关于
PyGaze是一个用于眼球追踪的Python库。一组插件允许您在OpenSesame中使用PyGaze。关于PyGaze的更多信息，请访问:
请引用PyGaze如下：
Dalmaijer, E., Mathôt, S., & Van der Stigchel, S. (2014). PyGaze: An open-source, cross-platform toolbox for minimal-effort programming of eyetracking experiments. Behavior Research Methods. doi:10.3758/s13428-013-0422-2
支持的眼球追踪器
PyGaze支持以下眼球追踪器：
对于以下眼球追踪器，有实验性支持：
您还可以使用WebGazer.js在在线实验中执行基本的眼球追踪：
PyGaze还包括两个用于测试目的的虚拟眼球追踪器：
- 简单虚拟 - 什么都不做。
- 高级虚拟 - 鼠标模拟眼动。
安装PyGaze
Windows
如果您使用的是OpenSesame的官方Windows软件包，那么PyGaze已经安装。
Ubuntu
如果您使用Ubuntu，您可以从Cogsci.nl PPA获得PyGaze：
sudo add-apt-repository ppa:smathot/cogscinl
sudo apt-get update
sudo apt-get install python-pygaze
如果您使用Python 3，将最后一个注释更改为：
sudo apt-get install python3-pygaze
pip安装（所有平台）
您可以使用pip安装PyGaze：
pip install python-pygaze
Anaconda（所有平台）
conda install python-pygaze -c cogsci
PyGaze OpenSesame 插件
以下PyGaze插件可用：
- pygaze_init - 初始化PyGaze。此插件通常插入实验开始部分。
- pygaze_drift_correct - 实现漂移校正过程。
- pygaze_start_recording - 将PyGaze置于录制模式。
- pygaze_stop_recording - 使PyGaze脱离录制模式。
- pygaze_wait - 暂停，直到发生事件，例如扫视开始。
- pygaze_log - 记录实验变量和任意文本。
示例
要查看如何使用PyGaze插件的示例，请参阅随OpenSesame附带的PyGaze模板。
以下是如何在Python inline_script中使用PyGaze的示例：
# 创建一个键盘和画布对象
my_keyboard = Keyboard(timeout=0)
my_canvas = Canvas()
my_canvas['dot'] = Circle(x=0, y=0, r=10, fill=True)
# 循环 ...
while True:
# ... 直到按下空格键
key, timestamp = my_keyboard.get_key()
if key == 'space':
break
# 从pygaze获取凝视位置 ...
x, y = eyetracker.sample()
# ... 并绘制一个基于验证凝视的点！
my_canvas['dot'].x = x + my_canvas.left
my_canvas['dot'].y = y + my_canvas.top
my_canvas.show()
功能概述
要在OpenSesame中初始化PyGaze，请将pygaze_init插件插入您的实验。一旦完成此操作，一个eyetracker对象将可用，其提供如下功能：
类 eyetracker
一个通用的Python库，用于眼动追踪。
函数 eyetracker.calibrate()
校准眼动追踪系统。此函数的实际行为取决于眼动追踪器的类型，并在下面进行了描述。
EyeLink:
此功能将激活摄像机设置屏幕，允许您调整摄像机并执行校准/验证程序。按下'q'将退出设置程序。按下'escape'，将首先触发确认对话框，然后在确认后引发异常。
EyeTribe:
激活一个简单的校准程序。
返回值：
如果校准成功，则返回True；如果校准失败，则返回False；此外，校准日志将添加到日志文件中，还将更新一些属性（例如检测算法的阈值）。
- 类型：布尔值
函数 eyetracker.close()
整净地关闭到追踪器的连接。保存数据并将self.connected设置为False。
函数 eyetracker.connected()
检查跟踪器是否已连接。
返回值：
如果已建立连接，则返回True；如果未建立连接，则返回False；将self.connected设置为相同的值。
- 类型：布尔值
函数 eyetracker.draw_calibration_target(x, y)
绘制一个校准目标。
参数：
x-- X坐标- 类型：整数
y-- Y坐标- 类型：整数
函数 eyetracker.draw_drift_correction_target(x, y)
绘制一个漂移校正目标。
参数：
x-- X坐标- 类型：整数
y-- Y坐标- 类型：整数
函数 eyetracker.drift_correction(pos=None, fix_triggered=False)
执行漂移校正程序。此函数在眼动追踪器类型上的具体行为在下面进行了描述。因为漂移校正可能会失败，所以您通常会在循环中调用此函数。
EyeLink:
在漂移校正过程中按'q'将激活摄像机设置屏幕。从那里，再次按下'q'将立即导致漂移校正失败。按下'escape'将有选择中断实验的选项，在这种情况下会引发异常。
关键字参数:
pos-- 固定点的(x, y)位置，或者为None表示中心固定。- 类型：元组，NoneType
- 默认值：None
fix_triggered-- 布尔值，表示漂移检查是否应根据凝视位置（True）或空格（False）执行。- 类型：布尔值
- 默认值：False
返回值：
布尔值，表示漂移检查是否正常（True）或异常（False）。
- 类型：布尔值
函数 eyetracker.fix_triggered_drift_correction(pos=None, min_samples=30, max_dev=60, reset_threshold=10)
通过收集一定数量的样本并计算与固定位置的平均距离，执行固定位置触发的漂移校正。
关键字参数：
pos-- 固定点的(x, y)位置，或者为None表示中心固定。- 类型：元组，NoneType
- 默认值：None
min_samples-- 计算平均偏差所需的最小样本数量。- 类型：整数
- 默认值：30
max_dev-- 固定的最大像素偏差。- 类型：整数
- 默认值：60
reset_threshold-- 如果两个连续样本之间的水平或垂直像素距离大于此阈值，则重置样本收集。- 类型：整数
- 默认值：10
返回：
表示漂移检查是否正常（True）或不正常（False）的布尔值。
- 类型：bool
函数 eyetracker.get_eyetracker_clock_async()
返回跟踪器时间和PyGaze时间之间的差值，可以用于同步时间
返回：
眼动跟踪器时间和PyGaze时间之间的差值。
- 类型：int、float
函数 eyetracker.log(msg)
将消息写入日志文件。
参数：
msg-- 一个消息。- 类型：str、unicode
函数 eyetracker.log_var(var, val)
将变量的名称和值写入日志文件
参数：
var-- 变量名。- 类型：str、unicode
val-- 变量值
函数 eyetracker.pupil_size()
返回最新的瞳孔大小样本；大小可能是以瞳孔直径或瞳孔面积来衡量的，这取决于您的设置（请注意，瞳孔大小大多以任意单位给出）。
返回：
返回当前正在跟踪的眼睛（由self.eye_used指定）的瞳孔大小，如果无法获取数据，则返回-1。
- 类型：int、float
函数 eyetracker.sample()
返回最新可用的凝视位置。
返回：
一个（x，y）元组，错误时返回（-1，-1）。
- 类型：元组
函数 eyetracker.send_command(cmd)
直接向眼动追踪器发送命令（并非所有品牌都支持；如果您的设置不支持直接命令，可能会产生警告消息）。
参数：
cmd-- 要发送到眼动追踪器的命令。- 类型：str、unicode
函数 eyetracker.set_detection_type(eventdetection)
将事件检测类型设置为PyGaze算法或原生算法（仅在可用的情况下：如果没有提供本地函数，检测类型将默认为PyGaze）
参数：
eventdetection-- 一个字符串，表示应该采用哪种检测类型：'pygaze'表示PyGaze事件检测算法，'native'表示制造商算法（仅在可用的情况下；如果没有本地事件检测可用，将默认为'pygaze'）- 类型：str、unicode
返回：
间跃、固定和眨眼的检测类型的元组，例如：('pygaze','native','native')，当传递的是'native'，原生检测对于间跃检测不可用。
- 类型：元组
函数 eyetracker.set_draw_calibration_target_func(func)
指定一个自定义函数来绘制校准目标。这将覆盖默认的[draw_calibration_target]。
参数：
func-- 用于绘制校准目标的函数。此函数应接受两个参数，用于目标的x和y坐标。- 类型：函数
函数 eyetracker.set_draw_drift_correction_target_func(func)
指定一个自定义函数来绘制漂移校正目标。这将覆盖默认的[draw_drift_correction_target]。
参数：
func-- 用于绘制漂移校正目标的函数。此函数应接受两个参数，用于目标的x和y坐标。- 类型：函数
函数 eyetracker.set_eye_used()
记录eye_used变量，基于指定的眼睛（如果两只眼睛都被追踪，使用左眼）。不返回任何内容。
函数 eyetracker.start_recording()
开始记录。当记录成功开始时，将self.recording设置为True。
函数 eyetracker.status_msg(msg)
将状态消息发送到眼动仪，该消息将显示在跟踪器的GUI中（仅适用于EyeLink设置）。
参数：
msg-- 一个要在实验者PC上显示的字符串， 例如："current trial: %d" % trialnr.- 类型：str，unicode
函数 eyetracker.stop_recording()
停止记录。当记录成功停止时，将self.recording设置为False。
函数 eyetracker.wait_for_blink_end()
等待眨眼结束并返回眨眼结束时间。 如果EVENTDETECTION设置为'pygaze'，则根据Dalmaijer等人（2013）进行检测；如果EVENTDETECTION设置为'native'，则使用本地检测功能（注意：并非每个系统都具有本地功能；如果没有可用的'native'，则退回到'pygaze'！）
返回：
从实验开始时间算起的毫秒数，作为眨眼结束时间。
- 类型：int，float
函数 eyetracker.wait_for_blink_start()
等待眨眼开始并返回眨眼开始时间。 如果EVENTDETECTION设置为'pygaze'，则根据Dalmaijer等人（2013）进行检测；如果EVENTDETECTION设置为'native'，则使用本地检测功能（注意：并非每个系统都具有本地功能；如果没有可用的'native'，则退回到'pygaze'！）
返回：
从实验开始时间算起的毫秒数，作为眨眼开始时间
- 类型：int，float
函数 eyetracker.wait_for_event(event)
等待一个事件。
参数:
-
event-- 一个整数事件代码，以下之一： -
3 = STARTBLINK
- 4 = ENDBLINK
- 5 = STARTSACC
- 6 = ENDSACC
- 7 = STARTFIX
- 8 = ENDFIX
- 类型：int
返回：
根据指定的事件，调用一个self.wait_for_*方法；返回相应方法的返回值。
函数 eyetracker.wait_for_fixation_end()
当注视结束时，返回时间和凝视位置； 函数假设当检测到与初始注视位置的偏离大于自身.pxfixtresh时，“注视”已经结束（self.pxfixtresh在self.calibration中创建，基于self.fixtresh，该属性在self .__init__中定义）。 如果EVENTDETECTION设置为'pygaze'，则根据Dalmaijer等人（2013）进行检测；如果EVENTDETECTION设置为'native'，则使用本地检测功能（注意：并非每个系统都具有本地功能；如果没有可用的'native'，则退回到'pygaze'！）
返回：
一个time, gazepos元组。时间是毫秒数（从expstart开始），gazepos是一个（x，y）凝视位置元组，表示从该位置开始注视。
- 类型：tuple
函数 eyetracker.wait_for_fixation_start()
返回定位开始的时间和位置； 该函数假设当凝视位置保持相对稳定（即，当最偏离的样本在 self.pxfixtresh 内）连续五个样本时开始“注视”（self.pxfixtresh 在 self.calibration 中创建，基于 self.fixtresh ，在 self.init 中定义的属性）。 如果 EVENTDETECTION 设置为'pygaze'，则基于 Dalmaijer 等人（2013）进行检测，或者如果 EVENTDETECTION 设置为'native'，则使用本机检测功能（注意：并非每个系统都具有本机功能；如果'native' 不可用，将回退到'pygaze'！）
返回：
一个time, gazepos元组。时间从 expstart 开始以毫秒为单位，gazepos 是从该位置启动定位的（x,y）凝视位置元组。
- 类型：元组
函数 eyetracker.wait_for_saccade_end()
在眼跳结束时返回结束时间，开始和结束位置；如果 EVENTDETECTION 设置为'pygaze'，则基于 Dalmaijer 等人(2013)在线眼跳检测算法，或者如果 EVENTDETECTION 设置为'native'，则使用本机检测功能（注意：并非每个系统都具有本机功能；如果'native' 不可用，将回退到'pygaze'！）
返回：
一个 endtime, startpos, endpos 元组。 Endtime 以毫秒为单位（从 expbegintime 开始）； startpos 和 endpos 是（x,y）凝视位置元组。
- 类型：元组
函数 eyetracker.wait_for_saccade_start()
在眼跳开始时返回开始时间和起始位置；如果 EVENTDETECTION 设置为'pygaze'，则基于 Dalmaijer 等人(2013)在线眼跳检测算法，或者如果 EVENTDETECTION 设置为'native'，则使用本机检测功能（注意：并非每个系统都具有本机功能；如果'native' 不可用，将回退到'pygaze'！）
返回：
一个 endtime, startpos 元组。 Endtime 以毫秒为单位（从 expbegintime 开始）； startpos 是一个（x,y）凝视位置元组。
- 类型：元组