OpenSesame
Rapunzel Code Editor
DataMatrix
Support forum
Python Tutorials
MindProbe
OpenSesame videos
Python videos
Supported by

PyGaze (眼动追踪)

关于

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_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)凝视位置元组。

  • 类型:元组
Supported by