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

PyGaze (suivi du regard)

À propos

PyGaze est une bibliothèque Python pour l'eye tracking. Un ensemble de plugins vous permet d'utiliser PyGaze au sein d'OpenSesame. Pour plus d'informations sur PyGaze, visitez :

Veuillez citer PyGaze comme suit :

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

Eye trackers pris en charge

PyGaze prend en charge les eye trackers suivants:

Pour les eye trackers suivants, il y a un support expérimental :

Vous pouvez également effectuer un eye tracking basique dans des expériences en ligne avec WebGazer.js :

PyGaze inclut également deux eye trackers fictifs pour les tests :

  • Simple dummy — Ne fait rien.
  • Dummy avancé — Simulation de mouvements oculaires avec la souris.

Installation de PyGaze

Windows

Si vous utilisez le package officiel Windows d'OpenSesame, PyGaze est déjà installé.

Ubuntu

Si vous utilisez Ubuntu, vous pouvez obtenir PyGaze à partir du PPA Cogsci.nl :

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

Ou, si vous utilisez Python 3, changez la dernière commande pour :

sudo apt-get install python3-pygaze

Installation avec pip (toutes les plates-formes)

Vous pouvez installer PyGaze avec pip :

pip install python-pygaze

Anaconda (toutes les plates-formes)

conda install python-pygaze -c cogsci

Plugins PyGaze OpenSesame

Les plugins PyGaze suivants sont disponibles :

  • pygaze_init — Initialise PyGaze. Ce plugin est généralement inséré au début de l'expérience.
  • pygaze_drift_correct — Implémente une procédure de correction de dérive.
  • pygaze_start_recording — Met PyGaze en mode enregistrement.
  • pygaze_stop_recording — Sort PyGaze du mode enregistrement.
  • pygaze_wait — Met en pause jusqu'à ce qu'un événement se produise, comme le début d'une saccade.
  • pygaze_log — Enregistre des variables expérimentales et du texte arbitraire.

Exemple

Pour un exemple d'utilisation des plugins PyGaze, consultez le modèle PyGaze inclus avec OpenSesame.

Ci-dessous un exemple d'utilisation de PyGaze dans un inline_script Python :

# Créez un clavier et un objet toile
my_keyboard = Keyboard(timeout=0)
my_canvas = Canvas()
my_canvas['dot'] = Circle(x=0, y=0, r=10, fill=True)
# Boucle ...
while True:
    # ... jusqu'à ce que l'espace soit pressé
    key, timestamp = my_keyboard.get_key()
    if key == 'space':
        break
    # Obtenez la position du regard à partir de pygaze ...
    x, y = eyetracker.sample()
    # ... et dessinez un point de fixation dépendant du regard !
    my_canvas['dot'].x = x + my_canvas.left
    my_canvas['dot'].y = y + my_canvas.top
    my_canvas.show()

Aperçu des fonctions

Pour initialiser PyGaze dans OpenSesame, insérez le plugin pygaze_init dans votre expérience. Une fois que vous avez fait cela, un objet eyetracker sera disponible, qui offre les fonctions suivantes :

classe eyetracker

Une bibliothèque Python générique pour le suivi du regard.

fonction eyetracker.calibrate()

Calibre le système de suivi du regard. Le comportement réel de cette fonction dépend du type de suivi du regard et est décrit ci-dessous.

EyeLink:

Cette fonction active l'écran de configuration de la caméra, qui permet d'ajuster la caméra et d'effectuer une procédure de calibration/validation. Appuyer sur 'q' quittera la routine de configuration. Appuyer sur 'échap' déclenchera d'abord une boîte de dialogue de confirmation, puis, après confirmation, lève une exception.

EyeTribe:

Active une routine de calibration simple.

Retourne:

Renvoie Vrai si la calibration a réussi, ou Faux si ce n'est pas le cas; en plus, un journal de calibration est ajouté au fichier journal et certaines propriétés sont mises à jour (c'est-à-dire les seuils pour la détection algorithmes).

  • Type : bool

fonction eyetracker.close()

Ferme soigneusement la connexion au tracker. Sauvegarde les données et définit self.connected à Faux.

function eyetracker.connected()

Vérifie si le suivi est connecté.

Retourne:

Vrai si la connexion est établie, Faux si ce n'est pas le cas; définit self.connected à la même valeur.

  • Type : bool

function eyetracker.draw_calibration_target(x, y)

Dessine une cible de calibration.

Arguments:

  • x -- La coordonnée X
    • Type : int
  • y -- La coordonnée Y
    • Type : int

function eyetracker.draw_drift_correction_target(x, y)

Dessine une cible de correction de dérive.

Arguments:

  • x -- La coordonnée X
    • Type : int
  • y -- La coordonnée Y
    • Type : int

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

Effectue une procédure de correction de dérive. Le comportement exact de cette fonction dépend du type de suivi du regard et est décrit ci-dessous. Parce que la correction de dérive peut échouer, vous appellerez généralement cette fonction dans une boucle.

