Getting started / Making an experiment


Distance units – deg, deg-, cm, ww, wh, wwh, px

By default most object properties relating to distance on screen use units of visual angle degrees (deg). This includes deg as well as related units like deg/sec (e.g. speed), cycles/deg (e.g. spatial frequency), etc. During experiments PsychBench converts degrees to pixels on screen using the standard formula:

<cd>val_px = 2*d_cm*tan(val_deg/2)*pxPcm<cd>

where d_cm is distance from eye to display panel in cm and pxPcm is pixels per cm on the display panel.

In order to interpret deg units, PsychBench needs to know display panel height (dimension) and distance from eye, both in cm. The first time you run an experiment, it asks for these values and saves them. From then on, it asks whether you want to use the saved values or change them. It can also save values for multiple display devices in case you use different ones.

You can also set height and distance directly in an experiment. To do this, add a screen object and set its properties height_cm and distance_cm. Then PsychBench won't ask when you run that experiment.

For any property that uses deg, you can also use any of the following units instead. To do this, put the property value in a 1×2 cell array <cd>{value, <cd><cds>"units"<cds><cd>}<cd>, where units is a string:

<cds>"deg" <cds> – degrees visual angle (default)
<cds>"deg-"<cds> – degrees visual angle with small angle approximation tanθ ≈ θ
<cds>"cm"  <cds> – centimeters
<cds>"ww"  <cds> – fraction of window width
<cds>"wh"  <cds> – fraction of window height, e.g. 0.5 or 1/2 = 50% window height
<cds>"wwh" <cds> – fraction of window width for x, height for y (alternating within rows for arrays)
<cds>"px"  <cds> – pixels on screen

Note a couple of little tools deg2px and px2deg are in <><PsychBench folder><>/tools. Generally you don't need these when working with properties. They are available just in case helpful.

Color units – RGB(A)

Properties setting color generally use RGB vectors. These are 1×3 vectors with numbers between
0–1 corresponding to intensity for red, green, blue components: 0 = no intensity, 1 = full intensity.

Sometimes you can also use a 1×4 RGBA vector where the fourth “alpha” component sets transparency (0 = fully transparent, 1 = fully opaque, 0.5 = 50% transparent, etc.). This is mostly in elements that have the option to set transparency for specific parts. Most elements have a transparent background by default anyway, (changeable in property backColor). And for all elements you can apply transparency to the whole element using property alpha.


<cd>[0    0    0    ]<cd> – black
<cd>[1    1    1    ]<cd> – white​
<cd>[1    0    0    ]<cd> – full red
<cd>[0    0.25 0    ]<cd> – 25% green
<cd>[0.5  0.5  0.5  ]<cd> – 50% gray​
<cd>[1    1    1    0.5  ]<cd> – white 50% transparent