.TH r.out.mpeg
.SH NAME
\fIr.out.mpeg\fR \- Raster File Series to MPEG Conversion Program 
.br
.SH SYNOPSIS
\fBr.out.mpeg\fR
.br
\fBr.out.mpeg help\fR
.br
\fBr.out.mpeg\fR \fB[-qc]\fR \fBview1=\fIname[,name,...]\fR 
   \fB[view2=\fIname[,name,...]]\fR \fB[view3=\fIname[,name,...]]\fR 
   \fB[view4=\fIname[,name,...]]\fR \fB[output=\fIname]\fR \fB[qual=\fIvalue]\fR

.SH DESCRIPTION
\fIr.out.mpeg\fR is a tool for combining a series of GRASS raster files into
a single MPEG-1 (Motion Pictures Expert Group) format file.  MPEG-1 is a
"lossy" video compression format, so the quality of each resulting frame of 
the animation will be much diminished from the original raster image.  The
resulting output file may then be viewed using your favorite mpeg-format
viewing program.
.LP
The user may define up to four "views", or sub-windows, to animate 
simultaneously.  e.g., View 1 could be rainfall, View 2 flooded areas,
View 3 damage to bridges or levees, View 4 other economic damage, all 
animated as a time series.  A black border 2 pixels wide is drawn 
around each view.  There is an arbitrary limit of 100 files per
view (100 animation frames).  Temporary files are created in the conversion
process, so lack of adequate tmp space could also limit the number of 
frames you are able to convert.
.LP
The environment variable
GMPEG_SIZE is checked for a value to use as the dimension, in pixels, of
the longest dimension of the animation image.  If GMPEG_SIZE is not set,
the animation size defaults to the rows & columns in the current GRASS
region, scaling if necessary to a default minimum size of 200 and 
maximum of 500.  These size defaults are overridden when using the -c flag 
(see below).  The resolution of the current GRASS region is maintained,
independent of image size.  Playback programs have to decode the compressed
data "on-the-fly", therefore smaller dimensioned animations will provide 
higher frame rates and smoother animations.
.LP
UNIX - style \fBwild cards\fR may be used with
the command line version in place of a raster file name, but it \fImust 
be quoted\fR.
.LP
Example:
.br
r.out.mpeg view1="rain[1-9]","rain1[0-2]" view2="temp*"
.LP
If the number of files differs for each view, the view with the fewest files
will determine the number of frames in the animation.
.LP
.SH "COMMAND LINE OPTIONS"
.LP
Flags:
.IP \fI-q\fR
Quiet - suppress progress report
.IP \fI-c\fR
Convert "on the fly", uses less disk space by using \fIr.out.ppm\fR with stdout
option to convert frames as needed instead of converting all frames to
ppm before encoding.  Only use when encoding a single view.  Use of this
option also overrides any size defaults, using the CURRENTLY DEFINED 
GRASS REGION for the output size.  So be careful to set region to a 
reasonable size prior to encoding.
.LP
Parameters:
.IP \fIview1\fR
Raster file(s) for View1
.IP \fIview2\fR
Raster file(s) for View2
.IP \fIview3\fR
Raster file(s) for View3
.IP \fIview4\fR
Raster file(s) for View4
.IP \fIoutput\fR
Name for MPEG output file (default gmovie.mpg)
.IP \fIqual\fR
Quality factor (1-5) (default 3)
.IP
A quality value of qual=1 will yield higher quality images, but with less
compression (larger MPEG file size).  Compression ratios will vary depending 
on the number of frames in the animation, but an MPEG produced using
qual=5 will usually be about
60% the size of the MPEG produced using qual=1;

.SH BUGS
MPEG images must be 16-pixel aligned for successful compression, so
if the rows & columns of the calculated image size (scaled, with borders
added) are not evenly divisible by 16, a few rows/columns will be cut 
off the bottom & right sides of the image.  
.br
The MPEG format is optimized
to recognize image MOTION, so abrupt changes from one frame to another
will cause a "noisy" encoding.

.P 
.SH NOTES
This program requires the program \fImpeg_encode\fR : 

                MPEG-1 Video Software Encoder
                (Version 1.3; March 14, 1994)

Lawrence A. Rowe, Kevin Gong, Ketan Patel, and Dan Wallach
Computer Science Division-EECS, Univ. of Calif. at Berkeley
.br
Available by anonymous ftp from: s2k-ftp.CS.Berkeley.EDU
.LP
Use of the -c flag also requires the program \fIr.out.ppm\fR with the
stdout option, which is available by anonymous ftp from: moon.cecer.army.mil.
.SH AUTHOR
Bill Brown, U.S. Army Construction Engineering Research Laboratories
(brown@zorro.cecer.army.mil)