
                DEMOS TO CREATE MOVIES FROM NEURON

                          Alain Destexhe

           CNRS, UNIC (Bat-33), Avenue de la Terrasse,
                 91198 Gif-sur-Yvette, France

                      Destexhe@unic.cnrs-gif.fr
                     http://cns.iaf.cnrs-gif.fr


This package is running with the NEURON simulation program written
by Michael Hines and available at: http://www.neuron.yale.edu

The package illustrates how to create animated (mpeg or gif) movies
from NEURON.  The example taken generates an animation of the
somato-dendritic profile of membrane potential in a model of
thalamic reticular neuron, relative to the paper:

  Destexhe A, Contreras D, Steriade M, Sejnowski TJ and Huguenard JR.  
  In vivo, in vitro and computational analysis of dendritic calcium currents 
  in thalamic reticular neurons.  Journal of Neuroscience 16: 169-185, 1996.
  (see http://cns.iaf.cnrs-gif.fr in "publications")



  SYSTEM REQUIREMENTS
  ===================

To create the animated movies, one needs a series of packages in 
addition to NEURON.

1. ghostscript

Ghostscript is a public-domain postscript interpreter available in
LINUX distributions.

2. pstopnm and ppmtogif

The scripts pstopnm and ppmtogif are part of the PBMplus and Netpbm
packages, available in LINUX distributions.  pstopnm uses
ghostscript to transform postscript files into ppm format.  The
transformation to gif is then made using ppmtogif.



  GENERATING FRAMES USING NEURON
  ==============================

Creating an animatedd gif movie from NEURON simulations can be done
in the following steps: (a) save NEURON plots as postscript; (b)
convert postscript images into gif; (c) encode the gif files into
an animated gif.

Steps (a) and (b) can be done in NEURON if the commands "pstopnm"
and "ppmtogif" are available.  This is what shows the demo called
"re80movie.oc".  The demo creates a series of successive gif frames
from a NEURON simulation and name them: fram0.gif, fram1.gif, ...
in a directory called "frames".

To run this demo, do the following:
- run the NEURON program re80movie.oc
- set "Shape Style" to "Show Diam" in the shapeplot
(the "v" can be moved outside the plot using "move text" if needed)
- set the shapeplot in "Shape Plot" mode
- click on "run" The program will create a bunch of frames in
the "frames" directory.  

Note that generating frames can also be done using the print window
manager in NEURON.  In this case, uncomment the appropriate
commands in the oc file (replace the "g[sh].printfile..." by
"print_session..." command).  Then start the program and
select/arrange windows as desired on the paper icon of the PWM. 
Then run the program as above, the difference is that each frame
will contain the complete set of windows as arranged by the user. 
(this allows for instance to generate movies where both shape plot
and time plots appear - see examples in http://cns.iaf.cnrs-gif.fr)



  GENERATING THE MOVIE
  ====================

Once the set of frames is generated, then we need other programs to
generate an animated movie.  Here, the exact nature of the program
will depend on the operating system used (it is different in
Windows, Mac or LINUX).  The procedure below applies to a standard
distribution of LINUX (Ubuntu 12.04).

1) MPEG movies

In the linux distribution, an MPEG (or AVI) movie can be generated
from a set of GIF frames using the "ffmpeg" command.  Install this
command using the normal procedure, then go into the directory
of GIF frames, and enter the command:

 ffmpeg -qscale 5 -r 20 -b 9600 -i fram%d.gif movie.mp4

This will generate a MPEG4 movie based on the set of frames


2) GIF movies

Another possibility is to create an animated GIF movie from the set
of GIF frames.  To do this, first install the ImageMagick tools. 
This set of tools contain two useful commands called "animate" and
"convert".  The first command, "animate", can be used to have an 
online animation using the frames, and can be used to adjust the
parameters (in particular the delay). 

 animate -delay 2 -loop 0 fram?.gif fram??.gif fram???.gif

Once you are happy with the delay, then enter the command:

 convert -delay 2 -loop 0 fram?.gif fram??.gif fram???.gif movie.gif

which will create the animated GIF "movie.gif"


Note that there are many other programs to generate MPEG, AVI or
GIF movies from a set of frames.  For example there is a C program
called "whirlgif" (available as open source on the internet), which
can compile an animated GIF.   Please adapt the present program to
your needs or specific platform.

The files "movie.mp4" and "movie.gif" included here were created
using the two above procedures.



  CONDITIONS AND TROUBLESHOOTING
  ==============================

This demo is provided "as is" and is of free access - if you
experience problems installing the programs, please refer directly
to the authors of these programs.  If these commands are properly
installed, the demo should work straight.  If you notice errors or
important program updates, please send me a note, so that I can
update this README file if needed.




Alain Destexhe

CNRS, UNIC (Bat-33), 
Avenue de la Terrasse,
91198 Gif-sur-Yvette, France

email: Destexhe@unic.cnrs-gif.fr
http://cns.iaf.cnrs-gif.fr
