pyForceDAQ 2.0.0__py3-none-any.whl

pyforcedaq/force/sensor_process.py

@@ -0,0 +1,251 @@
+__author__ = 'Oliver Lindemann'
+
+import atexit
+import ctypes as ct
+import logging
+from multiprocessing import Event, Pipe, Process, sharedctypes
+
+from .._lib import lsl, timer
+from .._lib.polling_time_profile import PollingTimeProfile
+from .._lib.process_priority_manager import get_priority
+from .._lib.types import DAQEvents
+from .sensor import Sensor, SensorSettings
+
+
+class SensorProcess(Process):
+
+    def __init__(self, settings, pipe_buffered_data_after_pause=True,
+                  chunk_size=10000):
+        """ForceSensorProcess
+
+        return_buffered_data_after_pause: does not write shared data queue continuously and
+            writes it the buffer data to queue only after pause (or stop)
+
+        """
+
+        # DOC explain usage
+
+        # type checks
+        if not isinstance(settings, SensorSettings):
+            raise RuntimeError(
+                "settings has to be force_sensor.Settings object")
+
+        super(SensorProcess, self).__init__()
+        self.sensor_settings = settings
+        self._pipe_buffer_after_pause = pipe_buffered_data_after_pause
+        self._chunk_size = chunk_size
+
+        self._pipe_i, self._pipe_o = Pipe()
+        self._event_is_polling = Event()
+        self._event_sending_data = Event()
+        self._event_new_data = Event()
+        self.event_bias_is_available = Event()
+        self.event_trigger = Event()  #  software trigger
+
+        self._last_Fx = sharedctypes.RawValue(ct.c_float)
+        self._last_Fy = sharedctypes.RawValue(ct.c_float)
+        self._last_Fz = sharedctypes.RawValue(ct.c_float)
+        self._last_Tx = sharedctypes.RawValue(ct.c_float)
+        self._last_Ty = sharedctypes.RawValue(ct.c_float)
+        self._last_Tz = sharedctypes.RawValue(ct.c_float)
+        self._buffer_size = sharedctypes.RawValue(ct.c_uint64)
+        self._sample_cnt = sharedctypes.Value(ct.c_uint64)
+        self._event_quit_request = Event()
+        self._determine_bias_flag = Event()
+
+        self._bias_n_samples = 200
+        atexit.register(self.join)
+
+    @property
+    def Fx(self):
+        return self._last_Fx.value
+
+    @property
+    def Fy(self):
+        return self._last_Fy.value
+
+    @property
+    def Fz(self):
+        return self._last_Fz.value
+
+    @property
+    def Tx(self):
+        return self._last_Tx.value
+
+    @property
+    def Ty(self):
+        return self._last_Ty.value
+
+    @property
+    def Tz(self):
+        return self._last_Tz.value
+
+    def get_force(self, parameter_id):
+        if   parameter_id == 0: return self._last_Fx.value
+        elif parameter_id == 1: return self._last_Fy.value
+        elif parameter_id == 2: return self._last_Fz.value
+        elif parameter_id == 3: return self._last_Tx.value
+        elif parameter_id == 4: return self._last_Ty.value
+        elif parameter_id == 5: return self._last_Tz.value
+        else: return None
+
+    def get_Fxyz(self):
+        return (self._last_Fx.value, self._last_Fy.value, self._last_Fz.value)
+
+    def Txyz(self):
+        return (self._last_Tx.value, self._last_Ty.value, self._last_Tz.value)
+
+    def get_sample_cnt(self):
+        return int(self._sample_cnt.value)
+
+    def get_buffer_size(self):
+        return int(self._buffer_size.value)
+
+    def determine_bias(self, n_samples=100):
+        """recording is paused after bias determination
+
+        Bias determination is only possible while pause.
+        This process might take a while. Please use "wait_bias_available" to
+        ensure that the process is finished and the sensor is again read for
+        recording.
+        """
+
+        if not self._event_is_polling.is_set():
+            self._bias_n_samples = n_samples
+            self.event_bias_is_available.clear()
+            self._determine_bias_flag.set()
+
+    def start_polling(self):
+        self._event_is_polling.set()
+
+    def pause_polling(self):
+        self._event_is_polling.clear()
+
+    def get_buffer(self, timeout=1.0):
+        """return recorded buffer"""
+        rtn = []
+        if self._event_sending_data.is_set() or self._buffer_size.value > 0:
+            self._event_sending_data.wait()
+            while self._buffer_size.value > 0:  # wait until buffer is empty
+                rtn.extend(self._pipe_i.recv())
+            self._event_sending_data.clear() # stop sending
+        return rtn
+
+    def join(self, timeout=None):
+
+        if self._event_is_polling.is_set():
+            self.pause_polling()
+            timer.wait(100)
+            self.get_buffer() # empty buffer, required to quit process run loop
+
+        self._event_quit_request.set()
+        super(SensorProcess, self).join(timeout)
+
+
+    def run(self):
+        buffer = []
+        self._buffer_size.value = 0
+        sensor = Sensor(self.sensor_settings)
+        stream_forces = self.sensor_settings.array_write_forces()
+        stream_trigger = self.sensor_settings.array_write_trigger()
+
+        self._event_is_polling.clear()
+        self._event_sending_data.clear()
+        is_polling = False
+        ptp = PollingTimeProfile() #TODO just for testing?
+
+        ## create init LSL
+        lsl_data_steam = None
+        lsl_hardware_trigger_stream = None
+        if self.sensor_settings.has_lsl_stream:
+            lsl_data_steam = lsl.init(
+                    name=f"Force {self.sensor_settings.device_name}",
+                    n_channels=sum(stream_forces),
+                    stream_id=f"RF_{self.sensor_settings.device_name}",
+                    freq=self.sensor_settings.rate,
+                    metadata={"sensor_name": self.sensor_settings.sensor_name})
+            n_hardware_trigger = sum(stream_trigger)
+            if n_hardware_trigger > 0:
+                lsl_hardware_trigger_stream = lsl.init(
+                    name=f"Trigger {self.sensor_settings.device_name}",
+                    n_channels=n_hardware_trigger,
+                    stream_id=f"Tr_{self.sensor_settings.device_name}",
+                    freq=self.sensor_settings.rate)
+
+
+        while not self._event_quit_request.is_set():
+            if self._event_is_polling.is_set():
+                # is polling
+                if not is_polling:
+                    # start NI device and acquire one first sample to
+                    # ensure good timing
+                    sensor.start_data_acquisition()
+                    buffer.append(DAQEvents(time=sensor.timer.time,
+                                            code="started:"+repr(sensor.device_id)))
+                    logging.info("Sensor start, name %s, pid %s, priority %s",
+                        sensor.name,self.pid, get_priority(self.pid))
+                    is_polling = True
+
+                d = sensor.poll_data()
+                ## LSL
+                if lsl_data_steam is not None:
+                    lsl_data_steam.push_sample(list(d.selected_forces(stream_forces))) # steam only select forces
+                if lsl_hardware_trigger_stream is not None:
+                    lsl_hardware_trigger_stream.push_sample(list(d.selected_trigger(stream_trigger))) # stream only triggers
+
+                ptp.update(d.time) # needed? TODO
+                self._last_Fx.value, self._last_Fy.value, self._last_Fz.value, \
+				                     self._last_Tx.value, self._last_Ty.value, \
+                                     self._last_Tz.value = d.forces
+                self._sample_cnt.value += 1
+
+                if self.event_trigger.is_set():
+                    self.event_trigger.clear()
+                    d.trigger[0] = 1
+
+                buffer.append(d)
+                self._buffer_size.value = len(buffer)
+
+            else:
+                # pause: not polling
+                if is_polling:
+                    sensor.stop_data_acquisition()
+                    buffer.append(DAQEvents(time=sensor.timer.time,
+                                            code="pause:"+repr(sensor.device_id)))
+                    self._buffer_size.value = len(buffer)
+                    logging.info(
+                        "Sensor stop, name %s, pid %s, priority %s",
+                        sensor.name,
+                        self.pid,
+                        get_priority(self.pid),
+                    )
+                    is_polling = False
+                    ptp.stop()
+
+                if self._pipe_buffer_after_pause and self._buffer_size.value>0:
+                    # sending data to force
+                    self._event_sending_data.set()
+                    chks = self._chunk_size
+                    while len(buffer)>0:
+                        if chks > len(buffer):
+                            chks = len(buffer)
+                        self._pipe_o.send(buffer[0:chks])
+                        buffer[0:chks] = [] # clear buffer
+                        self._buffer_size.value = len(buffer)
+
+                    while self._event_sending_data.is_set():
+                        timer.wait(2)
+
+                if self._determine_bias_flag.is_set():
+                    sensor.determine_bias(n_samples=self._bias_n_samples)
+                    self._determine_bias_flag.clear()
+                    self.event_bias_is_available.set()
+
+                self._event_is_polling.wait(timeout=0.1)
+
+
+        # stop process
+        sensor.stop_data_acquisition()
+        self._buffer_size.value = 0
+
+        logging.info("Sensor quit, %s, %s", sensor.name, ptp.get_profile_str())

