OpenSesame
Rapunzel Code Editor
DataMatrix
Support forum
Python Tutorials
MindProbe
Supported by
Edit on GitHub

PyGaze (Eye-Tracking)

Über

PyGaze ist eine Python-Bibliothek für Eye Tracking. Ein Satz von Plugins ermöglicht Ihnen, PyGaze innerhalb von OpenSesame zu verwenden. Für weitere Informationen über PyGaze, besuchen Sie:

Bitte zitieren Sie PyGaze wie folgt:

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

Unterstützte Eye Tracker

PyGaze unterstützt die folgenden Eye Tracker:

Für die folgenden Eye Tracker gibt es experimentelle Unterstützung:

Mit WebGazer.js können Sie auch grundlegendes Eye Tracking für Online-Experimente durchführen:

PyGaze enthält auch zwei Dummy-Eye Tracker für Testzwecke:

  • Einfacher Dummy — Tut nichts.
  • Erweiterter Dummy — Maus-Simulation von Augenbewegungen.

PyGaze installieren

Windows

Wenn Sie das offizielle Windows-Paket von OpenSesame verwenden, ist PyGaze bereits installiert.

Ubuntu

Wenn Sie Ubuntu verwenden, können Sie PyGaze aus dem Cogsci.nl PPA beziehen:

sudo add-apt-repository ppa:smathot/cogscinl
sudo apt-get update
sudo apt-get install python-pygaze

Oder, wenn Sie Python 3 verwenden, ändern Sie den letzten Kommentar in:

sudo apt-get install python3-pygaze

pip install (alle Plattformen)

Sie können PyGaze mit pip installieren:

pip install python-pygaze

Anaconda (alle Plattformen)

conda install python-pygaze -c cogsci

PyGaze OpenSesame Plugins

Die folgenden PyGaze Plugins sind verfügbar:

  • pygaze_init — Initialisiert PyGaze. Dieses Plugin wird im Allgemeinen am Anfang des Experiments eingefügt.
  • pygaze_drift_correct — Implementiert ein Driftkorrekturverfahren.
  • pygaze_start_recording — Setzt PyGaze in den Aufnahmemodus.
  • pygaze_stop_recording — Setzt PyGaze aus dem Aufnahmemodus zurück.
  • pygaze_wait — Pausiert bis ein Ereignis eintritt, wie z.B. der Beginn einer Sakkade.
  • pygaze_log — Protokolliert experimentelle Variablen und beliebigen Text.

Beispiel

Ein Beispiel, wie die PyGaze Plugins verwendet werden, finden Sie in der PyGaze Vorlage, die mit OpenSesame enthalten ist.

Im Folgenden finden Sie ein Beispiel, wie PyGaze in einem Python inline_script verwendet wird:

# Erstellen Sie ein Tastatur- und ein Canvas-Objekt
my_keyboard = Keyboard(timeout=0)
my_canvas = Canvas()
my_canvas['dot'] = Circle(x=0, y=0, r=10, fill=True)
# Schleife ...
while True:
    # ... bis die Leertaste gedrückt wird
    key, timestamp = my_keyboard.get_key()
    if key == 'space':
        break
    # Holen Sie die Blickposition von pygaze ...
    x, y = eyetracker.sample()
    # ... und zeichnen Sie einen blickkontingenten Fixationspunkt!
    my_canvas['dot'].x = x + my_canvas.left
    my_canvas['dot'].y = y + my_canvas.top
    my_canvas.show()

Funktionsübersicht

Um PyGaze in OpenSesame zu initialisieren, fügen Sie das pygaze_init Plugin in Ihr Experiment ein. Sobald Sie dies getan haben, steht Ihnen ein eyetracker Objekt zur Verfügung, das die folgenden Funktionen bietet:

Klasse eyetracker

Eine generische Python-Bibliothek für Eye-Tracking.

Funktion eyetracker.calibrate()

Kalibriert das Eye-Tracking-System. Das tatsächliche Verhalten dieser Funktion hängt von der Art des Eye-Trackers ab und ist unten beschrieben.

EyeLink:

Diese Funktion aktiviert den Kamera-Setup-Bildschirm, der es ermöglicht, die Kamera einzustellen und ein Kalibrierungs-/Validierungsverfahren durchzuführen. Mit der Taste 'q' wird die Setup-Routine beendet. Das Drücken von "Entfernen" löst zunächst einen Bestätigungsdialog und dann, bei Bestätigung, eine Ausnahme aus.

