.. _colorspaces: Color spaces ==================================== .. image:: /images/colorPicker.png *You can explore colors in PsychoPy Builder through accessing the color picker from any parameter that takes a color value.* The color of stimuli can be specified when creating a stimulus and when using setColor() in a variety of ways. From Builder view you can also use the color picker to pick the color you want and explore what value that color would correspond to in a variety of spaces. There are three basic color spaces that |PsychoPy| can use, RGB, DKL and LMS but colors can also be specified by a name (e.g. 'DarkSalmon') or by a hexadecimal string (e.g. '#00FF00'). examples:: stim = visual.GratingStim(win, color=[1,-1,-1], colorSpace='rgb') #will be red stim.setColor('Firebrick')#one of the web/X11 color names stim.setColor('#FFFAF0')#an off-white stim.setColor([0,90,1], colorSpace='dkl')#modulate along S-cone axis in isoluminant plane stim.setColor([1,0,0], colorSpace='lms')#modulate only on the L cone stim.setColor([1,1,1], colorSpace='rgb')#all guns to max stim.setColor([1,0,0])#this is ambiguous - you need to specify a color space .. _colorNames: Colors by name ---------------- Any of the `web/X11 color names `_ can be used to specify a color. These are then converted into RGB space by |PsychoPy|. These are not case sensitive, but should not include any spaces. .. _hexColors: Colors by hex value -------------------- This is really just another way of specifying the r,g,b values of a color, where each gun's value is given by two hexadecimal characters. For some examples see `this chart `_. To use these in |PsychoPy| they should be formatted as a string, beginning with `#` and with no spaces. (NB on a British Mac keyboard the # key is hidden - you need to press Alt-3) .. _RGB: RGB color space ------------------- This is the simplest color space, in which colors are represented by a triplet of values that specify the red green and blue intensities. These three values each range between -1 and 1. Examples: * :code:`[1,1,1]` is white * :code:`[0,0,0]` is grey * :code:`[-1,-1,-1]` is black * :code:`[1.0,-1,-1]` is red * :code:`[1.0,0.6,0.6]` is pink The reason that these colors are expressed ranging between 1 and -1 (rather than 0:1 or 0:255) is that many experiments, particularly in visual science where |PsychoPy| has its roots, express colors as deviations from a grey screen. Under that scheme a value of -1 is the maximum decrement from grey and +1 is the maximum increment above grey. You can still specify colors in RGB from 0:1 or 0:255, but you will need to let |PsychoPy| know that this is what you're doing. To do this, set the color space to be `rgb1` for 0:1 or `rgb255` for 0:255 - if the color space is just `rgb`, then values will be from -1:1 Note that |PsychoPy| will use your monitor calibration to linearize this for each gun. E.g., 0 will be halfway between the minimum luminance and maximum luminance for each gun, if your monitor gammaGrid is set correctly. .. _HSV: HSV color space ------------------ Another way to specify colors is in terms of their Hue, Saturation and 'Value' (HSV). For a description of the color space see the `Wikipedia HSV entry `_. The Hue in this case is specified in degrees, the saturation ranging 0:1 and the 'value' also ranging 0:1. Examples: * :code:`[0,1,1]` is red * :code:`[0,0.5,1]` is pink * :code:`[90,1,1]` is cyan * :code:`[anything, 0, 1]` is white * :code:`[anything, 0, 0.5]` is grey * :code:`[anything, anything,0]` is black Note that colors specified in this space (like in RGB space) are not going to be the same another monitor; they are device-specific. They simply specify the intensity of the 3 primaries of your monitor, but these differ between monitors. As with the RGB space gamma correction is automatically applied if available. .. _DKL: DKL color space ------------------- To use DKL color space the monitor should be calibrated with an appropriate spectrophotometer, such as a PR650. In the Derrington, Krauskopf and Lennie [#dkl1984]_ color space (based on the Macleod and Boynton [#mb1979]_ chromaticity diagram) colors are represented in a 3-dimensional space using spherical coordinates that specify the `elevation` from the isoluminant plane, the `azimuth` (the hue) and the contrast (as a fraction of the maximal modulations along the cardinal axes of the space). .. image:: /images/dklSpace.png In |PsychoPy| these values are specified in units of degrees for elevation and azimuth and as a float (ranging -1:1) for the contrast. Note that not all colors that can be specified in DKL color space can be reproduced on a monitor. You can see `here a movie plotting colors in DKL space `_ (showing `cartesian` coordinates, not spherical coordinates) to show the gamut of colors available on an example monitor. Examples: * :code:`[90,0,1]` is white (maximum elevation aligns the color with the luminance axis) * :code:`[0,0,1]` is an isoluminant stimulus, with azimuth 0 (S-axis) * :code:`[0,45,1]` is an isoluminant stimulus,with an oblique azimuth .. [#dkl1984] Derrington, A.M., Krauskopf, J., & Lennie, P. (1984). Chromatic Mechanisms in Lateral Geniculate Nucleus of Macaque. Journal of Physiology, 357, 241-265. .. [#mb1979] MacLeod, D. I. A. & Boynton, R. M. (1979). Chromaticity diagram showing cone excitation by stimuli of equal luminance. Journal of the Optical Society of America, 69(8), 1183-1186. .. _LMS: LMS color space -------------------- To use LMS color space the monitor should be calibrated with an appropriate spectrophotometer, such as a PR650. In this color space you can specify the relative strength of stimulation desired for each cone independently, each with a value from -1:1. This is particularly useful for experiments that need to generate cone isolating stimuli (for which modulation is only affecting a single cone type).