EyeLink:

Appuyer sur 'q' pendant la correction de dérive activera l'écran de configuration de la caméra. À partir de là, appuyer sur 'q' à nouveau entraînera l'échec immédiat de la correction de dérive. Appuyer sur 'échap' donnera la possibilité d'interrompre l'expérience, auquel cas une exception est levée.

Mots-clés:

  • pos -- Position (x, y) du point de fixation ou None pour une fixation centrale.
    • Type : tuple, NoneType
    • Par défaut : None
  • fix_triggered -- Booléen indiquant si la vérification de la dérive doit être effectuée en fonction de la position du regard (Vrai) ou sur l'espace pressé (Faux).
    • Type : bool
    • Par défaut : Faux

Retourne:

Un booléen indiquant si la vérification de la dérive est correcte (Vrai) ou non (Faux).

  • Type : bool

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

Effectue une correction de dérive déclenchée par la fixation en collectant un certain nombre d'échantillons et en calculant la distance moyenne par rapport à la position de fixation

Mots-clés:

  • pos -- Position (x, y) du point de fixation ou None pour une fixation centrale.
    • Type : tuple, NoneType
    • Par défaut : None
  • min_samples -- Le nombre minimal d'échantillons après lequel une déviation moyenne est calculée.
    • Type : int
    • Par défaut : 30
  • max_dev -- La déviation maximale par rapport à la fixation en pixels.
    • Type : int
    • Par défaut : 60
  • reset_threshold -- Si la distance horizontale ou verticale en pixels entre deux échantillons consécutifs est supérieure à ce seuil, la collecte d'échantillons est réinitialisée.
    • Type : int
    • Par défaut : 10

Renvoie :

Un booléen indiquant si la vérification de dérive est correcte (True) ou non (False).

  • Type : bool

fonction eyetracker.get_eyetracker_clock_async()

Renvoie la différence entre l'heure du suiveur et l'heure de PyGaze, qui peut être utilisée pour synchroniser le temps

Renvoie :

La différence entre l'heure du suiveur de regard et l'heure de PyGaze.

  • Type : int, float

fonction eyetracker.log(msg)

Écrit un message dans le fichier de journal.

Arguments :

  • msg -- Un message.
    • Type : str, unicode

fonction eyetracker.log_var(var, val)

Écrit le nom et la valeur d'une variable dans le fichier de journal

Arguments :

  • var -- Un nom de variable.
    • Type : str, unicode
  • val -- Une valeur de variable

fonction eyetracker.pupil_size()

Renvoie la taille de la pupille la plus récente ; la taille peut être mesurée comme le diamètre ou la surface de la pupille, selon votre configuration (notez que la taille de la pupille est généralement donnée en unités arbitraires).

Renvoie :

Renvoie la taille de la pupille pour l'œil qui est actuellement suivi (tel que spécifié par self.eye_used) ou -1 lorsque aucune donnée n'est obtenable.

  • Type : int, float

fonction eyetracker.sample()

Renvoie la position du regard la plus récente disponible.

Renvoie :

Un tuple (x, y) ou un (-1, -1) en cas d'erreur.

  • Type : tuple

fonction eyetracker.send_command(cmd)