EyeTribe:

Aktiviert eine einfache Kalibrierroutine.

Returns:

Gibt True zurück, wenn die Kalibrierung erfolgreich war, oder False, wenn nicht; zusätzlich wird ein Kalibrierungsprotokoll zur Protokolldatei hinzugefügt und einige Eigenschaften werden aktualisiert (z. B. die Schwellenwerte für die Erkennungsalgorithmen).

  • Typ: bool

Funktion eyetracker.close()

Schließt die Verbindung zum Tracker ordentlich. Speichert Daten und stellt self.connected auf False.

Funktion eyetracker.connected()

Überprüft, ob der Tracker verbunden ist.

Returns:

True, wenn die Verbindung hergestellt ist, False, wenn nicht; stellt self.connected auf denselben Wert.

  • Typ: bool

Funktion eyetracker.draw_calibration_target(x, y)

Zeichnet ein Kalibrierungsziel.

Arguments:

  • x -- Die X-Koordinate
    • Typ: int
  • y -- Die Y-Koordinate
    • Typ: int

Funktion eyetracker.draw_drift_correction_target(x, y)

Zeichnet ein Driftkorrekturziel.

Arguments:

  • x -- Die X-Koordinate
    • Typ: int
  • y -- Die Y-Koordinate
    • Typ: int

Funktion eyetracker.drift_correction(pos=None, fix_triggered=False)

Führt ein Driftkorrekturverfahren durch. Das genaue Verhalten dieser Funktion hängt von der Art des Eye-Trackers ab und ist unten beschrieben. Da die Driftkorrektur fehlschlagen kann, rufen Sie diese Funktion in der Regel in einer Schleife auf.

EyeLink:

Während der Driftkorrektur wird mit der Taste 'q' der Kamera-Setup-Bildschirm aktiviert. Von dort aus verursacht das Drücken von 'q' erneut das sofortige Scheitern der Driftkorrektur. Das Drücken von "Entfernen" bietet die Möglichkeit, das Experiment abzubrechen, in diesem Fall wird eine Ausnahme ausgelöst.

Keywords:

  • pos -- (x, y) Position des Fixationspunkts oder None für eine zentrale Fixation.
    • Typ: tuple, NoneType
    • Standard: None
  • fix_triggered -- Boolescher Wert, der angibt, ob die Driftüberprüfung auf der Blickposition (True) oder auf dem Spacepress (False) basieren soll.
    • Typ: bool
    • Standard: False

Returns:

Ein Boolescher Wert, der angibt, ob die Driftüberprüfung in Ordnung ist (True) oder nicht (False).

  • Typ: bool

Funktion eyetracker.fix_triggered_drift_correction(pos=None, min_samples=30, max_dev=60, reset_threshold=10)

Führt eine Fixationsauslösung der Driftkorrektur durch, indem eine bestimmte Anzahl von Proben gesammelt und die durchschnittliche Entfernung von der Fixationsposition berechnet wird

Keywords:

  • pos -- (x, y) Position des Fixationspunkts oder None für eine zentrale Fixation.
    • Typ: tuple, NoneType
    • Standard: None
  • min_samples -- Die minimale Anzahl an Proben, nach denen eine durchschnittliche Abweichung berechnet wird.
    • Typ: int
    • Standard: 30
  • max_dev -- Die maximale Abweichung von der Fixation in Pixeln.
    • Typ: int
    • Standard: 60
  • reset_threshold -- Wenn der horizontale oder vertikale Abstand in Pixeln zwischen zwei aufeinanderfolgenden Proben größer als diese Schwelle ist, wird die Probensammlung zurückgesetzt.
    • Typ: int
    • Standard: 10

Rückgabe:

Ein Boolean, der angibt, ob die Driftprüfung in Ordnung ist (Wahr) oder nicht (Falsch).

  • Typ: bool

Funktion eyetracker.get_eyetracker_clock_async()

Gibt die Differenz zwischen Tracker-Zeit und PyGaze-Zeit zurück, die zur Synchronisation des Timings verwendet werden kann

Rückgabe:

Die Differenz zwischen Eyetracker-Zeit und PyGaze-Zeit.

  • Typ: int, float

Funktion eyetracker.log(msg)

Schreibt eine Nachricht in die Protokolldatei.

Argumente:

  • msg -- Eine Nachricht.
    • Typ: str, unicode

Funktion eyetracker.log_var(var, val)

