Screen lights stimuli demo


The below script demonstrates how to use visual stimuli in behavioural assays, such as lights and images on the screen. The tutorial explaining how to write a Zanscript is based on this demo script.

Top

Script explanation

The script is split into several parts to explain how to write the zanscript (the coding language) to build a service that will use the built-in visual stimuli during an experiment. For more details about screen coordinates see the illustrated description in the FUNCTIONS section of the Zanscript syntax manual.

INCLUDE ZSYS
 
DEFINE TRIALS 1
DEFINE STRIPE_TRIALS 3
DEFINE SCROLLTIME 8 
DEFINE QUARTER_SCROLLTIME 2
DEFINE WAIT_TIME 6 
DEFINE UNIT_TIME 3
 
DEFINE SPRITE 5 
DEFINE SPRITE_IMAGE 520 
 
DEFINE CIRCLE 1
DEFINE SQUARE 2

The DEFINE commands at the top of the script apply values to actions later used in the script, in this case, the number of trials, amount of time in seconds, the use of SPRITEs (used to produce images on the screen) and enable the shapes - circle and square - to be included in the script.

SETCOLOUR(10,0.01,0.01,0.01) 
 
SETLIGHT(LIGHT1,SQUARE,300,500,1000) 
SETLIGHT(LIGHT2,SQUARE,1300,500,1000)
 
SETLIGHT(LIGHT8,SPRITE,0,500,0) 
SETLIGHT(LIGHT9,SPRITE,0,500,0) 
SETLIGHT(LIGHT10,SPRITE,0,500,0) 
SETLIGHT(LIGHT11,SPRITE,800,0,0) 
 
LOAD(SPRITE_IMAGE,"8:blue_stripe_vertical") 
LOAD(SPRITE_IMAGE,"9:blue_stripe_vertical") 
LOAD(SPRITE_IMAGE,"10:blue_stripe_vertical") 
LOAD(SPRITE_IMAGE,"11:danio_small")

The SETCOLOUR command enables you to change how an image is lit from the screen, in this instance this command will be used to change how LIGHT10 (which is the SPRITE bitmap, the blue bar image) is lit, so it will appear black.

The first two SETLIGHT commands position square images on the screen, the first two numbers are the coordinates of their centre, and the third number is the size (in pixels).

The next four SETLIGHT commands tell the unit to look for a bitmap (.bmp) image from the Assets directory, label it as LIGHT8 - 10 and load this in the position as indicated by the screen coordinates for its centre (first 2 numbers) and size (0 will keep original size).

The LOAD command tells the unit which .bmp image should be used for which light, i.e. LIGHT8 will be the asset "blue_stripe_vertical" and LIGHT11 will be "danio_small".

ACTION MAIN
 
 LIGHTS(ALL,OFF)
 INVOKE(OVERHEAD_LIGHTS,TRIALS)
 INVOKE(FISH_MOVEMENT,TRIALS)
 INVOKE(STRIPE_MOVEMENT,STRIPE_TRIALS)
 LIGHTS(ALL,OFF)
 INVOKE(BLOCK_COLOURS,TRIALS)
 LIGHTS(ALL,OFF)
 
COMPLETE

The next set of ACTION MAIN commands (above) details the order of the whole experiment.

At the beginning and end all the lights all turned off.

The experiment comprises four parts, First OVERHEAD_LIGHTS is INVOKED and will repeat a number of times as DEFINED in TRIALS at the top of the script. The other 3 parts will run sequentially in the order that they are INVOKED in the script. Each will also repeat for a number of times as defined by TRIALS.

COMPLETE indicates that the ACTION has finished.

ACTION OVERHEAD_LIGHTS
 
 LIGHTS(LIGHT16,red)
 WAIT(1)
 LIGHTS(LIGHT16,green)
 WAIT(1)
 LIGHTS(LIGHT16,blue)
 WAIT(1)
 LIGHTS(LIGHT16,white)
 WAIT(1)
 LIGHTS(all,off)
 
COMPLETE

LIGHT16 is the overhead light and it can be set to come on in four different colours, red, green, blue and white, as specified.

The overhead light is turned on as red, after a one second interval, the light changes to green and so on until all the lights are turned off with command LIGHTS(all,off).

ACTION FISH_MOVEMENT 
 
 LIGHTS(LIGHT11,ON) 
 PANLIGHT(LIGHT11,800,1000,SCROLLTIME) 
 WAIT(WAIT_TIME) 
 LIGHTS(LIGHT11,OFF) 
 
 LIGHTS(LIGHT11,MAGENTA) 
 PANLIGHT(LIGHT11,1600,0,SCROLLTIME) 
 WAIT(WAIT_TIME)
 LIGHTS(LIGHT11,OFF)
 LIGHTS(all,off) 
 
COMPLETE

