PiVR has been developed by David Tadres and Matthieu Louis (Louis Lab).
5. PiVR Software Manual¶
If you have the High LED power version of PiVR you must take care to properly shield yourself and others from the potentially very strong LED light to protect eyes and skin!
Several options will open a pop-up. You must close the pop-up in order to interact with the main window.
The software has different functionality if run on a Raspberry Pi as compared to any other PC. This software manual is for the Raspberry Pi version of the software
5.3. Preparing a Time Dependent Stimulus File¶
In your PiVR folder you can find a folder called ‘time_dependent_stim’. On a fresh install it is supposed to contain a single file: blueprint_stim_file.csv
When you open it with, e.g. excel or your csv viewing program of choice you’ll see that there are 5 columns and many rows:
The first Column (A) is the frame number. E.g. if you are recording at 30 frames per second the row 2-32 will define what’s going on in that time.
The second column defines what Channel 1 is doing at a given frame. 0 means the light is completely OFF. 100 means the light is completely ON. A number in between, e.g. 50 means that the light is on at 50/100=50%
The third (Channel 2), the fourth (Channel 3) and the fifth (Channel 4) use the same principle for the other channels.
It is important to notice that the stimulation file needs to be defined on a very low level: Frame Number. The same stimulus file will give different stimulations depending on the framerate. Therefore:
Decide on a framerate for you experiment, as an example we’ll say you decide on 30fps
Decide on a length of your experiment, for example 20 seconds
Decide on the stimulation pattern, e.g. you want Channel 1 to be OFF for the first second and Channel 2 to be ON for the first second. Then you want to switch, Channel 1 is ON for 1 sec, Channel 2 is OFF for 1 sec
You will need to set the first 30 (framerate * length of stimulus) rows of Channel 1 to 0
And you will need to set the first 30 (framerate * length of stimulus) rows of Channel 2 to 100
As you don’t care about Channel 3 and 4 you can leave it at zero
At row # 2 (since you start at row #2 in excel) or frame # 30 (first column) you set Channel 1 to 100 for 30 rows (framerate * length of stimulus) to turn it ON and Channel 2 to 0 to turn it OFF
If you do not define enough rows for your experiment, e.g. if you want to run the 20 seconds experiment at 30frames per second but you only define what happens during the first 15 seconds (by only going to row 15*30=450 instead of row 20*30=600) the last value for each channel will be propagated, e.g. if row 450 is set to 100 and row 451 to 600 are not defined the value 100 will be used for the rest of the experiment.
If you define more rows than you need for your experiments only the stimulation up to the point you record are used (this will behave as you probably expect)
5.4. Set Pixel/mm¶
In order to set Pixel/mm for your resolution, press the ‘Options’ Menu in the Menu Bar. Then select ‘Define Pixel/mm’
In the popup window you will see features:
The resolution you are currently using. The defined value will only be valid for this resolution
The Left and right cutoff slider. By moving them you can measure the distance.
A slice of the image taken by the camera. You want to put something you can measure horizontally before the camera.
A text field to enter a length you want to measure.
Below an example of an adjusted distance configuration window. Once you are satisfied with the adjustments you’ve made hit the quit button.
5.5. Adjust image¶
In order to set any options related to the image, press the ‘Options’ Menu in the Menu Bar. Then select ‘Optimize Image’.
This popup should being used to set up the image in the optimal way:
Turn the camera on (‘Cam On’) if it’s not on already
Adjust the preview size so that you can comfortably see both the preview and the popup.
Set the framerate as desired.
Press the ‘Update Preview Framerate’ button
Set the resolution you’d like to use for the recording.
Make sure the autoexposure button says ‘autoexp on’.
Turn the Backlight Intensity up. It is normal to only see something above 150’000. 400’000-500’000 is often a good value to choose.
If you have Backlight 2 intensity on one of the GPIOs (see define GPIO output channels) you can also adjust Backlight 2 intensity at this point.
To test your output channels, slide the appropriate slider to the right. At the beginning of any experiments these will be turn off again. To keep a stimulus ON for the duration of the experiment use the Backlight 2 intensity.
5.5.1. Set up optimal image¶
In order to set up optimal image parameters I usually do the following:
Turn ‘Cam On’
Set ‘autoexp on’
Pull ‘Backlight Intensity’ slider all the way to the left (Image will be dark)
Now pull the ‘Backlight Intensity’ slider to the right. As soon as I see an image in the camera I go another 100‘000 to the right - this way I’m not at the lower detection limit of the camera.
Then I turn ‘autoexp off’
Often it can improve the image if I pull the ‘Backlight Intensity’ slider a bit more to the right, effectively overexposing the image a bit.
5.6. Define GPIO output channels¶
In order to define GPIO output channels for your resolution, press the ‘Options’ Menu in the Menu Bar. Then select ‘define GPIO output channels’.
The images on the far left indicate which of the outputs on the left of your setups are which GPIO (e.g. the one closest to the LED power input is GPIO#18).
There are 4 GPIO’s that can be used to control LEDs: GPIO#18, GPIO#17, GPIO#27 and GPIO#13. GPIO#18 and GPIO#13 are special as they are the only ones that are capable of using PWM frequencies above the kilohertz range.
Channel 1 is always defined as the channel that is used for the Virtual Arena experiments.
Channel 1, Channel 2, Channel 3 and Channel 4 can be seperately adressed using the time dependent stimulus files.
5.7. Turn Debug Mode ON/OFF¶
In order Turn Debug Mode On or Off press ‘Options’ Menu in the Menu Bar. Then go on ‘Turn Debug Mode…’ and select either ‘OFF’ or ‘ON’.
5.8. Select Animal Detection Mode¶
In order Define the Animal Detection Method press ‘Options’ Menu in the Menu Bar. Then press ‘Animal Detection Method’.
When in either ‘Online Tracking’ or ‘Closed Loop Stimulation the animal needs to be detected. There are 3 modes that can be used to detect the animal. For most cases Mode 1 (Standard) will be fine. If you need a clear background image consider Mode 2 or Mode 3.
5.9. Select Organism¶
In order select an organism press ‘Options’ Menu in the Menu Bar. Then go on ‘Select Animal’ and select your animal.
5.10. Updating the software¶
In order to update the software on your RaspberryPi, press the ‘File’ Menu in the Menu Bar. Then go on ‘Update Software’.
Please make sure you are connected to the Internet when updating.
This will first update our Linux by calling:
Next, it will download the newest version from the gitlab repository by calling:
5.11. High/Low Power LED switch¶
In order to choose between High and low Power LED setups press ‘Options’ Menu in the Menu Bar. Then go on ‘High Power LEDs’.
Select either Standard or High power version depending on the setup you have.
5.12. Select Body Part for VR stimulation¶
When running virtual reality experiments the cells you are interested in could be at different places of the animal.
PiVR allows you to present the virtual reality depending on different body parts identified during tracking.
You may choose different body parts that are defined during tracking.
As the difference between centroid and midpoint is not straightforward, please see here for an explanation.
The Head (standard) will probably make a lot of sense in many experiments as a lot of sensory neurons of many animals are located there. However be aware that the Head/Tail classification algorithm is not perfect and does make mistakes. There is no option to correct for wrong head/tail assignment during the experiment!
The Centroid is probably the most consistently correct point during tracking. Please see here to see how it is defined.
The Midpoint is similar to the centroid, but can be different in flexible animals such as fruit fly larvae.
The tail is is the final option to choose from. We have used the presentation of the virtual reality based on tail position as a control in the past.
5.13. Animal Color Selection¶
Depending on your experimental setup, the animal can either be dark on white background due to transillumination, or white on dark background due to side illumination.
The standard setting is dark on white. If you need to change this setting, go to Options->
Now just press the button above the image that describes your experiment.