Envoie directement une commande au suiveur de regard (non pris en charge pour toutes les marques ; peut produire un message d'avertissement si votre configuration ne prend pas en charge les commandes directes).

Arguments :

  • cmd -- La commande à envoyer au suiveur de regard.
    • Type : str, unicode

fonction eyetracker.set_detection_type(eventdetection)

Définit le type de détection des événements sur les algorithmes PyGaze, ou les algorithmes natifs fournis par le fabricant (seulement si disponible : le type de détection sera par défaut PyGaze si aucune fonction native n'est disponible)

Arguments :

  • eventdetection -- Une chaîne indiquant quel type de détection doit être utilisé : soit 'pygaze' pour les algorithmes de détection d'événements PyGaze ou 'native' pour les algorithmes du fabricant (seulement si disponible ; par défaut à 'pygaze' si aucune détection d'événements native n'est disponible)
    • Type : str, unicode

Renvoie :

Type de détection pour les saccades, les fixations et les clignotements dans un tuple, par exemple ('pygaze','native','native') lorsque 'native' a été passé, mais la détection native n'était pas disponible pour la détection de saccade.

  • Type : tuple

fonction eyetracker.set_draw_calibration_target_func(func)

Spécifie une fonction personnalisée pour dessiner la cible de calibration. Cette fonction remplacera la fonction par défaut [draw_calibration_target].

Arguments :

  • func -- La fonction pour dessiner une cible de calibration. Cette fonction doit accepter deux paramètres, pour les coordonnées x et y de la cible.
    • Type : fonction

fonction eyetracker.set_draw_drift_correction_target_func(func)

Spécifie une fonction personnalisée pour dessiner la cible de correction de dérive. Cette fonction remplacera la fonction par défaut [draw_drift_correction_target].

Arguments :

  • func -- La fonction pour dessiner une cible de correction de dérive. Cette fonction doit accepter deux paramètres, pour les coordonnées x et y de la cible.
    • Type : fonction

fonction eyetracker.set_eye_used()

Enregistre la variable eye_used, selon l'œil spécifié (si les deux yeux sont suivis, l'œil gauche est utilisé). Ne retourne rien.

fonction eyetracker.start_recording()

Démarre l'enregistrement. Définit self.recording sur True lorsque l'enregistrement est démarré avec succès.

fonction eyetracker.status_msg(msg)

Envoie un message d'état à l'eye tracker, qui est affiché dans l'interface graphique du traceur (uniquement disponible pour les configurations EyeLink).

Arguments :

  • msg -- Une chaîne de caractères à afficher sur le PC de l'expérimentateur, par exemple : "essai en cours : %d" % trialnr.
  • Type : str, unicode

fonction eyetracker.stop_recording()

Arrête l'enregistrement. Définit self.recording sur False lorsque l'enregistrement est arrêté avec succès.

fonction eyetracker.wait_for_event(event)

Attend un événement.

Arguments :

  • event -- Un code d'événement entier, l'un des suivants :

  • 3 = STARTBLINK

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

Renvoie :

Une méthode self.wait_for_* est appelée, en fonction de l'événement spécifié ; la valeur de retour de la méthode correspondante est renvoyée.

fonction eyetracker.wait_for_fixation_end()

Renvoie le temps et la position du regard lorsqu'une fixation s'est terminée ; la fonction suppose qu'une "fixation" est terminée lorsqu'un écart de plus de self.pxfixtresh par rapport à la position de fixation initiale a été détecté (self.pxfixtresh est créé dans la calibration de soi-même, basée sur self.fixtresh, une propriété définie dans self.init). Détection basée sur Dalmaijer et al. (2013) si EVENTDETECTION est défini sur 'pygaze', ou à l'aide de fonctions de détection natives si EVENTDETECTION est défini sur 'native' (NOTE : tous les systèmes n'ont pas de fonctionnalité native ; retournera à ;pygaze' si 'native' n'est pas disponible !)

Renvoie :

Un tuple time, gazepos. Le temps est le temps de fin en millisecondes (depuis le début de l'expérience), gazepos est un tuple de position du regard (x,y) de la position à partir de laquelle la fixation a été initiée.

  • Type : tuple

fonction eyetracker.wait_for_fixation_start()

Renvoie l'heure de début et la position lorsqu'une fixation est commencée ; la fonction suppose qu'une "fixation" a commencé lorsque la position du regard reste raisonnablement stable (c'est-à-dire lorsque la plupart des échantillons déviants sont à l'intérieur de self.pxfixtresh) pendant cinq échantillons d'affilée (self.pxfixtresh est créé dans self.calibration, basé sur self.fixtresh, une propriété définie dans self.init). Détection basée sur Dalmaijer et al. (2013) si EVENTDETECTION est défini à 'pygaze', ou en utilisant des fonctions de détection natives si EVENTDETECTION est défini sur 'native' (NOTE : tous les systèmes n'ont pas de fonctionnalité native ; retournera à 'pygaze' si 'native' n'est pas disponible!)

Renvoie :

Un tuple time, gazepos. Time est l'heure de début en millisecondes (à partir de expstart), gazepos est un tuple de position (x,y) du regard à partir duquel la fixation a été initiée.

  • Type: tuple

fonction eyetracker.wait_for_saccade_end()

Renvoie l'heure de fin, la position de départ et la position de fin lorsqu'une saccade est terminée ; basée sur l'algorithme de détection de saccades en ligne de Dalmaijer et al. (2013) si EVENTDETECTION est défini à 'pygaze', ou en utilisant des fonctions de détection natives si EVENTDETECTION est défini sur 'native' (NOTE: pas tous les systèmes ont une fonctionnalité native ; retournera à 'pygaze' si 'native' n'est pas disponible !)

Renvoie :

Un tuple endtime, startpos, endpos. Endtime en millisecondes (à partir de expbegintime) ; startpos et endpos sont des tuples de position (x,y) du regard.

  • Type: tuple

fonction eyetracker.wait_for_saccade_start()

Renvoie l'heure de début et la position de départ lorsqu'une saccade est commencée ; basée sur l'algorithme de détection de saccades en ligne de Dalmaijer et al. (2013) si EVENTDETECTION est défini à 'pygaze', ou en utilisant des fonctions de détection natives si EVENTDETECTION est défini sur 'native' (NOTE: pas tous les systèmes ont une fonctionnalité native ; retournera à 'pygaze' si 'native' n'est pas disponible !)

Renvoie :

Un tuple endtime, startpos. Endtime en millisecondes (à partir de expbegintime) ; startpos est un tuple de position (x,y) du regard.

  • Type: tuple
Supported by
Sebastiaan Mathôt » Copyright 2010 — 2024 » License information