*************************************************************************
************		Welcome to VirtualRetina	*****************
************			version 2.1	 	*****************
*************************************************************************

		Spiking, large-scale retina simulation software.

			Author : Adrien Wohrer
			Institution : ODYSSEE, INRIA Sophia Antipolis
			Contact : Adrien.Wohrer@sophia.inria.fr
			Project started december 2004.


****** README for the Applications directory  : appli/ ******************

This directory contains the sources for the binary files you can use directly.
Type -h after a program to get a brief description and list of options.

This README contains: 
(I)  descriptions for all application programs.
(II) some examples of use.



A Research Report (also submitted to Journal of Computational Neuroscience)
explains the retina model, and might be useful for you to better understand the role of the (numerous) parameters in the xml file. Find it at:

https://hal.inria.fr/inria-00160716/en/



*************************************************************************
*************************************************************************
************	 (I) Description of the programs	*****************
*************************************************************************
*************************************************************************




*************************************************************************
***************************  Retina *************************************
*************************************************************************


The main simulation program.
Takes a 3d-sequence (space and time), or a set of images forming a sequence, as input. Produces sets of spike trains or, if you did not ask for spikes, analogic spatio-temporal sequences corresponding to the 'activities' of ganglion cells.

Most important option is -ret retina_file.xml, where retina_file.xml must define the whole architecture of your retina! 

Some example retina files are provided by default. They are named EXAMPLE_*, and can be used directly. Examples of use are given in part (II) of this README.

But to create YOUR OWN retina, read file SPECIFICATION_RETINA.xml !
It presents all the ways to customize your retina, and rapid explanations of the different parameters for each stage of processing. READ IT!
PS: it's not bound to be directly loaded by the Retina program.



*************************************************************************
**************************  ReconstructRetina ***************************
*************************************************************************


Reconstruct a video sequence from spike trains emitted by the previous program.

Option -ch is useful if you simulated simultaneously several layers of ganglion cells (e.g. ON parvo, OFF parvo, ON magno, OFF magno) and want to represent only the emissions of a particular number of channels. Type -h for details.

Option -p provides two possible processes for reconstruction:
-p 0 will associate each emitted spike to a 3d cube in the reconstructed sequence, of spatial width given by -w pixels and of temporal latency given by -lat frames.
-p 1 will associate each emitted spike in the fovea to a circular spot of radius -w pixels. Outside of fovea (if this outside exists), the radius augments to counterbalance the decreasing cell density.

For both processes, the intensity of each added 'one-spike-spot' is equal to 1/(3d_size_of_spot)/local-cell-density. As a result of this last division, the number stocked in each pixel of the reconstructed sequence has the dimension of an AVERAGE FIRING RATE PER SPIKING CELL. 
If option -nodn (for no_density_normalize) is written, then the intensity of each spot is only 1/(3d_size_of_spot). In which case the number stocked in each pixel of the reconstructed sequence has the dimension of an AVERAGE FIRING RATE PER PIXEL. And you dont see a... sheep... in regions of the image with lower cell density. Not recommended.



*************************************************************************
***************************** TestGanglionCell **************************
*************************************************************************


A wrapper for program 'Retina' in the particular case where you want to test a SINGLE, SPIKING ganglion cell with noise in its spike generation, and reconstruct an averaged firing rate. The code for this program can serve as a basis for you to simulate "intracellular" properties of ganglion cells.

By default, time courses are represented for:
- opl current
- ganglion input current
- ganglion average firing rate.
Use option -nodisp if you want no display.

Options -p and -lat allow you to customize the linear kernel used to reconstruct the average firing rate. Type -h for more details.

See examples of use in ../experiments/


*************************************************************************
******************************* shapleyVictor ***************************
*************************************************************************


A more experimental program, to test the responses of a single ganglion cell, with contrast-gain-control, to Shapley-Victor multi-sinus stimuli at different contrsts (reproduction of the first experiment of article 'Shapley-Victor 78').

See example of use in ../experiments/multi-sinus_shapley-victor78/



*************************************************************************
***************************** Helper applications ***********************
*************************************************************************


viewVideo: A simple video viewer. Useful to watch input sequences, or reconstructed sequences. To be honest, you might also want to use program inrcast, which is one of the applications proposed in the examples of CImg sofwtre. BUT this program also allows you to watch the sequence at any speed you like, by using option -s.

lumImage: allows you to change the mean luminosity and contrast of a sequence before feeding it to the retina.

Grating: creates a moving bar stimulus. No, I'm joking. It creates a GRATING stimulus.




