NAME

mpp - a preprocessor for movie frames


SYNOPSIS

mpp [ OPTIONS ] COMMAND-FILE


DESCRIPTION

Mpp stands for Movie PreProcessor. It prepares a set of images for inclusion into a movie. Mpp was written to allow the processing of heterogeneous material (e.g. images with different sizes and file formats, text pages in yet another format) into a homogenous set of frame files. It also does some basic title generation. Features:

o

Convert images from different formats into a single common format. The recognition of many image formats is automatic.

Scale, cut or frame images of different sizes to a common size.

o

Create empty frames of any color, as background for titles etc.

o

Paste text into frames.

o

Paste images into frames. Pasting can be masked, so that the movie frames become the background for the pasted image.

o

Multiplicate a single frame (with links -> no extra disk space required) in order to have it incorporated several times in a movie (still frames and/or slow-motion effects).

Mpp creates movie frames according to the specifications in COMMAND-FILE (or STDIN). The frames are put into a subdirectory MPP_frames. A logfile mpp.log and an error file mpp.err are written for reference.

Mpp also writes a parameter file mpeg.par suitable for a run of the UCB MPEG-I encoder. With the -mpeg switch, the mpeg_encode program runs automatically and produces movie.mpeg.

Mpp will digest many different image formats. Currently the following formats are recognized and converted:

    - JPEG/JFIF       JPEG compressed images in JFIF format
    - GIF             GIF files
    - PBM/PGM/PPM     Jef Poskanzers portable formats
    - PM              Pixmap
    - XBM             X bitmap
    - SUN RASTER      Sun Microsystems raster format
    - BMP             BMP files
    - UTAH RLE        The UTAH RLE format
    - IRIS            RGB files from an SGI workstation
    - PCX             PCX files
    - TIFF            TIFF files
    - PS              Postscript files
    - PDS VICAR       PDS/VICAR files
    - MTV             The format from the MTV raytracer

Mpp will also find compressed images if they have one of the extensions .bz2, .bz, .gz, .z or .Z.

To use mpp, the following programs must be available on your machine.

-

Jef Poskanzers pbmplus library. Mpp makes heavy use of it.

-

Conversion programs to convert your file format into PPM pixmaps. Many of these programs come with the pbmplus library. Mpp also needs to know how these programs are used. If necessary, you can configure this and other information in the configuration section at the top of the mpp program. More documentation can be found there.

-

The MPEG encoder from the University of California, Berkeley, if you want to produce MPEG files. It's available at

  ftp://mm-ftp.cs.berkeley.edu:/pub/multimedia/mpeg

On some systems, this program is installed as ppmtompeg. If this is the case on your system, edit mpp and change the name in the configuration section.

If you are not sure what you have installed, you can check with

    mpp -check.


THE COMMAND FILE

The command file is a script in which you describe the movie frames. Below follows a list of the available commands. Several commands accept a color as an argument. Colors can be specified by name (e.g. 'red', 'green', 'orange') or in rgbi format where the contributions of red, green and blue are specified by numbers between 0 and 1 (e.g. '1/0/0', '0/1/0', '1/0.65/0/').

SIZE size-spec

Set the size of the movie frames. All images will be scaled to this size if necessary. Size-spec is the size in pixels, given as WWWxHHH. It can also be the name of a file containing an image of the correct size, or any of the keywords NTSC (=352x240), CIF (352x288), QCIF (176x144). If no SIZE command is issued early in the command file, the size of the first processed image is used.

SCALE method

Scale all images to equal size using the specified method. The following methods are available.

    cut     If the image is too big, use the center piece
            and clip anything outside the frame size.

    reduce  Reduce images that are too big. The aspect
            ratio is preserved. This is the default.

    best    Reduce large images and enlarge small
            images to fit into the movie size.
            The aspect ratio is preserved.

    exact   Scale the images to exactly the movie
            frame size. The aspect ratio is NOT
            preserved in this operation.

    not     Forbid scaling altogether. This will
            cause mpp to abort if frame sizes
            are found to be inconsistent.

Unless the method is 'exact', the pictures will be framed as needed to meet the exact movie size.

FRAMECOLOR color

