Example: Sending a digital trigger on Pixel Sync

In this example we will send a digital trigger on the next Pixel Sync, via the digital output on the DATAPixx I/O hub.

We start by defining

a pixel sequence to act as our cue for Pixel Sync
a digital output state we wish to execute when this sequence appears

Then we send our command to register write on Pixel Sync.

Once you have sent a call to RegWrPixelSync, you will want to flip your pixel sequence to the display relatively quickly. While RegWr is not a blocking function, it will place the DATAPixx I/O hub in a “busy” state and stop you from being able to execute other register writes and updates until the pixel trigger is detected.

In order to stop the RegWrPixelSync command from hanging for too long, there is a “timeout” variable which specifies the number of video frames before the register write will automatically execute. In our example we set the timeout to a reasonable period (60 frames).

We recommend a trigger sequence of at least 8 pixels when using PixelSync, to ensure the trigger is unique. To align the trigger with stimulus onset, the pixels should be embedded in the top of your stimuli, without any blending or dithering applied.

MATLAB/Psychtoolbox

MATLAB

%Connect
Datapixx('Open')

%First, we define the pixel sequence we are waiting for. In this case, it 
%is a series of 8 red and green pixels in the top corner of our image. We define 
%these pixels in a 3 x 8 array, where the columns are the number of pixels in 
%the sequence and rows are the red, green and blue values of the pixels.
pixelTrigger = [255, 0, 255, 0, 255, 0, 255, 0;    %R
                  0, 255, 0, 255, 0, 255, 0, 255;  %G
                  0, 0, 0, 0, 0, 0, 0, 0];         %B

%Next, we set our desired digital output. Let’s say we want to set DOut 4-7 to 
%high, and everything else to low. This command is stored in the local register 
%for now.
doutValue = bin2dec('0000 0000 0000 0000 1111 0000');
Datapixx('SetDoutValues', doutValue);

%Nothing has happened on the device register yet. Let’s write an update to the 
%device register on the next appearance of our pixel sequence, i.e., when our 
%target appears.
timeout = 60 %frames
Datapixx('RegWrPixelSync', pixelTrigger, timeout);

Python (libdpx wrapper)

PY

from pypixxlib import _libdpx as dp
import numpy as np

#Connect
dp.DPxOpen()

#First, we define the pixel sequence we are waiting for, the pixeTrigger. In 
#this case, our  trigger is a series of 8 red and green pixels in the top corner 
#of our image. In Python, the pixel trigger RGB values are passed as a single 
#vector, ie [R1, G1, B1, R2, G2, B2, etc]. 
#We use the numpy 'tile' function #to repeat our [red, green] pattern four times 
#to generate the full trigger.
pixelPattern = [255, 0, 0, 0, 255, 0] #1 red and 1 green pixel
pixelTrigger = list(np.tile(pixelPattern,4))

#Next, we set our desired digital output. Let’s say we want to set DOut 4-7 to 
#high, and everything else  to low. This command is stored in the local register 
#for now. We use binary to represent all 24 digital outputs and set positions 
#4-7 to 1. The int() command converts this value to one that can be read by the 
#device. 
doutValue = int('000000000000000011110000', 2)
bitMask = 0xffffff
dp.DPxSetDoutValue(doutValue, bitMask)

#Nothing has happened on the device register yet. Let’s write an update to the 
#device register on the next appearance of our pixel sequence, i.e., when our 
#target appears.
timeout = 60 #frames
triggerLength = int((len(pixelTrigger)/3))
dp.DPxWriteRegCacheAfterPixelSync(triggerLength, pixelTrigger, timeout)

Python (object-oriented)

PY

import numpy as np
from pypixxlib.propixx import PROPixxCTRL #insert your device here
ppc = PROPixxCTRL()
ppc.open()

#First, we define the pixel sequence we are waiting for, the pixeTrigger. In 
#this case, our  trigger is a series of 8 red and green pixels in the top corner 
#of our image. In Python, the pixel trigger RGB values are passed as a single 
#vector, ie [R1, G1, B1, R2, G2, B2, etc]. 
#We use the numpy 'tile' function #to repeat our [red, green] pattern four times 
#to generate the full trigger.
pixelPattern = [255, 0, 0, 0, 255, 0] #1 red and 1 green pixel
pixelTrigger = list(np.tile(pixelPattern,4))

#Next, we set our desired digital output. Let’s say we want to set DOut 4-7 to 
#high, and everything else  to low. This command is stored in the local register 
#for now. We use binary to represent all 24 digital outputs and set positions 
#4-7 to 1. The int() command converts this value to one that can be read by the 
#device.
doutValue = int('000000000000000011110000', 2)
bitMask = 0xffffff
ppc.dout.setBitValue(doutValue, bitMask)

#Nothing has happened on the device register yet. Let’s write an update to the 
#device register on the next appearance of our pixel sequence, i.e., when our 
#target appears.
timeout = 60 #frames
triggerLength = int((len(pixelTrigger)/3))
ppc.writeRegCacheAfterPixelSync(triggerLength, pixelTrigger, timeout)