Units

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 any compound 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:

val_px = 2*d_cm*tan(val_deg/2)*pxPcm

where d_cm is distance from subject to screen (cm) and pxPcm is pixels per cm on the screen.

In order to interpret deg units, PsychBench wants to know screen height (not including bezel) and distance from subject, both in cm. The first time you run an experiment, it asks for these values and saves them. Whenever you run an experiment again, it asks whether you want to use the saved values or change them. It can also save values for multiple screens in case you use different screens at different times.

You can also set screen height and distance directly in an experiment script. To do this, make a screen object and set properties height_cm and distance_cm. If you do, PsychBench doesn’t prompt when the experiment runs.

For any property that uses deg, you can also use any of the following units instead. To do this, set the property to 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. <cd>0.5<cd> or <cd>1/2<cd> = 50% window height
<cds>"wwh"  <cds> – fraction of window width for x, height for y (alternating within rows for vectors/matrixes)
<cds>"px"   <cds> – pixels on screen

* deg- units can be useful in some circumstances since they scale linearly with regular distance units like px and cm, whereas regular deg units scale non-linearly (e.g. 10 deg in px or cm is not exactly = 10 × [1 deg in px or cm]). deg- = deg at the limit of deg = 0.

Note a couple of little tools deg2px and px2deg are in <PsychBench folder>/tools. Generally you don't need these when working with object properties. But they are available 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. Many elements have a transparent background anyway. For all elements you can apply transparency to the whole element using property alpha (0–1).