Set the color of the frame around images to color. Color can be a name or an r/g/b specification. The default framecolor is black (0/0/0).

PREFIX prefix

Use this prefix for all filenames containing images. This can be used to indicate a path or a longish prefix, e.g.

    PREFIX frames/

Prefix will be applied only to frame files, not to font or paste files (see below).

NNx FILE%dNAME min max step

The frame producing command. NNx is an integer NN followed by x saying how often each frame should be included into the movie. Use this to hold a single frame for some time, or to create a slow-motion effect by showing each frame a few times. If no repetition factor is given, 1 is the default.

The second item is a filename template which can contain a %d (or %04d or whatever). It is fed as a format into sprintf to produce the filenames. The values from MIN to MAX in steps of STEP are used. For example

    image%d.gif 1 10 3

is equivalent to

    image1.gif
    image4.gif
    image7.gif
    image10.gif

When a file does not exist, mpp looks for a compressed version of it with extension .bz, .bz2, .Z, .gz, or .z and uses that one. If those don't exist either, mpp aborts (see, however, -force option).

Filenames that look like a color specification (name or r/g/b) will produce empty frames of the specified color.

TEXTCOLOR color

Specifies the color for subsequent TEXT rendering. The default is white.

TEXTFONT font

Specifies the font for subsequent text rendering. Mpp has built-in two sets of fonts. These are (size specification is character height in pixels)

    FONT TYPE  | AVAILABLE SIZES
    -----------|------------------
    standard   | 8 10 12 14 18 24
    cubistic   | c6 c8

The 'standard' fonts are bold courier fonts. The 'cubistic' fonts have no oblique lines in them and look a little awkward. They do, however, have the advantage of being scalable by arbirary integer factors without quality loss. Font scaling is activated by appending *N to the name. You may also provide your own fonts. To do that, a special font file needs to be prepared. See the pbmtext man page on how to make one. When the font parameter in the TEXTFONT command corresponds to an existing pbm file, it is used as the font file. Examples:

    TEXTFONT 18            # Select standard font 18 pixels high
    TEXTFONT c8*8          # Select cubistic font 64 pixels high
    TEXTFONT my_font.pbm   # Select font defined in this font file
TEXT POS some text for pasting

This command specifies text which will be inserted in the following frames. POS is a single digid 1..9 and determines the position of the text in the frame like the numbers on a keypad.

      ---------------
      |7     8     9|
      |             |
      |4     5     6|
      |             |
      |1     2     3|
      ---------------

If the text runs over several lines, a here-document syntax may be used:

    TEXT 5 <<EOT
    Line 1
        Second line
    Line three
    EOT

If TEXT is called several times with different positions, the different items are all pasted in the frames. For each position, only the most recently defined text is used.

The default color and font used for rendering text are taken from the most recent TEXTFONT and TEXTCOLOR commands. These values may locally be overwritten by embedded -color and -font options. For example

    TEXT 3  -color 1/0/0.5 -font 14  render this text

Should any of the text items turn out to be too large to fit into a movie frame, it will be scaled appropriately.

PASTE POS image

Paste the image in file image at position POS into the following frames. POS has the same meaning as in the TEXT command. You can have either text or an image at a specific location.

Like the TEXT command, PASTE recognizes embedded options. These are:

    -crop  Crop away background around the "interesting" part
           of the image.

    -scale METHOD
           Use METHOD to scale the image into a movie frame.
           METHOD can be any of the ones described for the 
           SCALE command above. The default is 'reduce'.

    -size WWxHH
           Use this size limit rather than the full movie
           frame size when scaling.

    -mask [ THRESHOLD ]
           Use a mask when pasting. This way, only the
           foreground in image will be pasted into the
           frames. THRESHOLD, if specified, marks the
           intensity divide between foreground and background
           in the image. It has to be between 0 and 1. The default
           0.5 works well for strong contrast. For weak
           contrast, use .99 if the background is white,
           .01 if it is black.

    -color color
           Like -mask, but the color of the entire foreground
           is changed to the specified color (name or r/g/b).

Thus, you could make a text frame on some text processing program and save the page in an image format. In order to paste this text in green and as large as possible, the following command could be used:

    PASTE -crop -scale best -color green  textimage

