BitsPlusPlus

Control a CRS Bits# device. See typical usage in the class summary (and in the menu demos>hardware>BitsBox of PsychoPy’s Coder view).

Important: See note on BitsPlusPlusIdentityLUT

Attributes

BitsPlusPlus(win[, contrast, gamma, ...])	The main class to control a Bits++ box.
BitsPlusPlus.mode
BitsPlusPlus.setContrast(contrast[, ...])	Set the contrast of the LUT for ‘bits++’ mode only
BitsPlusPlus.setGamma(newGamma)	Set the LUT to have the requested gamma value Currently also resets the LUT to be a linear contrast ramp spanning its full range.
BitsPlusPlus.setLUT([newLUT, gammaCorrect, ...])	Sets the LUT to a specific range of values in ‘bits++’ mode only

Details

class psychopy.hardware.crs.bits.BitsPlusPlus(win, contrast=1.0, gamma=None, nEntries=256, mode='bits++', rampType='configFile')

The main class to control a Bits++ box.

This is usually a class added within the window object and is typically accessed from there. e.g.:

from psychopy import visual
from psychopy.hardware import crs

win = visual.Window([800,600])
bits = crs.BitsPlusPlus(win, mode='bits++')
# use bits++ to reduce the whole screen contrast by 50%:
bits.setContrast(0.5)

Parameters:

contrast :

The contrast to be applied to the LUT. See BitsPlusPlus.setLUT() and BitsPlusPlus.setContrast() for flexibility on setting just a section of the LUT to a different value

gamma :

The value used to correct the gamma in the LUT

nEntries

: 256

[DEPRECATED feature]

mode

: ‘bits++’ (or ‘mono++’ or ‘color++’)

Note that, unlike the Bits#, this only affects the way the window is rendered, it does not switch the state of the Bits++ device itself (because unlike the Bits# have no way to communicate with it). The mono++ and color++ are only supported in PsychoPy 1.82.00 onwards. Even then they suffer from not having gamma correction applied on Bits++ (unlike Bits# which can apply a gamma table in the device hardware).

rampType

: ‘configFile’, None or an integer

if ‘configFile’ then we’ll look for a valid config in the userPrefs folder if an integer then this will be used during win.setGamma(rampType=rampType):

reset()

Deprecated: This was used on the old Bits++ to power-cycle the box It required the compiled dll, which only worked on windows and doesn’t work with Bits#

setContrast(contrast, LUTrange=1.0, gammaCorrect=None)

Set the contrast of the LUT for ‘bits++’ mode only

Parameters:

contrast

: float in the range 0:1

The contrast for the range being set

LUTrange

: float or array

If a float is given then this is the fraction of the LUT to be used. If an array of floats is given, these will specify the start / stop points as fractions of the LUT. If an array of ints (0-255) is given these determine the start stop indices of the LUT

Examples:

setContrast(1.0,0.5)

will set the central 50% of the LUT so that a stimulus with contr=0.5 will actually be drawn with contrast 1.0

setContrast(1.0,[0.25,0.5])

setContrast(1.0,[63,127])

will set the lower-middle quarter of the LUT (which might be useful in LUT animation paradigms)

setGamma(newGamma)

Set the LUT to have the requested gamma value Currently also resets the LUT to be a linear contrast ramp spanning its full range. May change this to read the current LUT, undo previous gamm and then apply new one?

setLUT(newLUT=None, gammaCorrect=True, LUTrange=1.0)

Sets the LUT to a specific range of values in ‘bits++’ mode only

Note that, if you leave gammaCorrect=True then any LUT values you supply will automatically be gamma corrected.

The LUT will take effect on the next Window.flip()

Examples:

bitsBox.setLUT()

builds a LUT using bitsBox.contrast and bitsBox.gamma

bitsBox.setLUT(newLUT=some256x1array)

(NB array should be float 0.0:1.0) Builds a luminance LUT using newLUT for each gun (actually array can be 256x1 or 1x256)

bitsBox.setLUT(newLUT=some256x3array)

(NB array should be float 0.0:1.0) Allows you to use a different LUT on each gun

(NB by using BitsBox.setContr() and BitsBox.setGamma() users may not need this function)

Finding the identity LUT

For the Bits++ (and related) devices to work correctly it is essential that the graphics card is not altering in any way the values being passed to the monitor (e.g. by gamma correcting). It turns out that finding the ‘identity’ LUT, where exactly the same values come out as were put in, is not trivial. The obvious LUT would have something like 0/255, 1/255, 2/255... in entry locations 0,1,2... but unfortunately most graphics cards on most operating systems are ‘broken’ in one way or another, with rounding errors and incorrect start points etc.

PsychoPy provides a few of the common variants of LUT and that can be chosen when you initialise the device using the parameter rampType. If no rampType is specified then PsychoPy will choose one for you:

from psychopy import visual
from psychopy.hardware import crs

win = visual.Window([1024,768], useFBO=True) #we need to be rendering to framebuffer
bits = crs.BitsPlusPlus(win, mode = 'bits++', rampType = 1)

The Bits# is capable of reporting back the pixels in a line and this can be used to test that a particular LUT is indeed providing identity values. If you have previously connected a BitsSharp device and used it with PsychoPy then a file will have been stored with a LUT that has been tested with that device. In this case set rampType = “configFile” for PsychoPy to use it if such a file is found.