Contents

QDS Commands

QDS Commands

Control stimulus generation

QDS.Initialize(_sName='noname', _sDescr='nodescription', _runMode=1)

Initializes the QDS library. Needs to be called before any other QDS command is used.

Parameters:

_sName
stimulus name

_sDescr
description of stimulus (optional)

_runMode
0=just re-compile,
1=run stimulus if script unchanged
QDS.SetColorMode(_depth_bit, _shift_bit=(0, 0, 0), _mode=0)

Set color mode and bit depth as well as bit offset.

Note

Note that this conversion happens at compile-time (see section How QDSpy works). Changing the mode requires recompilation of the script to affect presentation.

Bit depth and offset each are defined by color (as (r,b,b) tuple). All color values are scaled by the given bit depth and then bitwise left- shifted by the given offset. For example, when color mode is 0..255 (see below), “red” is scaled:

r_new = (r/255 x(2^BitDepth_r -1)) << BitShift_r

Parameters:

_depth_bit
bit depth as tuple (dr, bg, bb)

_shift_bit
bit offsets are tuple (or, og, ob)

_mode
0=color in “gun” values, 0..255
1=color as fraction, 0..1
2=LightCrafter mode B9G9

LightCrafter modes (EXPERIMENTAL)

(here, _depth_bit and _shift_bit are ignored.)

  • Mode B9G9: black+8 grey levels for green and blue LEDs (dichromatic), with blanks (=red LED) for laser-scanning (700 us LED +1400 us blank), 8 lines (=16.667 ms) per stimulus frame (=60 Hz)

  • …

QDS.SetColorLUTEntry(_index, _rgb)

Redefines an entry in the colour lookup table (LUT), allowing to linearize the intensity range of a display.

Note that it alters the gamma LUT at run-time (see section How QDSpy works) on the operation system-side, that is for all connected display devices, including the screen that shows the GUI.

When the program ends, a linear gamma LUT will be automatically restored.

While this adjustment is completely independent of the color mode setting (see QDS.setColorMode()), it is only meaningful for color modes 0 and 1, and not for special lightcrafter modes. Therefore, LUT corrections will not be applied to stimuli using color modes >1.

Parameters:

_index
LUT index, 0..255

_rgb
new LUT entries as tuple (r, g, b)
with r,g,b in 0..255
QDS.StartScript()

Start of the stimulus run section. No definitions are allowed after this command. Must be called before QDS commands that generate stimulus scenes are called.

QDS.EndScript()

Must be called after all stimulus scenes have been created, i.e. at the end of the script.

QDS.Loop(_nRepeats, _func)

Loops the stimulus sequence generated by the given function.

Note that _func is called only once and the loop is coded in the actual compiled stimulus; this can be used to keep compilation time short and reduces the copiled stimulus file size.

Parameters:

_nRepeats
>0 number of repeats, <0 indefinitely

_func
python function that scripts a stimulus

Generate objects

QDS.DefObj_BoxEx(_iobj, _dx, _dy, _enShader=0)

Defines a box object and if shaders can be used for this object.

Parameters:

_iobj
object index

_dx,_dy
box width and height in µm

_enShader
0=disable shaders (default)
1=disable shaders,
see QDS.SetObjShader()
QDS.DefObj_Box(_iobj, _dx, _dy, _angle=0.0)

See QDS.DefObj_BoxEx()

Note

Note that “_angle” is depreciated and ignored in QDSpy. The angle of an object is now set in the render command.

QDS.DefObj_EllipseEx(_iobj, _dx, _dy, _enShader=0)

Defines an ellipse object.

Parameters:

_iobj
object index

_dx,_dy
ellipse diameters in µm

_enShader
0=disable shaders (default)
1=disable shaders,
see QDS.SetObjShader()
QDS.DefObj_Ellipse(_iobj, _dx, _dy, _angle=0.0)

See QDS.DefObj_EllipseEx()

Note

