Getting ready


  1. Install a current python distribution (64-bit, Python 3.7.x), e.g. Anaconda. The following steps were tested with Anaconda3 (v4.2.x, v4.3.1, v4.3.21, v5.1.0) - using a different Python distribution may require the installation of additional packages.


    Unless you know what you are doing and are familiar with configuring different Anaconda workspaces, make sure that both boxes in the following dialog are checked:


    You will need to start a windows shell which can be started using cmd.exe or powershell.exe. The latter is the better alternative, as it supports, among other things, a Unix-like syntax.

  2. The software needs several packages that may or may not be included the Anaconda distribution used. These include PyOpenGL, pyglet and MoviePy; furthermore, some example stimulus scripts may use seaborn. Therefore, execute in the shell:

    pip install pyopengl
    pip install pyglet
    pip install moviepy
    pip install seaborn
    pip install pyqt5


    MoviePy is a which is a Python module for script-based movie editing, which is used by QDSpy to display videos.

    When Python imports moviepy for the first time - and this will happen when QDSpy is started - moviepy checks if the software FFMPEG for video reading and writing is present on the machine. If not, it automatically downloads ffmpeg.win32.exe from and stores it under ...\AppData\Local\imageio\ffmpeg.

    If you consider this behaviour irritating, please find instructions for manual installation on the Anaconda site.

    If you know what you are doing, you can manually install the software using the following commands in a shell:

    1. pip install imageio

    2. Then run python, …

    3. … and import imageio, and then

  3. Copy the content of the .zip file into a folder (e.g. C:\User\QDSpy), keeping the internal folder substructure intact.


    If you use GitHub desktop to update your installation from the repository, please make sure that you save copies of your stimulus files and the QDSpy configuration file QDSpy.ini. To avoid overwriting existing QDSpy.ini, the repository does not contain one, however, the existing one might be deleted by the sync.

  4. To run QDSpy, it is important to add the path to the QDSpy main folder to the PYTHONPATH environment variable. If this variable does not yet exist, it needs to be created. There are several ways to do this; an easy way is using Spyder, which comes with the Anaconda package:

    1. Run Spyder (note that the first start can take some time).

    2. In the menu, select Tools, then PYTHONPATH manager

    3. Add the path to the QDSpy folder and press the synchronize button.

    Note that open powershells need to be restarted to acknowledge this change.

If you do not use any special hardware (e.g. digital I/O, a lightcrafter etc) or do not need gamma correction, you can proceed to the section Running the GUI version of QDSpy. Otherwise continue with the following steps.

  1. If you plan to use the LightCrafter 4500 not only as a displaying device but also want to configure it via QDSpy (via USB), then you will need the hidapi package.

    For Python 3.4 through 3.7 (all 64 bit), pre-compiled libraries (hid.cp3x-win_amd64.pyd) are provided in ...\QDSpy\Devices. To test if it works, run python in the main directory and try to import hid from the ...\QDSpy\Devices subfolder:

    PS C:\User\QDSpy> python
    Python 3.5.1 |Anaconda 4.0.0 (64-bit)| (default, Feb 16 2016, 09:49:46) [MSC v.1900 64 bit (AMD64)] on win32
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import Devices.hid

    If no error occurs, your all set.

    If this does not work, the hidapi package needs to be installed. The installation of hidapi via pip generates an error unless the respective Microsoft Visual C++ compiler/SDK package is installed. Note that Python 3.4.x and 3.5.x require different versions of Microsoft Visual C++. Currently, the following steps seem to work for Python 3.5.x (and 3.6.x):

    1. Install Microsoft Visual Studio Community 2015 (or Microsoft Visual Studio Express 2015); the free version is sufficient. Make sure you choose the user-defined installation, where you can include Visual C++ including its tools as well as Python Tools for Visual Studio.

    2. Goto hidapi, choose the newest package (currently hidapi 0.7.99.post20) and follow the instructions listed under Build from source. To this end, use the git shell that comes with GitHub for Windows.

    Now try again importing hid as described above.

  1. If you plan to use a digital I/O card from Measurement Computing, you need to install their Universal Library (the 64-bit version). Note that you’ll need to reboot before the library is available to QDSpy. Enable the support for digital I/O in the Configuration file:

    bool_use_digitalio = True
    str_digitalio_board_type = PCIDIO24

    Measurement Computing’s Universal Library comes with an application called “InstaCal”, which provides you with the board and device number to be set here:

    int_digitalio_board_num = 0
    int_digitalio_device_num = 1

    Adjust the following lines according to port (e.g. “A”) and pin (e.g. “2”) that gives out the stimulus marker. The input port definition is not yet used, however, it is recommended to use a different port (currently, QDSpy ignores the output pin and sets the complete output port according to the marker status!).

    int_digitalio_port_out = A
    int_digitalio_pin_markerOut = 2
    int_digitalio_port_in = B
  1. If you need gamma correction (currently Windows-only): Depending how strongly the color presentation needs to be changed, you may have to define/change a registry key that tells Windows normally to prevents too extreme color changes by the user. For details on gamma correction, see here.

    To deactivate Windows’ safety measures, write the following text in a file with the extension .reg and double-click it:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ICM]

    To reactivate Windows’ safety measures:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ICM]

    You may have to reboot for this change to become active.

    Note that QDSpy currently uses Windows’ SetDeviceGammaRamp function to change gamma. The advantage is that it is very simple to use, however, a side effect is that all connected screens are affected.


    With the registry key set as described above, you can accidentally turn all screens unreadable!!

