= Animating the results of a CompuCell3D simulation =

== Generate the snap shots ==
You will first need to tell CC3D (Player) to save screen shots during the simulation. Click on the Tools menu then select Configuration. As shown below, set the frequency you want screen shots saved, the dimensions of the saved file and the file location. It is often simplest to just use the default “CC3DWorkspace” folder, which is similar to C:\Users\<USERNAME>\CC3DWorkspace\. Note that if you are saving a lot of screen shots with large resolutions, you can consume a significant amount of disk space. 

{{attachment:CC3D _Settings.png|CC3D Setting Dialog}}

You then need to click on the camera icon in the Player window for all of the sub-windows that you want saved. To insure that the screenshots are saved you should start the run by clicking on (1) the Stop button (if it isn’t greyed out), (2) Single Step button to start the simulation, (3) the Camera Icon in the sub-window(s) you want to save, and finally (4) click on the Run button.

{{attachment:Click_on_Camera_icon.png|Click on the camera icon}}

== Files ==

The CC3D output will be written in a directory named after your project with a date time stamp. For example; C:\Users\<USERNAME>\CC3DWorkspace\YOUR_PROJECT_NAME_MM_DD_YYYY_HH_MM_SS.

{{attachment:CC3D_outptut_dir.png|File names and folder}}

Inside that directory will be a folder for each of the sub-windows that you clicked the Camera Icon on. The folders names will be based on the sub-windows name and some brief info on the sub-window such as 2D or 3D. The default window in Player is “Cell_Field” so you will often have a directory that starts with that if you had clicked on the Cell_Field sub-windows Camera Icon.

Within that folder will be all the image files in .png (portable network graphics) format. The files are named based on the folder name plus the Monty Carlo Step (MCS) that the file was written at.

{{attachment:png_files_2.png|pg file list}}

== Animate the files ==

=== Simple test animation on Windows ===

On a windows machine (I haven’t tried this on a Mac or Linux systems), you can get a rough idea of what the files will look like when animated. As shown below, switch the window view to show “Extra Large Icons”, and then resize the window so it is just a little bigger than one image. You can now use the up and down scroll arrows to animate the images. You’ll need to first scroll through all the images once to force Windows to generate the thumbnail images. 

{{attachment:Quick_animation_windows.png|Quick animation test in windows}}

=== Simple Animation on Windows ===

On a Windows machine you can browse to a folder of images, select the set of images and then right-click and choose "Create a new video". This will import the set of files into Windows Photos which can create a movie. You can also used Windows Movie Maker to create the movie.

=== Simple Animation ===

There are a number of tools for converting the set of .png files into basic animations. 

If you don’t want to install any software, or if you want the flexibility to work from Windows, Linux or Mac, there are a couple of very nice online animation tools. One such tool is '''ezgif''' at https://ezgif.com/apng-maker. This tool not only animates the files but it also lets you choose the output movie format, resize and/or clip the images, change the delay between images etc. The animation below was generated with ezgif, which also clipped and rescaled the images. 

{{attachment:falling_cell_vsmall.png}}

Another online tool is https://gifmaker.me/. '''Gifmaker''' is similar to ezgif, and both are easy to use.

=== Complex Animations ===