or shorter as

    PASTE -c -s best -c green  textimage
CLEAR [ POS ] [ POS ] ...

This will remove text or images from the specified positions. If no positions are given, all text and image items will be cleared.


OPTIONS

-check

Check the system for the programs required to run mpp.

-colors

List all color names known to mpp.

-clean

Remove all files created by mpp.

-force

Ignore recoverable errors.

-quiet

Make less verbose output. This should give hardly any messages on the terminal. You are supposed to check the error file, though.

-verbose

Make more verbose output. This copies all the stuff headed for the log file to STDERR. It will also show the messages from the mpeg_encode program (several lines per frame).

-product KEY

Defines the file format of the produced frames. The default is ppm. KEY may be any of the following.

    ppm       keep the PPM versions of the frame files
    pgm       produce  PGM versions of the frame files
    pbm       produce  PBM versions of the frame files
    gif       produce  GIF versions of the frame files
    tiff      produce TIFF versions of the frame files
    bz2       compress ppm files with 'bzip2'
    gz        compress ppm files with 'gzip'
    Z         compress ppm files with 'compress'
    z         compress ppm files with 'pack'

Thus,

     mpp -product gif

would produce all frames in GIF format, and

     mpp -p bz2

would save a lot of disk space by compressing the frames.

KEY may also be a system command that formally converts the file 'frame.ppm' into 'frame.img'. For example

     mpp -product 'ppmtogif frame.ppm > frame.img'

would also do a conversion to GIF format.

-mpeg

Call the mpeg_encode program to produce an MPEG movie file movie.mpg. You may use the -mpeg switch together with any of the -product specifications.

All options may be abbreviated to uniqueness.


EXAMPLES

Here is an example of a command file.

    # Specify the size of the movie
    SIZE my_frame01.gif

    # Set default text color to yellow.
    TEXTCOLOR yellow

    # The titlepage in file title.tiff should be masked and pasted
    # into the first frames.
    PASTE 5 title.tiff -mask

    # Ten empty blue frames (r/g/b specification or color name in place
    # of a filename).  title.tiff will be pasted into these frames
    10x blue

    # Terminate pasting of title.tiff
    CLEAR

    # First frame 20 times
    20x my_frame01.gif

    # For the moving frames, show "MOVE" in upper left corner
    TEXT 7 MOVE

    # The frames 02 .. 50 each only once
    my_frame%02d.gif 2 50

    # The same backwards again, and show "BACK" in the upper right corner
    TEXT 9 -c red BACK
    my_frame%02d.gif 50 2 -1

    # ... And forward in slow motion (each frame three times)
    # Show "SLOW" instad of "BACK".
    TEXT 9 -c orange SLOW
    3x my_frame%02d.gif 2 50

    # Clear the "MOVE" and "SLOW" labels.
    CLEAR 7 9

    # Repeat last frame with BIG centered green THE END message
    TEXT 5 -font 24 -color green THE END
    10x my_frame50.gif


FILES

The following files and directories are used by mpp and will be deleted or overwritten without warning.

The major files written by mpp are:

   ./mpp.log ./mpp.err ./mpeg.par ./movie.mpg

Some temporary files are used in the current directory but will be deleted when mpp is done:

   ./frame.* ./redo.img

All other files are placed into two subdirectories:

   ./MPP_frames/      The frame files
   ./MPP_tmp/         Temporary files


BUGS

Not all of the file formats claimed to be recognized have been tested. Most of them have, however.

Image names must be different from color names or mpp will get confused. You can change the supported color names in the configuration section of mpp.

Mpp needs to run on a UNIX system and is not easily ported to other operating systems.

The movie SIZE must be known before the first TEXT or PASTE item is specified.

Mpp has a configuration section near the top of the program. If things don't work as advertised, especially file conversion and file decompression, check it out.

Send bug reports and other feedback to

    Carsten Dominik <dominik@astro.uva.nl>


AUTHOR

Carsten Dominik

(c) 1995 1996 2001 Carsten Dominik

Mpp may be copied, changed, and redistributed under the same terms as PERL.