Running the GUI version of QDSpy

Open a windows shell (powershell.exe) and change to the QDSpy folder. Run the GUI version of QDSpy:

Windows PowerShell
Copyright (C) 2014 Microsoft Corporation. Alle Rechte vorbehalten.

PS C:\Users\Thomas\QDSpy3> python

Alternatively, use the included batch file QDSpy.bat to start the GUI version of QDSpy. For instance, create a link to this batch file on the desktop; change the icon of this linke to QDSpy.ico`.

Using the batch file is equivalent to

PS C:\Users\Thomas\QDSpy3> python --gui

The optional command line parameter --gui directs all messages (except for messages generated when scripts are compiled) exclusively to the history window of the GUI. The parameter is ignored when starting stimulus files directly from the shell.

Using QDSpy with the shell

Another way to compile and run stimulus scripts is by using the windows shell.

  1. Start a shell and change to the folder that contains the stimulus scripts:

    Windows PowerShell
    Copyright (C) 2014 Microsoft Corporation. Alle Rechte vorbehalten.
    PS C:\Users\Thomas> e:
    PS E:\> cd .\user\Dropbox\QDSpy\QDS_stimuli
    PS E:\user\Dropbox\QDSpy\QDS_stimuli>
  2. Compile a script (for details on writing QDS stimulus scripts, see Writing QDSpy stimulus scripts):

    PS E:\User\Dropbox\QDSpy\Stimuli> python .\
         *** QDSpy v0.4 alpha Compiler - (c) 2013-15 Thomas Euler
             Initializing ...
             Defining objects ...
          ok 150 object(s) defined.
          ok 0 shader(s) defined.
             Generating scenes ...
          ok 245 scene(s) defined.
          ok Stimulus 'Test2' compiled for 60.0 Hz refresh (default).
          ok Stimulus 'Test2' saved to 'stimLCTest2.pickle'
          ok ... done in 1.204 s
    PS E:\User\Dropbox\QDSpy\Stimuli>

    Some information about the script is shown, the script is compiled and saved to disk as a .pickle file of the same name as the .py script file.

  3. To present the compiled stimulus, run the script again:

    PS E:\User\Dropbox\QDSpy\Stimuli> python .\
         *** QDSpy v0.4 alpha Compiler - (c) 2013-15 Thomas Euler
             Initializing ...
        INFO Script has not changed, running stimulus now ...
         *** QDSpy v0.4 alpha Presenter - (c) 2013-15 Thomas Euler
          ok Initializing ...
             ENABLED    : high process priority during presentation
             enabled    : automatic garbage collection
        INFO OpenGL     : v4.3.12618 Compatibility Profile Context 13.251.9001.1001
        INFO Renderer   : AMD Radeon HD 7800 Series by ATI Technologies Inc.
        INFO Timing     : vsync-based (Pyglet calls), DEFAULT
          ok Window mode, 800x600 pixels
             ENABLED    : forced fsync
          ok SwapIntervalEXT() reported success
          ok Stage center: 0,0 pixels, scale: 0.83,0.83 µm/pix, rotation: 0°, refresh: 60.0 Hz
             2 shader type(s) found
          ok Stimulus 'stimLCTest2.pickle' loaded
             Name       : Test2
             Description: Test for Lightcrafter
             Frequency  : 60.0 Hz
          ok Stimulus 'Test2' prepared
          ok Running...
     WARNING dt of frame #2 was 13.824 ms
     WARNING dt of frame #60 was 33.576 ms
     WARNING dt of frame #120 was 19.380 ms
     WARNING dt of frame #121 was 14.338 ms
          ok Done
          ok Program finished
        INFO 16.666 ms/frame (60.002 Hz), rendering: 1.033 ms (720 frames in total)
        INFO 16.689 +/- 0.669 ms/frame (over the last 719 frames) = 59.9 Hz
     WARNING 4 frames dropped (=0.556 %)
          ok ... done
    PS E:\User\Dropbox\QDSpy\Stimuli>

    The script checks if the .pickle file is more recent that the .py file (indicating that the .py file has not changed). If this is the case, the stimulus is presented, acknowledging the settings in the folder’s configuration file (QDSpy.ini, see Configuration file).

    Before displaying the stimulus, some information about the system is shown. To abort the stimulus, press Q; note that (currently) the focus has to be on the stimulus window for these keys to be active.