Note that “_angle” is depreciated and ignored in QDSpy. The angle of an object is now set in the render command.

QDS.DefObj_SectorEx(_iobj, _r, _offs, _angle, _awidth, _astep=None, _enShader=0)

Defines a sector object and if shaders can be used for this object.

Parameters:

_iobj
object index

_r
outer radius (of disk) in um

_offs
inner radius (=radius of center “hole”)
in um (0 ≤ offs < r)

_angle
rotation angle in degrees
(of the center of the arc)

_awidth
width of sector
(angle, in degrees)

_astep
“smoothness” of the arc
(1° <= _astep <= 90)
if omitted, _astep is automatically optimized

_enShader
0=disable shaders (default)
1=disable shaders,
see QDS.SetObjShader()
QDS.DefObj_Sector(_iobj, _r, _offs, _angle, _awidth, _astep=None)

See QDS.DefObj_SectorEx()

QDS.DefObj_Movie(_iobj, _fName)

Defines and loads a movie object.

A movie object consists of two files that have the same name but different extensions: a text file (.txt) that describes the dimensions of a frame and the number of frames, and an image file that contains a montage of all frames (.png, .jpg, …).

Note

In contrast to QDS, QDSpy considers the bottom-left frame of a montage the first frame (in QDS it was to top-left frame). Therefore, movie montage files have to be adapted. This can be easily done in ImageJ:

  1. load the montage into ImageJ

  2. use Image/Stacks/Tools/Montage To Stack… to convert the montage into a stack

  3. use Image/Transform/Flip Vertically to mirror the stack along the x axis

  4. use Image/Stacks/Make Montage… to convert the stack back into a montage

  5. use Image/Transform/Flip Vertically again now to mirror the montage along the x axis. Now the frame sequence starts with the bottom-left frame.

Parameters:

_iobj
object index

_fName
string with movie file name
(with image file extension)
QDS.DefObj_Video(_iobj, _fName)

Defines and loads a video object.

A video object consists of a single file; currently the following video format(s) is/are allowed: .avi

Parameters:

_iobj
object index

_fName
string with video file name

Scene and object color

QDS.SetObjColorEx(_iobjs, _ocols, _alphas=[])

Set color of object(s) (not defined for all object types).

Attention

Extended version: Number of objects not anymore a parameter - it is determined by the lenght of the object index list -, and allows to define alpha (transparency) values for each object.

Parameters:

_iobjs
list of objects,
[o1, o2, …],
with oX being valid object indices

_ocols
list of object colors in RGB values,
[(r1,g1,b1{,u1,v1,w1}),(r2,g2,b2{,u2,v2,w2}), …],
with 0 <= r,g,b,u,v,w <= 255 and
a tuple length between 3 and 6

_oalphas
list of object alpha values, 0..255

In the parameter _ocols, the values beyond r,g,b are optional; they are only relevant in “screen overlay mode” and otherwise ignored.

new or changed parameters

QDS.SetObjColorAlphaByVertex(_iobjs, _oRGBAs)

Set color and transparency (alpha) of object(s) by vertex (not defined for all object types).

The number of objects is determined by the lenght of the object index list. Individual color (RGB) and alpha (A) values are expected as a tuples with 4 elements (RGBA). For each object, a list of such RGBA tuples is expected, the number of tuples per object depends on the object type:

  • box, one RGBA tuple for each corner (n=4)

  • ellipse, RGBA[0]=center, RGBA[1]=circumfence, (n=2)

  • sector (actual sector), RGBA[0]=center, RGBA[1]=circumfence, (n=2)

  • sector (arc), RGBA[0]=outer, RGBA[1]=inner circumfence, (n=2)

Parameters:

_iobjs
list of objects,
[o1, o2, …],
with oX being valid object indices

_oRGBAs
list of object colors/transparency as RGBA,
[o1List, o2List, …],
with o1List := [(r1,g2,b1,a1),(r2, …), …]
and 0 <= r,g,b,a <= 255
QDS.SetBkgColor(_col)

