wpl::Experiment Class Reference

Implements an experiment flow for Judd et al. (2009) Judd2009. More...

#include "where_people_look/experiment.h"

Public Member Functions
	Experiment (GtkImage *const image, Config *const config)
Config *	get_config ()
Experiment usage
void	prepare ()
void	start ()
You should not call this manually.
Todo: shoeffner: Maybe this should become private?
bool	trial ()

Static Public Member Functions
static gboolean	experiment_calibrate (gpointer experiment)
static gboolean	experiment_trial (gpointer experiment)
static gboolean	experiment_quit_program (gpointer experiment)
static bool	experiment_prepare (const GtkWidget *const assistant, Experiment *const experiment)
static bool	experiment_start (const GtkWidget *const window, const GdkEventKey *const event_key, Experiment *const experiment)

Detailed Description

Implements an experiment flow for Judd et al. (2009) Judd2009.

The data acquisition experiment can be prepared, started, quitted, and is divided into trials.

Using this class

The experiment should first be prepared (prepare()), then started (start()). After that, it will go through each available trial, recalibrate every 50 trials, and stop after all trials are done.

Each trial lasts three seconds and there are pauses of one second between the trials, during which a gray screen is shown.

Before the first and after the last trial there is another two seconds break.

Note

Many static functions are just created to allow G_CALLBACK to call them with appropriate Experiment instances. For example, Experiment::experiment_trial calls trial() on the provided experiment. However, some do extra checking: Experiment::experiment_start will only start the experiment if the space key was pressed and the experiment is not yet running.

Definition at line 45 of file experiment.h.

Constructor & Destructor Documentation

wpl::Experiment::Experiment	(	GtkImage *const	image,
		Config *const	config
	)

Constructs an experiment.

Parameters

image	The GtkImage* to be updated for each trial.
config	The configuration. It is used to find the stimuli.

Definition at line 48 of file experiment.cpp.

    : config(config),
      gaze_tracker(new gaze::GazeTracker()),
      image(image) {
}

Member Function Documentation

gboolean wpl::Experiment::experiment_calibrate ( gpointer  experiment )

static

Calibrates the GazeTracker of the specified experiment.

Parameters

experiment

Must be a gpointer to an Experiment.

Returns

false

Definition at line 104 of file experiment.cpp.

Referenced by trial().

                                                             {
  Experiment* exp = static_cast<Experiment*>(experiment);
  exp->is_calibrating = false;
  exp->gaze_tracker->calibrate();
  return false;
}

bool wpl::Experiment::experiment_prepare ( const GtkWidget *const  assistant, Experiment *const  experiment  )

static

Calls prepare() on the given experiment.

Parameters

assistant	This widget is ignored but needed to bind the G_CALLBACK properly.
experiment	Must be a gpointer to an Experiment.

Returns

false

Definition at line 123 of file experiment.cpp.

References prepare().

                                                                  {
  experiment->prepare();
  return false;
}

gboolean wpl::Experiment::experiment_quit_program ( gpointer  experiment )

static

Gets the ancestor window of the experiment's image (see Experiment(GtkImage*,Config*)) and issues a destroy signal.

Parameters

experiment

Must be a gpointer to an Experiment.

Returns

false

Definition at line 111 of file experiment.cpp.

Referenced by trial().

                                                                {
  Experiment* exp = static_cast<Experiment*>(experiment);
  GtkWidget* window = gtk_widget_get_ancestor(GTK_WIDGET(exp->image),
      GTK_TYPE_WINDOW);
  g_signal_emit_by_name(window, "destroy");
  return false;
}

bool wpl::Experiment::experiment_start ( const GtkWidget *const  window, const GdkEventKey *const  event_key, Experiment *const  experiment  )

static

Calls start() on the given experiment if the space key is event_key's keyval and the experiment is not started.

Parameters

window	This widget is ignored but needed to bind the G_CALLBACK properly.
event_key	The event key to process.
experiment	Must be a gpointer to an Experiment.

Returns

false

Definition at line 129 of file experiment.cpp.

References start().

                                                                {
  if (event_key->keyval == GDK_KEY_space) {
    if (!experiment->is_started) {
      experiment->start();
    }
  }
  return false;
}

gboolean wpl::Experiment::experiment_trial ( gpointer  experiment )

static

Calls trial() on the given experiment.

Parameters

experiment

Must be a gpointer to an Experiment.

Returns

false

Definition at line 119 of file experiment.cpp.

References trial().

Referenced by start(), and trial().

                                                         {
  return static_cast<Experiment*>(experiment)->trial();
}

Config * wpl::Experiment::get_config

(

)

Returns

a pointer to this experiment's config.

Definition at line 57 of file experiment.cpp.

                               {
  return this->config;
}

void wpl::Experiment::prepare

(

)

Prepares the experiment.

Preparations performed are

• GazeTracker initialization
• Stimuli list generation

Definition at line 61 of file experiment.cpp.

References lock().

Referenced by experiment_prepare().

                         {
  std::lock_guard<std::mutex> lock(this->mutex);
  if (this->is_prepared) {
    return;
  }
  this->init_gaze_tracker();
  this->read_stimuli_list();
  this->is_prepared = true;
}

void wpl::Experiment::start

(

)

Starts the experiment. After a warmup time, the first trial starts.

If this function is called on a started experiment, it simply returns.

Definition at line 71 of file experiment.cpp.

References experiment_trial(), and lock().

Referenced by experiment_start().

                       {
  std::lock_guard<std::mutex> lock(this->mutex);
  if (this->is_started) {
    return;
  }
  g_timeout_add(this->warmup, Experiment::experiment_trial, this);
  this->is_started = true;
}

bool wpl::Experiment::trial

(

)

Handles trials.

This function should not be called manually.

If a calibration is needed (because of the 50-trials-then-recalibrate setting), this calls the calibration function and polls itself every 500 millisecondss to try to continue the experiment with the next trial.

If a calibration is already (or still) in progress, this simply returns true to trigger another test.

If there are no trials left, this issues a program quit after two seconds.

Only if no calibration needs to be done or is in progress, and there are still trials left, an actual trial is started: A stimulus is presented for three seconds, followed by a one second pause. This trial function issues a new trial to be performed afterwards and returns false to not poll itself again.

Returns

true for retries during calibration, false otherwise.

Definition at line 80 of file experiment.cpp.

References experiment_calibrate(), experiment_quit_program(), experiment_trial(), and lock().

Referenced by experiment_trial().

                       {
  std::lock_guard<std::mutex> lock(this->mutex);
  if (this->is_calibrating) {
    return true;
  }
  if (this->calibration_countdown-- == 0) {
    this->is_calibrating = true;
    this->calibration_countdown = this->calibration_after;
    g_timeout_add(0, Experiment::experiment_calibrate, this);
    g_timeout_add(500, Experiment::experiment_trial, this);
  } else {
    if (!this->trials.empty()) {
      g_timeout_add(0, Experiment::experiment_start_trial, this);
      g_timeout_add(this->trial_duration, Experiment::experiment_stop_trial,
          this);
      g_timeout_add(this->trial_duration + this->pause_duration,
          Experiment::experiment_trial, this);
    } else {
      g_timeout_add(this->cooldown, Experiment::experiment_quit_program, this);
    }
  }
  return false;
}

---

The documentation for this class was generated from the following files:

• include/where_people_look/experiment.h
• src/demo/where_people_look/experiment.cpp