Schreibt den Namen und den Wert einer Variablen in die Protokolldatei

Argumente:

  • var -- Ein Variablenname.
    • Typ: str, unicode
  • val -- Ein Variablenwert

Funktion eyetracker.pupil_size()

Gibt die neueste Pupillengrößenprobe zurück; die Größe kann je nach Einrichtung als Durchmesser oder Fläche der Pupille gemessen werden (beachten Sie, dass die Pupillengröße meist in willkürlichen Einheiten angegeben wird).

Rückgabe:

Gibt die Pupillengröße für das Auge zurück, das derzeit verfolgt wird (wie von self.eye_used angegeben) oder -1, wenn keine Daten abrufbar sind.

  • Typ: int, float

Funktion eyetracker.sample()

Gibt die neueste verfügbare Blickposition zurück.

Rückgabe:

Ein (x, y) Tupel oder ein (-1, -1) bei einem Fehler.

  • Typ: tuple

Funktion eyetracker.send_command(cmd)

Sendet direkt einen Befehl an den Eyetracker (nicht für alle Marken unterstützt; kann eine Warnmeldung erzeugen, wenn Ihre Einrichtung direkte Befehle nicht unterstützt).

Argumente:

  • cmd -- Der Befehl, der an den Eyetracker gesendet werden soll.
    • Typ: str, unicode

Funktion eyetracker.set_detection_type(eventdetection)

Setzt den Ereigniserkennungstyp entweder auf PyGaze-Algorithmen oder native Algorithmen, wie sie vom Hersteller bereitgestellt werden (nur wenn verfügbar: Erkennungstyp wird auf PyGaze zurückgesetzt, wenn keine nativen Funktionen verfügbar sind)

Argumente:

  • eventdetection -- Ein String, der angibt, welcher Erkennungstyp verwendet werden soll: entweder 'pygaze' für PyGaze Ereigniserkennungsalgorithmen oder 'native' für Algorithmen der Hersteller (nur wenn verfügbar; wird auf 'pygaze' zurückgesetzt, wenn keine native Ereigniserkennung verfügbar ist)
    • Typ: str, unicode

Rückgabe:

Erkennungstyp für Sakkaden, Fixationen und Blinzeln in einem Tupel, z.B. ('pygaze','native','native'), wenn 'native' übergeben wurde, aber native Erkennung für Sakkaden nicht verfügbar war.

  • Typ: tuple

Funktion eyetracker.set_draw_calibration_target_func(func)

Gibt eine benutzerdefinierte Funktion zum Zeichnen des Kalibrierungsziels an. Diese Funktion ersetzt das Standard [draw_calibration_target].

Argumente:

  • func -- Die Funktion zum Zeichnen eines Kalibrierungsziels. Diese Funktion sollte zwei Parameter akzeptieren, für die x- und y-Koordinate des Ziels.
    • Typ: function

Funktion eyetracker.set_draw_drift_correction_target_func(func)

Gibt eine benutzerdefinierte Funktion zum Zeichnen des Driftkorrekturziels an. Diese Funktion ersetzt das Standard [draw_drift_correction_target].

Argumente:

  • func -- Die Funktion zum Zeichnen eines Driftkorrekturziels. Diese Funktion sollte zwei Parameter akzeptieren, für die x- und y-Koordinate des Ziels.
    • Typ: function

Funktion eyetracker.set_eye_used()

Protokolliert die eye_used Variable, basierend darauf, welches Auge angegeben wurde (wenn beide Augen verfolgt werden, wird das linke Auge verwendet). Gibt nichts zurück.

Funktion eyetracker.start_recording()

Beginnt die Aufnahme. Setzt self.recording auf True, wenn die Aufnahme erfolgreich gestartet wurde.

Funktion eyetracker.status_msg(msg)

Sendet eine Statusmeldung an den Eye-Tracker, die in der GUI des Trackers angezeigt wird (nur für EyeLink-Setups verfügbar).

Argumente:

  • msg -- Ein String, der auf dem Versuchsleiter-PC angezeigt wird, z.B.: "aktueller Versuch: %d" % trialnr.
    • Typ: str, unicode

Funktion eyetracker.stop_recording()

Stoppt die Aufnahme. Setzt self.recording auf False, wenn die Aufnahme erfolgreich gestoppt wurde.

Funktion eyetracker.wait_for_event(event)

Wartet auf ein Ereignis.