Set color of background.

Parameters:

_col
color in RGB values as tupple (r,g,b{,u,v,w})

In the parameter _col, the values beyond r,g,b are optional; they are only relevant in “screen overlay mode” and otherwise ignored.

Render stimulus scenes

QDS.Scene_Clear(_dur, _marker=0)

Clear screen and wait.

Enabling marker causes the display of a white square in the bottom left corner of the screen and/or the output of a TTL pulse via the DIO24 board, if installed).

Parameters:

_dur
duration of scene in seconds

_marker
0=no marker, 1=marker
QDS.Scene_RenderEx(_dur, _iobjs, _opos, _omag, _oang, _marker=0, _screen=0)

Draw objects and wait.

Enabling marker causes the display of a white square in the bottom left corner of the screen and/or the output of a TTL pulse via the DIO24 board, if installed).

Attention

Extended version: Number of objects not anymore a parameter - it is determined by the lenght of the object index list -, and allows to define magnification factors and rotation angles for each object.

Parameters:

_dur
duration of scene in seconds

_iobjs
object indices, as [i1, i2, …]

_opos
object positions, as [(x1,y1), (x2,y2), …]

_omag
object magification as [(mx,my), …]

_oang
object rotation angles in degree as [a1, …]

_marker
0=no marker, 1=marker

new or changed parameters

QDS.Start_Movie(_iobj, _opos, _seq, _omag, _trans, _oang, _screen=0)

Start playing a movie object.

Parameters:

_iobj
index of movie object

_opos
object positions, as (x1,y1)

_seq
sequence parameters, as
[fr0, fr1, frreps, sqreps], with …
fr0=first, f1=last frame,
frreps=number of frame repeats,
sqreps=number of sequence repeats

_omag
object magification as (mx,my)

_trans
transparency, 0=transparent … 255=opaque

_oang
object rotation angles in degree

_screen
0=standard, 1=render on 2nd screen (=2nd half
of wide screen) in screen overlay mode
QDS.Start_Video(_iobj, _opos, _omag, _trans, _oang, _screen=0)

Start playing a movie object.

Parameters:

_iobj
index of movie object

_opos
object positions, as (x1,y1)

_omag
object magification as (mx,my)

_trans
transparency, 0=transparent … 255=opaque

_oang
object rotation angles in degree

_screen
0=standard, 1=render on 2nd screen (=2nd half
of wide screen) in screen overlay mode

Other functions

QDS.GetDefaultRefreshRate()

Returns the refresh rate (in Hz) defined in the QDS configuration files.

QDS.GetMovieParameters(_iobj)

Returns a list with the parameters of a movie object or None, if an error occurs. The movie object must have been loaded.

Parameters:

_iobj
object index

Returns:

dictionary
“dxFr”, “dyFr”, and “nFr”
with dx,dy the frame size in pixels,
and nFr the number of frames
QDS.GetVideoParameters(_iobj)

Returns a list with the parameters of a video object. The video object must have been loaded.

Parameters:

_iobj
object index

Returns:

dictionary
“dxFr”, “dyFr”, “nFr”, and “fps”
with dx,dy the frame size in pixels,
nFr the number of frames, and fps
refresh rate in frames per second
QDS.GetStimulusPath()

Returns the current path of the stimulus folder. Use this function to make sure that the script can locate user-provided accessory files (e.g. a random number series for a noise stimulus):

path = QDS.getStimulusPath()
file = open(path +"/parameters.txt", "r")
QDS.LogUserParameters(_dict)

Writes a user-defined set of parameters to the history and log file.

Parameters:

_dict
dictionary with parameters
as key-value pairs

Example for such a user parameter entry as it appears in the history and log file:

20151220_135948    DATA {'nTrials': 1, 'dxStim_um': 1000}

previous

Lightcrafter

next

Disclaimer