pyforcedaq/gui/__init__.py

@@ -0,0 +1,6 @@
+from ._run import (
+    run,
+    run_with_options,  # for running with options from Python script
+)
+from ._settings import settings  ## read settings
+

pyforcedaq/gui/_gui_status.py

@@ -0,0 +1,306 @@
+__author__ = "Oliver Lindemann"
+
+from pickle import dumps, loads
+
+from expyriment import io, misc
+
+from .. import __version__ as forceDAQVersion
+from .._lib.misc import SensorHistory
+from .._lib.types import ForceSensorData, Thresholds
+from .._lib.types import GUIRemoteControlCommands as RcCmd
+from ..force.sensor_process import SensorProcess
+from ._layout import RecordingScreen, logo_text_line
+from ._scaling import Scaling
+from ._settings import settings
+
+
+def _text2number_array(txt):
+    """helper function"""
+    rtn = []
+    try:
+        for x in txt.split(","):
+            rtn.append(float(x))
+        return rtn
+    except:
+        return None
+
+class GUIStatus(object):
+
+    def __init__(self,
+                 screen_refresh_interval_indicator,
+                 screen_refresh_interval_plotter,
+                 recorder,
+                 remote_control,
+                 level_detection_parameter,
+                 data_min_max,
+                 plotter_pixel_min_max,
+                 indicator_pixel_min_max,
+                 screen_size,
+                 plot_axis):
+
+        self.screen_refresh_interval_indicator = screen_refresh_interval_indicator
+        self.screen_refresh_interval_plotter = screen_refresh_interval_plotter
+        self.plot_axis = plot_axis
+        self.recorder = recorder
+        self.remote_control = remote_control
+        self.level_detection_parameter = level_detection_parameter
+
+        self.background = RecordingScreen(window_size = screen_size,
+                                          filename=recorder.filename,
+                                          remote_control=remote_control)
+        self.scaling_plotter = Scaling(min=data_min_max[0], max= data_min_max[1],
+                      pixel_min=plotter_pixel_min_max[0],
+                      pixel_max=plotter_pixel_min_max[1])
+        self.scaling_indicator = Scaling(min=data_min_max[0], max= data_min_max[1],
+                                pixel_min = indicator_pixel_min_max[0],
+                                pixel_max = indicator_pixel_min_max[1])
+
+
+        self.sensor_processes = recorder.force_sensor_processes
+        self.n_sensors = len(self.sensor_processes)
+        self.history = []
+        for _ in range(self.n_sensors):
+            self.history.append( SensorHistory(history_size = settings.gui.moving_average_size,
+                                               number_of_parameter= 3) )
+
+        self._start_recording_time = 0
+        self.pause_recording = True
+        self.quit_recording = False
+        self.clear_screen = True
+        self.thresholds = None
+        self.set_marker = False
+        self.last_udp_data = None
+        self._last_processed_smpl = [0] * self.n_sensors
+        self._last_recording_status = None
+        self._last_thresholds = None
+        self._clock = misc.Clock()
+
+        self.sensor_info_str = ""
+        for tmp in self.recorder.sensor_settings_list:
+            self.sensor_info_str = self.sensor_info_str + \
+                                   "{0}: {1}\n".format(tmp.device_name, tmp.sensor_name)
+        self.sensor_info_str = self.sensor_info_str.strip()
+        self.plot_indicator = True
+        self.plot_filtered = False
+        if self.n_sensors == 1:
+            self.plot_data_indicator = settings.gui.plot_data_indicator_for_single_sensor
+            self.plot_data_plotter = settings.gui.plot_data_plotter_for_single_sensor
+        else:
+            self.plot_data_indicator = settings.gui.plot_data_indicator_for_two_sensors
+            self.plot_data_plotter = settings.gui.plot_data_plotter_for_two_sensors
+        # plot data parameter names
+        self.plot_data_indicator_names = []
+        for x in self.plot_data_indicator:
+            self.plot_data_indicator_names.append(self.recorder.sensor_settings_list[x[0]].device_name +\
+                                                  "_" + ForceSensorData.forces_names[ x[1]])
+
+
+        self.plot_data_plotter_names = []
+        for x in self.plot_data_plotter:
+            self.plot_data_plotter_names.append(str(x[0]) + "_" + ForceSensorData.forces_names[ x[1]])
+
+
+    def set_start_recording_time(self):
+        self._start_recording_time = self._clock.time
+
+    @property
+    def recording_duration_in_sec(self):
+        return (self._clock.time - self._start_recording_time) / 1000
+
+    def check_refresh_required(self):
+        """also resets clock"""
+        if self.plot_indicator:
+            intervall = self.screen_refresh_interval_indicator
+        else:
+            intervall = self.screen_refresh_interval_plotter
+
+        if not self.pause_recording and self._clock.stopwatch_time >= intervall:
+            self._clock.reset_stopwatch()
+            return True
+        return False
+
+    def check_recording_status_change(self):
+        """returns only onces true if not changed between calls"""
+        if self.pause_recording != self._last_recording_status:
+            self._last_recording_status = self.pause_recording
+            return True
+        return False
+
+    def check_new_samples(self):
+        """returns list of sensors with new samples"""
+        rtn = []
+        for i,  cnt in enumerate(map(SensorProcess.get_sample_cnt, self.sensor_processes)):
+            if self._last_processed_smpl[i] < cnt:
+                # new sample
+                self._last_processed_smpl[i] = cnt
+                rtn.append(i)
+        return rtn
+
+    def check_thresholds_changed(self):
+        """returns only true if not changed between calls"""
+        if self.thresholds != self._last_thresholds:
+            # new sample
+            self._last_thresholds = self.thresholds
+            return True
+        return False
+
+    def process_key(self, key):
+        if key == misc.constants.K_q or key == misc.constants.K_ESCAPE:
+            self.quit_recording = True
+        elif key == misc.constants.K_v:
+            self.plot_indicator = not self.plot_indicator
+            self.background.stimulus().present()
+        elif key == misc.constants.K_p:
+            # pause
+            self.pause_recording = not self.pause_recording
+        elif key == misc.constants.K_b and self.pause_recording:
+            self.background.stimulus("Recording baseline").present()
+            self.recorder.determine_biases(n_samples=500)
+            self.background.stimulus("Paused").present()
+
+        elif key == misc.constants.K_KP_MINUS:
+            self.scaling_plotter.increase_data_range()
+            self.scaling_indicator.increase_data_range()
+            self.background.stimulus().present()
+            self.clear_screen = True
+        elif key == misc.constants.K_KP_PLUS:
+            self.scaling_plotter.decrease_data_range()
+            self.scaling_indicator.decrease_data_range()
+            self.background.stimulus().present()
+            self.clear_screen = True
+        elif key == misc.constants.K_UP:
+            self.scaling_plotter.data_range_up()
+            self.scaling_indicator.data_range_up()
+            self.background.stimulus().present()
+            self.clear_screen = True
+        elif key == misc.constants.K_DOWN:
+            self.scaling_plotter.data_range_down()
+            self.scaling_indicator.data_range_down()
+            self.background.stimulus().present()
+            self.clear_screen = True
+        elif key == misc.constants.K_f:
+            self.plot_filtered = not self.plot_filtered
+
+        elif key == misc.constants.K_t:
+            tmp = _text2number_array(
+                        io.TextInput("Enter thresholds",
+                                    background_stimulus=logo_text_line("")).get())
+            self.background.stimulus().present()
+            if tmp is not None:
+                self.thresholds = Thresholds(tmp, n_channels=self.n_sensors)
+            else:
+                self.thresholds = None
+
+    def process_udp_event(self, udp_event):
+        """remote control
+
+        See commands in pyforceDAQ.types.GUIRemoteControlCommands
+        """
+
+        if self.remote_control and udp_event.is_remote_control_command:
+            if udp_event.byte_string == RcCmd.START:
+                self.pause_recording = False
+            elif udp_event.byte_string == RcCmd.PAUSE:
+                self.pause_recording = True
+            elif udp_event.byte_string == RcCmd.QUIT:
+                self.quit_recording = True
+
+            elif udp_event.startswith(RcCmd.SET_THRESHOLDS): # thresholds
+                try:
+                    self.thresholds = loads(
+                        udp_event.byte_string[len(RcCmd.SET_THRESHOLDS):])
+                    if not isinstance(self.thresholds, Thresholds): # ensure not strange types
+                        self.thresholds = None
+                    else:
+                        self.thresholds.set_number_of_channels(self.n_sensors)
+                except:
+                    self.thresholds = None
+
+            elif udp_event.startswith(RcCmd.GET_THRESHOLD_LEVEL) or \
+                 udp_event.startswith(RcCmd.GET_THRESHOLD_LEVEL2):
+                if self.thresholds is not None:
+                    s = int(udp_event.startswith(RcCmd.GET_THRESHOLD_LEVEL2))
+                    tmp = self.thresholds.get_level(self.level_detection_parameter_average(s))
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE + dumps(tmp))
+                else:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE + dumps(None))
+            elif udp_event.startswith(RcCmd.SET_LEVEL_CHANGE_DETECTION) or \
+                 udp_event.startswith(RcCmd.SET_LEVEL_CHANGE_DETECTION2):
+                if self.thresholds is not None:
+                    s = int(udp_event.startswith(RcCmd.SET_LEVEL_CHANGE_DETECTION2))
+                    self.thresholds.set_level_change_detection(self.level_detection_parameter_average(s),
+                                                               channel=s)
+
+            elif udp_event.startswith(RcCmd.SET_RESPONSE_MINMAX_DETECTION) or \
+                    udp_event.startswith(RcCmd.SET_RESPONSE_MINMAX_DETECTION2):
+                try:
+                    duration =  int(loads(
+                        udp_event.byte_string[len(RcCmd.SET_RESPONSE_MINMAX_DETECTION):]))
+                except:
+                    duration = None
+
+                s = int(udp_event.startswith(RcCmd.SET_LEVEL_CHANGE_DETECTION2))
+                if self.thresholds is not None and duration is not None:
+                    self.thresholds.set_response_minmax_detection(
+                        value = self.level_detection_parameter_average(s), duration = duration,
+                        channel=s)
+
+            elif udp_event.byte_string == RcCmd.GET_VERSION:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                            dumps(forceDAQVersion))
+            elif udp_event.byte_string == RcCmd.PING:
+                self.recorder.udp.send_queue.put(RcCmd.PING)
+            elif udp_event.byte_string == RcCmd.GET_FX1:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                 dumps(self.sensor_processes[0].Fx))
+            elif udp_event.byte_string == RcCmd.GET_FY1:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                 dumps(self.sensor_processes[0].Fy))
+            elif udp_event.byte_string == RcCmd.GET_FZ1:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                 dumps(self.sensor_processes[0].Fz))
+            elif udp_event.byte_string == RcCmd.GET_TX1:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                 dumps(self.sensor_processes[0].Fx))
+            elif udp_event.byte_string == RcCmd.GET_TY1:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                 dumps(self.sensor_processes[0].Fy))
+            elif udp_event.byte_string == RcCmd.GET_TZ1:
+                self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                 dumps(self.sensor_processes[0].Fz))
+            elif self.n_sensors > 1:
+                if udp_event.byte_string == RcCmd.GET_FX2:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                     dumps(self.sensor_processes[1].Fx))
+                elif udp_event.byte_string == RcCmd.GET_FY2:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                     dumps(self.sensor_processes[1].Fy))
+                elif udp_event.byte_string == RcCmd.GET_FZ2:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                     dumps(self.sensor_processes[1].Fz))
+                elif udp_event.byte_string == RcCmd.GET_TX2:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                     dumps(self.sensor_processes[1].Fx))
+                elif udp_event.byte_string == RcCmd.GET_TY2:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                     dumps(self.sensor_processes[1].Fy))
+                elif udp_event.byte_string == RcCmd.GET_TZ2:
+                    self.recorder.udp.send_queue.put(RcCmd.VALUE +
+                                                     dumps(self.sensor_processes[1].Fz))
+        else:
+            # not remote control command
+            self.set_marker = True
+            self.last_udp_data = udp_event.byte_string
+
+
+    def update_history(self, sensor):
+        self.history[sensor].update(self.sensor_processes[sensor].get_Fxyz())
+
+    def level_detection_parameter_average(self, sensor):
+        """just a short cut"""
+        if sensor < self.n_sensors:
+            return self.history[sensor].moving_average[self.level_detection_parameter]
+        else:
+            return None
+
+