For more complex animations, the gold standard software is '''!ImageMagick''' (https://imagemagick.org/), which runs on Linux, Mac and Windows. !ImageMagick can create the animation, it can also recolor, resize, change frame rates and combine multiple sets of images into side by side animations, label images etc. In addition, ImageMagick can read and write a very wide range of image and movie formats. ImageMagick uses command line commands or script files to specify inputs, outputs and manipulations and can take some time getting used to. But if you have  a complex animation to create this is a great tool. 

==== Windows batch script ====
Below is a demonstration script (Windows batch) that makes a side by side animation using two sets of .png files.

{{{
@echo off
:: Demonstration ImageMagick script (Windows batch file) to animate two sets of images side by side
setlocal EnableDelayedExpansion

:: output directory for the intermediate images
mkdir combined_frames

:: This script is for the set of png files created by CC3D with these names:
:: Cell_Field_CellField_2D_XY_0_000000.png  
:: Cell_Field_CellField_2D_XY_0_000300.png
::    . . .
:: Cell_Field_CellField_2D_XY_0_040200.png
:: So the files go from zero, in steps of 300 up to 402000

:: The for loop parameters are: starting file number, step number, final file number
:: these values match the list of files shown above
for /L %%i in (0, 300, 40200) do (
     set "formattedValue=000000%%i"
     set "f1=.\Images_1\Cell_Field_CellField_2D_XY_0_!formattedValue:~-6!.png"
     set "f2=.\Images_2\Cell_Field_CellField_2D_XY_0_!formattedValue:~-6!.png"
     set "f3=.\combined_frames\combined_!formattedValue:~-6!.png"
echo "C:\Program Files\ImageMagick-7.0.10-Q16-HDRI\magick.exe" montage -geometry +1+1 -crop 150x600+225+0 !f1! !f2! !f3!
     "C:\Program Files\ImageMagick-7.0.10-Q16-HDRI\magick.exe" montage -geometry +1+1 -crop 150x600+225+0 !f1! !f2! !f3!
)
:: The above creates individual side-by-suide images for each frame
:: The below takes that set of images and makes a movie
:: You can also use other file extensions for the output, like .mpg or .mov isntead of .gif
"C:\Program Files\ImageMagick-7.0.10-Q16-HDRI\magick.exe" convert .\combined_frames\combined_*.png output_movie.gif
}}}
{{attachment:output_movie.gif|side by side movie|width=100px}}

==== Linux batch script ====
Below is a demonstration script (Linux batch) that makes a side by side  by side animation with captions using one, two or three sets of .png files. (here it just use the same file repeated 3 times.) The "for i" loop specifies that the file numbers turn from 0 to 7900 in steps of 100. The "%04g" says to pad i to 4 spaces with leading zeroes.

{{{
#!/bin/bash
    
mkdir Frames
for i in $(seq -f '%04g' 0 100 7900); 
do
    montage -geometry +1+1+1+1 -tile 3x1 -background Black -fill White -font Helvetica-Bold -pointsize 50\
	-label 0.080 0.080/Cell_Field_CellField_2D_XY_0_$i* \
	-label 0.120 0.120/Cell_Field_CellField_2D_XY_0_$i* \
	-label 0.160 0.160/Cell_Field_CellField_2D_XY_0_$i* \
    Frames/output$i.png
done
}}}

=== A more complex animation ===

Here we will animate four images streams from a CC3D simulation. We are using a modification of the Macro phage-Bacterium Chemotaxis script the simulates the Macrophages chasing the "smell" of the bacterium (green) and the bacterium (red) running away form the "smell" of the macrophage. In the CC3D screen shot below there are four graphics windows: upper left shows the two cells in a filed of boxes. Bottom left shows the track of the Macrophages. Top right shows the repulsion field generated by the Macrophage that the bacterium is running away from. Bottom right it the attractant field generated by by bacterium that the Macrophaoge is chemotaxing too. The zip file with this CC3D project is [[attachment:bacterium_macrophage_animation.zip|here|&do=get]]. The zip file also contains the four sets of screen shots from the graphics windows in CC3D if you need a test set of images for animation.

{{attachment:Macrophage-Bacterium_screenshot.png|Bacterium Macrophage Animation|width=500px}}

The animation we will create is:<<BR>>
[[attachment:output_movie_side_x4.gif|{{attachment:output_movie_side_x4.gif|Bacterium Macrophage Movie|width=900px}}|target=_blank&do=get]] 
<<BR>>(click for a larger version)

The original animation script was written by Josua Aponte-Serrano. Below is the windows version, and then a somewhat different Linux version.

==== Windows Bat ====
{{{
@echo off
:: Demonstration ImageMagick script (Windows batch file) to animate three sets of images side by side with captions and clipping
:: Underlying Linux batch created by Josua Aponte-Serrano <joaponte@iu.edu>
setlocal EnableDelayedExpansion

:: output directory for the intermediate images
mkdir Frames

:: The for loop parameters are: starting file number, step number, final file number
:: these values match the list of files shown above  (0,20,4980)
:: Note that for this simulation the mcs number in the filenames is a 4 digit string. The length is set by
:: CC3D based on the maximum number of MCS in the simulation.
for /L %%i in (0, 20, 4980) do (
     set "formattedValue=000000%%i"
     set "f1=.\Cell_Field_CellField_2D_XY_0\Cell_Field_CellField_2D_XY_0_!formattedValue:~-4!.png"
     set "f2=.\Cell_Center_Track_ScalarField_2D_XY_0\Cell_Center_Track_ScalarField_2D_XY_0_!formattedValue:~-4!.png"
     set "f3=.\ATTR_ConField_2D_XY_0\ATTR_ConField_2D_XY_0_!formattedValue:~-4!.png"
     set "f4=.\REPL_ConField_2D_XY_0\REPL_ConField_2D_XY_0_!formattedValue:~-4!.png"
     set "f5=.\Frames\combined_!formattedValue:~-4!.png"
     echo "                      >>>>>>>>>>>>>>>>> " !f1!
     "C:\Program Files\ImageMagick-7.0.10-Q16-HDRI\magick.exe" ^
        montage -geometry +1+1+1+1 ^
        -tile 4x1 ^
        -background White ^
        -fill Blue ^
        -font Arial ^
        -pointsize 25 ^
  	    -label "Cells: !formattedValue:~-6!" !f1! ^
	    -label "Macrophage Track" !f2! ^
	    -label "Attractant" !f3! ^
	    -label "Repelent" !f4! ^
        !f5!
    )
:: The above creates individual side-by-side images for each times step
:: The below takes that set of images and makes a movie 
:: (you could also use an online tool like https://ezgif.com/apng-maker)
:: You can also use other file extensions for the output, like .mpg or .mov instead of .gif

echo ""
echo "combining images into movie, this may take a while..."
"C:\Program Files\ImageMagick-7.0.10-Q16-HDRI\magick.exe" convert .\Frames\combined_*.png output_movie_side_x4.gif


:: To get a listing of all the fonts installed with your Imagemagick you can use:
::      "C:\Program Files\ImageMagick-7.0.10-Q16-HDRI\magick.exe" convert -list font
}}}


==== Linux script ====
This script creates the side by side images and puts them in the "Frames" folder but does not generate the animation.
{{{
#!/bin/bash
## Demonstration ImageMagick script (Linux batch file) to animate three sets of images side by side with captions and clipping
## Linux batch created by Josua Aponte-Serrano <joaponte@iu.edu>
    
mkdir Frames
for i in $(seq -f '%04g' 0 100 7900); 
do
    montage -geometry +1+1+1+1 -tile 3x1 -background Black -fill White -font Helvetica-Bold -pointsize 50\
	-label 0.080 0.080/Cell_Field_CellField_2D_XY_0_$i* \
	-label 0.120 0.120/Cell_Field_CellField_2D_XY_0_$i* \
	-label 0.160 0.160/Cell_Field_CellField_2D_XY_0_$i* \
    Frames/output$i.png
done
}}}

''more to come ... ''