Argumente:

  • event -- Ein ganzzahliger Event-Code, einer der folgenden:

  • 3 = STARTBLINK

  • 4 = ENDBLINK
  • 5 = STARTSACC
  • 6 = ENDSACC
  • 7 = STARTFIX
  • 8 = ENDFIX
    • Typ: int

Rückgabe:

Je nach angegebenem Ereignis wird eine self.wait_for_* Methode aufgerufen; der Rückgabewert der entsprechenden Methode wird zurückgegeben.

Funktion eyetracker.wait_for_fixation_end()

Gibt Zeit und Blickposition zurück, wenn eine Fixierung beendet wurde; Funktion geht davon aus, dass eine 'Fixierung' beendet wurde, wenn eine Abweichung von mehr als self.pxfixtresh von der ursprünglichen Fixierungsposition erkannt wurde (self.pxfixtresh wird in self.calibration erstellt, basierend auf self.fixtresh, einer Eigenschaft, die in self.init definiert ist). Detektion basiert auf Dalmaijer et al. (2013), wenn EVENTDETECTION auf 'pygaze' gesetzt ist, oder mit nativen Detektionsfunktionen, wenn EVENTDETECTION auf 'native' gesetzt ist (HINWEIS: nicht jedes System hat native Funktionalität; wird auf ;pygaze' zurückgreifen, wenn 'native' nicht verfügbar ist!)

Rückgabe:

Ein time, gazepos Tupel. Time ist die Endzeit in Millisekunden (ab expstart), gazepos ist ein (x,y) Blickpositionstupel der Position, von der aus die Fixierung initiiert wurde.

  • Typ: Tupel

Funktion eyetracker.wait_for_fixation_start()

Gibt Startzeit und Position zurück, wenn eine Fixierung beginnt; Funktion geht davon aus, dass eine "Fixierung" beginnt, wenn die Blickposition weitgehend stabil bleibt (d.h. wenn die meisten abweichenden Proben innerhalb von self.pxfixtresh liegen) für fünf Proben hintereinander (self.pxfixtresh wird in self.calibration erstellt, basierend auf self.fixtresh, einer Eigenschaft definiert in self.init). Erkennung basiert auf Dalmaijer et al. (2013), wenn EVENTDETECTION auf 'pygaze' gesetzt ist, oder mit nativen Erkennungsfunktionen, wenn EVENTDETECTION auf 'native' gesetzt ist (HINWEIS: Nicht jedes System hat native Funktionalität; wird auf 'pygaze' zurückgreifen, wenn 'native' nicht verfügbar ist!)

Gibt zurück:

Ein time, gazepos Tupel. Die Zeit ist die Startzeit in Millisekunden (von expstart), gazepos ist ein (x,y) Blickpositionstupel der Position, von der die Fixierung initiiert wurde.

  • Typ: Tupel

Funktion eyetracker.wait_for_saccade_end()

Gibt Endzeit, Start- und Endposition zurück, wenn eine Sakkade endet; basiert auf Dalmaijer et al. (2013) Online-Sakkaden-Erkennungsalgorithmus, wenn EVENTDETECTION auf 'pygaze' gesetzt ist, oder mit nativen Erkennungsfunktionen, wenn EVENTDETECTION auf 'native' gesetzt ist (HINWEIS: Nicht jedes System hat native Funktionalität; wird auf 'pygaze' zurückgreifen, wenn 'native' nicht verfügbar ist!)

Gibt zurück:

Ein endtime, startpos, endpos Tupel. Endzeit in Millisekunden (von expbegintime); startpos und endpos sind (x,y) Blickpositionstupel.

  • Typ: Tupel

Funktion eyetracker.wait_for_saccade_start()

Gibt Startzeit und Startposition zurück, wenn eine Sakkade beginnt; basiert auf Dalmaijer et al. (2013) Online-Sakkaden-Erkennungsalgorithmus, wenn EVENTDETECTION auf 'pygaze' gesetzt ist, oder mit nativen Erkennungsfunktionen, wenn EVENTDETECTION auf 'native' gesetzt ist (HINWEIS: Nicht jedes System hat native Funktionalität; wird auf 'pygaze' zurückgreifen, wenn 'native' nicht verfügbar ist!)

Gibt zurück:

Ein endtime, startpos Tupel. Endzeit in Millisekunden (von expbegintime); startpos ist ein (x,y) Blickpositionstupel.

  • Typ: Tupel
Supported by
Sebastiaan Mathôt » Copyright 2010 — 2024 » License information