= img2video (deprecated since r2718)=
== Overview ==

img2video is a wrapping tool for converting images of many types into video files using Mencoder and gifsicle. It has been developed as a ksh script for the animation of DVRP, VAPOR (TIFF images) and NCL-plotted data (EPS images). You can find img2video in your trunk/SCRIPTS/img2video folder (available since r586).

== Requirements ==

img2video requires the !ImageMagick and the Mencoder package  (contained in Mplayer)  as well as the package gifsicle.\\
\\
The input files have to be numbered (e.g. “karman0000” - “karman3999”). Missing files will be usually skipped without further notice, so please keep an eye on the completeness of your files. In general, single missing images will not affect the animation significantly (due to frame rates of at least 25fps). If you create animated gifs, warning messages will show up, if files are missing. To provide a fluently playing video, you should provide 25 single images (=frames) per second (25 fps).\\

== User instructions ==

1. Prepare a folder with your input files. \\e.g. “/localdata/dvrp/video” containing the files “image0000.tiff”  to “image3999.tiff” in TIFF format (as used by the DVRP software).

2. Run img2video with at least the -i and -n parameter from command line, \\e.g. {{{img2video -i /localdata/dvrp/video -n image}}}. You can get a short list of all parameters from command line typing {{{img2video ?}}}.\\\\Full list of parameters with description:\\[[#a|-a..]] [[#c|-c..]] [[#C|-C..]] [[#f|-f..]] [[#h|-h]] [[#i|-i..]] [[#k|-k]] [[#n|-n..]] [[#o|-o..]] [[#r|-r]] [[#R|-R]] [[#s|-s..]] [[#S|-S..]] [[#t|-t..]] [[#w|-w]] [[#X|-X]] \\
||='''Parameter Name'''  =||='''Default Value'''  =||='''Explanation'''  =||
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#a '''-a.. fps''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
25
}}}
{{{#!td
Frames per second
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#c '''-c.. codec''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
mpeg4
}}}
{{{#!td
Desired video format.\\
\\
Currently supported codecs are:\\
* flash (Flash Video)
* mpeg (MS MPEG 4.2, avi container)
* mpeg4 (MPEG4, avi container)
* mjpeg (Motion JPEG, avi container)
* gif (Animated GIF)
* ffv1 (lossless encoding, avi container)
* wmv2 (Windows Media Video 2)
* xvid (avi container)
\\
Flash is the best choice for web pages (~18mb for 3min).\\
\\
Animated GIF is recommended since it can be played out-of-the box in most browsers.\\
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#C '''-C.. colors''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
256
}}}
{{{#!td
Number of colors in case [[#c|-c..]] is set to gif.
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#f '''-f.. filename''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
Internally set
}}}
{{{#!td
Output file name.\\
\\
If this parameter is not set, img2video will generate a nice filename for you, e.g. “karman_50fps_mjpeg”.
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#h '''-h''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
N/A
}}}
{{{#!td
Flag parameter to enable high-quality output
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#i '''-i.. input_path''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
.
}}}
{{{#!td
Path to the input path (necessary),\\
e.g. “/localdata/dvrp/karman”
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#k '''-k''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
N/A
}}}
{{{#!td
Use this flag parameter, if you would like to delete the converted image files at the end of the run.
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#n '''-n.. run_identifier''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
""
}}}
{{{#!td
The basename of your files (necessary), e.g. "karman".
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#o '''-o.. output_path''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
input_path
}}}
{{{#!td
Path to the output_folder, e.g. "/data/username/dvrp".
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#r '''-r''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
N/A
}}}
{{{#!td
Use this flag parameter to encoding videos with already existing converted files in your “output_path/run_identifier/”
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#R '''-R''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
0
}}}
{{{#!td
Rotate images by given angle [°]
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#s '''-s.. scale_width''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
1024
}}}
{{{#!td
Scaling width.\\
\\
The original sized images width x height will be resized for the video output to  scale_width x scale_height. scale_height is calculated internally to keep the aspect ratio.
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#S '''-S.. video_speedup''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
1
}}}
{{{#!td
Video speed-up.\\Accelarate the video by a given factor.
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#t '''-t.. file_type''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
tiff
}}}
{{{#!td
Image file type (input).
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#w '''-w.. filename''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
N/A
}}}
{{{#!td
Filename/location of a watermark.\\
\\
For IMUK, there are already a black (imuk_wm_black.png) and a white (imuk_wm_white.png) watermarks
}}}
|----------------
{{{#!td style="vertical-align:top;width: 150px"
[=#X '''-X''']
}}}
{{{#!td style="vertical-align:top;width: 100px"
N/A
}}}
{{{#!td
Use this flag parameter to enable additional debug/error messages.
}}}

3. When img2video is finished, check your output_path. If no error occurred, you will find your animation as well as a preview image. 

== Notes ==

The conversion of the original images (e.g. from TIFF) takes some time, especially when using animated gif. Thus, using the “-k” parameters should only be used with care, otherwise your JPEG files will be lost. Running img2video on the file system where your input files are located is the best choice. The output_path should be located on the same file system. This will speed up the conversion.\\
\\
The preview image might be helpful and is necessary for the web page presentation. It shows the last frame of the simulation.\\
\\
For the file conversion, the input files don't need to have file extensions (karman***** will work as good as karman*****.tiff), if the option "-t" was set properly.\\
\\
img2video uses cycle numbers if an video with the same filename already exists, e.g.  {{{cube_1acc_mpeg.avi -->  cube_1acc_mpeg_1.avi}}}.

== Examples ==

Example joblines for producing videos from images located in the folder “/localdata/dvrp/karman”, named “karman0000” to “karman3999”  might look like this:

1. Standard settings for a mjpeg animation:\\{{{img2video -c mjpeg -i /localdata/dvrp/karman -n karman}}}

2. Settings for an animated gif with a speed-up of factor 2:\\{{{img2video -c gif -i /localdata/dvrp/karman -n karman -S 2}}}

3. Settings for an animated gif of a few EPS files (2 images per seconds displayed):\\{{{img2video -c gif -i /localdata/dvrp/karman -n karman -t "eps" -a 2}}}

Example of the img2video shell interface\\{{{img2video -n "cube" -i /home/user/scripts/img2video/testfilm -c mpeg}}}\\\\
{{{
#--------------------------------------------------------------#
| img2video  Rev: 1 $            Fri Jul 23 18:02:34 CEST 2010 |
|                                                              |
| Initialization parameters                                    |
| Jobname:            cube                                     |
| Input path:         /home/user/scripts/img2video/testfilm    |
| Output path:        /home/user/scripts/img2video/testfilm    |
|                     /cube                                    |
| Video codec:        mpeg (msmpeg4v2)                         |
| Input file type:    tiff                                     |
| Video speed-up:     1                                        |
| fps:                25                                       |
| Scaling video to    1024px width                             |
| Watermark           disabled                                 |
| HQ-options:         disabled                                 |
|                                                              |
| Additional settings                                          |
| - Image files will be stored at the end.                     |
| - img2video will generate new images.                        |
|                                                              |
| Video will be saved as cube_1acc_mpeg.avi                    |
|                                                              |
#--------------------------------------------------------------#
 *** Creating directory: /home/user/scripts/img2video/testfilm/
     cube/images_jpg... done.
 *** Outdated images will be deleted in /home/user/scripts/img2video/
     testfilm/cube/images_jpg... done.
 *** Converting images... done.
 --> Converted 101 images.
 *** Encoding video... done.
 --> All actions finished. Video saved as /home/user/scripts/
     img2video/testfilm/cube/cube_1acc_mpeg.avi.
}}}