*************************************************************************
*************************************************************************
************		 (II) Examples of use		*****************
*************************************************************************
*************************************************************************

In this example, all commands are launched directly from the 'bin' directory.


*************************************************************************
************** Answer of a spikeless, linear, retina  *******************
*************************************************************************


********Here is the sequence we are going to test:

viewVideo ../test/sequences/walking_finland/finland.10* -s 100	
	or, alternatively, by directly loading the 3d-sequence in .inr format:
viewVideo ../test/sequences/walking_finland/seq.inr -s 100

********Launching retinal processing:

Retina -ret EXAMPLE_linear_noSpikes.xml ../test/sequences/walking_finland/finland.10* -r 1 -nS 1
	
	if you check file EXAMPLE_Retina_linear_noSpikes.xml , you will see that it only contains a linear Outer Plexiform Layer, and that it processes images with a simulation time step of 40 ms.
	option -r 1 means that each input frame lasts 1 retinal time step (i.e. 40 ms)
	option -nS 1 means that retinal output is saved every 1 retinal time step, that is, every 40 ms.

********You can check the retinal output:

viewVideo ../tmp/oplFrames/opl_signal_0000* -s 40
	
	For this simple retina, the output is the opl, hence the name 'oplFrames' for the directory. The output frames are stored in .inr format with double precision, since the opl signal has typical magnitudes of value 1.0 only.


*************************************************************************
*********** Answer of a spiking retina with contrast gain control *******
*************************************************************************



********Here is the sequence we are going to test (actually it is just a single image):

viewVideo ../test/sequences/rocks_2contrasts.pgm
	it has been numerically modified to display different averaged contrasts on its left and right part

********Launching retinal processing:

Retina -ret EXAMPLE_primateParvoMagno.xml ../test/sequences/rocks_2contrasts.pgm -r 100 -nS 8 -y 150 -savemap -outD ../tmp

	this time the retinal file contains:
		
	* SPIKING CELLS: at bottom of the xml file, there is a layer of ganglion cells, of total diameter 300. This diameter determines the size of all maps in the retina. This is why the retinal maps are smaller than the input image.
	A spiking output has been created with all the spikes emitted by the retina, as ../tmp/spikes.spk. 
	If you remove the ganglion layer definition in the xml file:
		- the 'ganglion current' map does not exist anymore
		- no spike file will be created (but file for the preceding simulation remains, unless you destroyed it before...)

	* A CONTRAST GAIN CONTROL scheme was also added, to provide invariance to the contrast. This is why retinal output is much more similar on the left and right sides than the input image was. 
	If you remove this contrast gain control stage in the xml file
		-the 'bipolar' and 'amacrine' maps do not exist anymore
		-the ganglion current is much more sensitive to contrast (it becomes linear with contrast)

	* A LOG-POLAR SCHEME : past a fovea of radius 50, retinal filtering becomes more blurry and, at the same time, the density of spiking cells in the ganglion layer decreases, with the same ratio.
	If you remove this log-polar scheme, retinal blurring becomes uniform (with same scales as in the fovea)

	retinal time step is smaller this time (5 ms), as required for the non-linear contrast-gain-control loop to be stable. But you can try to augment it a little and gain processing speed.
	option -y 150 : asks that the vertical center of the retina be 150 pixels below top of input image. If you remove it, the retina is automatically centered on the input image... and you will not see the sky anymore...
	option -r 100 : the single frame is repeated a hundred retinal time steps, that is, 500 ms.
	option -savemap: we also asked for ALL retinal intermediate maps to be saved... Most of the time you should not need this option, but... who knows? They were saved every -nS 8 retinal time steps, that is, every 40 ms.
	option -outD : we ask for all saved files to be saved in ../tmp (it is the default directory, anyway).

********To reconstruct the SPIKING retinal output:

ReconstructRetina -i ../tmp/simulation.txt -s 5 -p 1 -lat 10 -o ../tmp/reconstruction.inr

	Each frame of the reconstruction lasts 5 ms. Reconstruction process 1, with a latency of 10 frames=50 ms.

viewVideo ../tmp/reconstruction.inr -s 5
	
	 to visualize the reconstructed firing rate.


OK, NOW YOU CAN TRY THIS RETINA ON A MOVING SEQUENCE AS WELL!!




*************************************************************************
*******   REPRODUCTION OF SINGLE-CELL PHYSIOLOGICAL RECORDINGS    *******
*************************************************************************

are available in directory ../experiments/

