r.out.mpeg  GRASS Reference Manual   r.out.mpeg


NAME
     r.out.mpeg - Raster File Series to MPEG Conversion Program

SYNOPSIS
     r.out.mpeg
     r.out.mpeg help
     r.out.mpeg [-qc] view1=name[,name,...]
        [view2=name[,name,...]] [view3=name[,name,...]]
        [view4=name[,name,...]] [output=name] [qual=value]


DESCRIPTION
     r.out.mpeg 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.

     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.

     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.

     UNIX - style wild cards may be used with the command line
     version in place of a raster file name, but it must be
     quoted.

     Example:
     r.out.mpeg view1="rain[1-9]","rain1[0-2]" view2="temp*"

     If the number of files differs for each view, the view with
     the fewest files will determine the number of frames in the
     animation.

COMMAND LINE OPTIONS
     Flags:

     -q   Quiet - suppress progress report

     -c   Convert "on the fly", uses less disk space by using
          r.out.ppm 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.

     Parameters:

     view1
          Raster file(s) for View1

     view2
          Raster file(s) for View2

     view3
          Raster file(s) for View3

     view4
          Raster file(s) for View4

     output
          Name for MPEG output file (default gmovie.mpg)

     qual Quality factor (1-5) (default 3)

          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;


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.
     The MPEG format is optimized to recognize image MOTION, so
     abrupt changes from one frame to another will cause a
     "noisy" encoding.


NOTES
     This program requires the program mpeg_encode :

                     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
     Available by anonymous ftp from: s2k-ftp.CS.Berkeley.EDU.

     Use of the -c flag also requires the program r.out.ppm with
     the stdout option, which is available by anonymous ftp from: 
     
     moon.cecer.army.mil.

AUTHOR
     Bill Brown, U.S. Army Construction Engineering Research
     Laboratories (brown@gis.uiuc.edu)