----------------------------------------------
Getting ready
----------------------------------------------
Installation
----------------------------------------------
1) Install a current python distribution (**64-bit, Python 3.8.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.
.. important:: 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:
.. image:: AnacondaDialog.png
:width: 450 px
:align: center
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:
.. code-block::
pip install pyopengl
pip install pyglet==1.4.4
pip install moviepy
pip install seaborn
pip install pyqt5
.. note:: 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
`https://github.com/imageio/imageio-binaries/tree/master/ffmpeg`
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:
a. ``pip install imageio``
b. Then run ``python``, ...
c. ... and ``import imageio``, and then ``imageio.plugins.ffmpeg.download()``.
3) Copy the content of the .zip file into a folder (e.g. ``C:\User\QDSpy``),
keeping the internal folder substructure intact.
.. warning:: 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:
a. Run Spyder (note that the first start can take some time).
b. In the menu, select ``Tools``, then ``PYTHONPATH manager``
c. 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.
5) 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:
.. code-block::
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):
a. 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.
b. 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.
.. _digital-i-o-label:
6) 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
:doc:`inifile`:
.. code-block:: ini
[Timing]
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:
.. code-block:: ini
...
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!).
.. code-block:: ini
...
int_digitalio_port_out = A
int_digitalio_pin_markerOut = 2
int_digitalio_port_in = B
.. _gamma-correction-installation-label:
7) 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:
.. code-block:: ini
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ICM]
"GdiIcmGammaRange"=dword:00000100
To reactivate Windows' safety measures:
.. code-block:: ini
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ICM]
"GdiIcmGammaRange"=dword:00000000
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.
.. warning:: 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:
.. code-block:: guess
Windows PowerShell
Copyright (C) 2014 Microsoft Corporation. Alle Rechte vorbehalten.
PS C:\Users\Thomas\QDSpy3> python QDSpy_GUI_main.py
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
.. code-block:: guess
PS C:\Users\Thomas\QDSpy3> python QDSpy_GUI_main.py --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:
.. code-block:: guess
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
:doc:`writing_scripts`):
.. code-block:: guess
PS E:\User\Dropbox\QDSpy\Stimuli> python .\stimLCTest2.py
*** 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:
.. code-block:: guess
PS E:\User\Dropbox\QDSpy\Stimuli> python .\stimLCTest2.py
*** 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 :doc:`inifile`).
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.