pyforcedaq/gui/_layout.py

@@ -0,0 +1,104 @@
+__author__ = 'Oliver Lindemann'
+
+# helper functions
+import os
+from time import strftime
+import pygame
+
+from expyriment import stimuli
+from expyriment.misc import constants
+
+from .. import __version__ as forceDAQVersion
+
+colours = [constants.C_RED,
+               constants.C_GREEN,
+               constants.C_YELLOW,
+               constants.C_BLUE,
+               constants.C_EXPYRIMENT_ORANGE,
+               constants.C_EXPYRIMENT_PURPLE]
+
+def get_pygame_rect(stimulus, screen_size):
+    """little helper function that returns the pygame rect from stimuli"""
+    half_screen_size = (screen_size[0] / 2, screen_size[1] / 2)
+    pos = stimulus.absolute_position
+    stim_size = stimulus.surface_size
+    rect_pos = (pos[0] + half_screen_size[0] - stim_size[0] / 2,
+                - pos[1] + half_screen_size[1] - stim_size[1] / 2)
+    return pygame.Rect(rect_pos, stim_size)
+
+def logo_text_line(text):
+    blank = stimuli.Canvas(size=(600, 400))
+    logo = stimuli.Picture(filename=os.path.join(os.path.dirname(__file__),
+                            "forceDAQ_logo.png"), position = (0, 150))
+    logo.scale(0.6)
+    stimuli.TextLine(text="Version " + forceDAQVersion, position=(0,80),
+                     text_size = 14,
+                     text_colour=constants.C_EXPYRIMENT_ORANGE).plot(blank)
+    logo.plot(blank)
+    stimuli.TextLine(text=text).plot(blank)
+    return blank
+
+class RecordingScreen(object):
+    def __init__(self, window_size, filename, remote_control):
+        """Expyriment has to be intialized"""
+        margin = 30
+        self.left = -1*window_size[0]/2 + margin
+        self.right = window_size[0]/2 - margin
+        self.top = window_size[1]/2 - margin
+        self.bottom = -1*window_size[1]/2 + margin
+
+        self.elements = []
+        self.add_text_line_left("Force Recorder " + str(forceDAQVersion),
+                                [self.left, self.top], text_size=15)
+        self.add_text_line_left("(p) pause/unpause", [self.left, self.bottom])
+        self.add_text_line_left("(v) switch view", [self.left + 160, self.bottom +20])
+        self.add_text_line_left("(f) switch filtered", [self.left + 160, self.bottom])
+        self.add_text_line_left("(+/-): axes scaling", [self.left + 340, self.bottom + 20])
+        self.add_text_line_left("(up/down): axes shift", [self.left + 340, self.bottom])
+        self.add_text_line_left("(t): change thresholds", [self.left + 560, self.bottom])
+        self.add_text_line_right("(q) quit recording", [self.right, self.bottom ])
+        self.add_text_line_centered("file: " + filename, [0, self.top], text_size=15)
+        if remote_control:
+            self.add_text_line_centered("REMOTE CONTROL", [0, self.top-20], text_size=15)
+        self.add_text_line_right("date: {0}".format(strftime("%d/%m/%Y")),
+                                [self.right, self.top], text_size=15)
+
+    @staticmethod
+    def _text_line(text, position, text_size=12, text_colour=(255, 150, 50)):
+        """helper function"""
+        return stimuli.TextLine(text, position=position,
+                                text_size=text_size,
+                                text_colour=text_colour)
+
+    def add_text_line_centered(self, text, position, text_size=12,
+                               text_colour=(255, 150, 50)):
+        self.elements.append(RecordingScreen._text_line(text, position,
+                                                       text_size,
+                                                       text_colour))
+
+    def add_text_line_right(self, text, position, text_size=12,
+                            text_colour=(255, 150, 50)):
+        """text_line right aligned"""
+        txt = RecordingScreen._text_line(text, position, text_size,
+                                        text_colour)
+        txt.move((-1 * (txt.surface_size[0] / 2), 0))
+        self.elements.append(txt)
+
+    def add_text_line_left(self, text, position, text_size=12,
+                           text_colour=(255, 150, 50)):
+        """text line left aligned"""
+        txt = RecordingScreen._text_line(text, position, text_size,
+                                        text_colour)
+        txt.move((txt.surface_size[0] / 2, 0))
+        self.elements.append(txt)
+
+    def stimulus(self, infotext=""):
+        """Return the stimulus including infotext (obligatory)"""
+        canvas = stimuli.BlankScreen()
+        for elem in self.elements:
+            elem.plot(canvas)
+        if len(infotext) > 0:
+            RecordingScreen._text_line(text=infotext, position=[0, 0],
+                                      text_size=36).plot(canvas)
+        return canvas
+