LIGHT11 comes on - as defined in the first section, this is a 'sprite', a .bmp image, loaded in the Assets directory, called "danio_small" (in this case it is a small fish)

This image pans across the screen from the position where it was originally set, as instructed by the SETLIGHT command in the first section, to the new position (co-ordinates 800,1000 on the screen). It will pan across the screen in the time as DEFINED at the top of the script as SCROLLTIME in seconds.

The unit will WAIT for the number of seconds as defined as WAIT_TIME at the top of the script before turning off LIGHT11. This period of time must be at least as long as the time alloted for the image to pan across the screen (i.e. the WAIT_TIME is 1 second longer than the SCROLLTIME) if you want the image to reach the location specified.

ACTION STRIPE_MOVEMENT 
 
 LIGHTS(LIGHT1,WHITE)
 LIGHTS(LIGHT2,WHITE)
 
 SETLIGHT(LIGHT8,SPRITE,0,500,0) 
 LIGHTS(LIGHT8,ON) 
 PANLIGHT(LIGHT8,1800,500,SCROLLTIME) 
 WAIT(QUARTER_SCROLLTIME) 
 
 SETLIGHT(LIGHT9,SPRITE,0,500,0) 
 LIGHTS(LIGHT9,10) 
 PANLIGHT(LIGHT9,1800,500,SCROLLTIME) 
 WAIT(QUARTER_SCROLLTIME) 
 
 SETLIGHT(LIGHT10,SPRITE,0,500,0) 
 LIGHTS(LIGHT10,ON) 
 PANLIGHT(LIGHT10,1800,500,SCROLLTIME) 
 WAIT(QUARTER_SCROLLTIME) 
 
COMPLETE

The first commands turn a white light on the screen.

SETLIGHT, LIGHT8, a blue vertical bar (.bmp loaded in the assets directory) is positioned the front end of the screen. LIGHT8 then turns on, illuminated by the screen light and pans across the screen, reaching the coordinates 1800,500 in the SCROLLTIME.

After a WAIT periods defined in seconds as QUARTER_SCROLLTIME, the next light (LIGHT9) pans across the screen. This bar appears black because of the command - LIGHTS(LIGHT9,10) - as the control for how the image is lit is set in the first section after the command SETCOLOUR(10,0.01,0.01,0.01).

LIGHT10, follows after another WAIT period

This ACTION is repeated 3 times (following the ACTION MAIN command - INVOKE(STRIPE_MOVEMENT,STRIPE_TRIALS), and the previous DEFINE command - STRIPE_TRIALS 3).

ACTION BLOCK_COLOURS
 
 LIGHTS(LIGHT1,BLUE) 
 LIGHTS(LIGHT2,GREEN) 
 WAIT(UNIT_TIME) 
 LIGHTS(LIGHT1,GREEN) 
 LIGHTS(LIGHT2,BLUE) 
 WAIT(UNIT_TIME)
 LIGHTS(ALL,OFF) 
 LIGHTS(LIGHT1,BLUE) 
 LIGHTS(LIGHT2,BLUE)
 WAIT(UNIT_TIME)
 LIGHTS(LIGHT1,GREEN) 
 LIGHTS(LIGHT2,GREEN)
 WAIT(UNIT_TIME)
 LIGHTS(ALL,OFF)
 
COMPLETE

LIGHT1 fills the front half of the screen and LIGHT2 fills the back half of the screen. The position and size of the lights is defined in SETLIGHT commands found earlier in the code.

The colours, blue and green, switch ends. The screen is then all blue, and then all green. There is a WAIT period between colour changes defined at the top of the script as UNIT_TIME in seconds.

The lights are then turned off and the section is completed.

Top

Script download

To download the stimulus_lights demo script as a .zs file (file type Zantiks software reads), choose the Save File As option in the right-click dialogue box. Clicking on the script name hyperlink will open a read-only version of the script. You will also need to have the assets used in the script saved into the unit's Asset directory.

Script download:
stimulus_lights_demo.zs

Asset downloads:
blue_stripe_vertical.bmp
danio_small.bmp

Top

Video demo

The video is a clip from the lights test and shows how colours, images and shapes can be displayed on the screen.

Demonstration of the light stimulation script running in the AD unit

Top

Making bitmaps

To use SPRITES for the display of images on the screen, the image must first be made into a bitmap file and loaded into the Asset Directory.

A bitmap can be made in image software such as windows paint or photoshop and then saved as a .bmp file. Bitmaps are always loaded into the asset directory as rectangles. As such, if your image is a cut out of something non-rectangular it must also have a blue background (i.e. no red or green) to make a rectangular image. An example of a bitmap which could be used as a SPRITE is shown below.

Danio Small
Example of a bitmap file which can be used as a SPRITE to display stimuli on the screen

The blue background will not show on the screen display. The bitmap featured above has been used in the Video Demo on this page.