mpp - a preprocessor for movie frames
mpp [ OPTIONS ] COMMAND-FILE
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:
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.
Create empty frames of any color, as background for titles etc.
Paste text into frames.
Paste images into frames. Pasting can be masked, so that the movie frames become the background for the pasted image.
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 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/').
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 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.
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).
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).
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.
Specifies the color for subsequent TEXT rendering. The default is white.
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
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 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
This will remove text or images from the specified positions. If no positions are given, all text and image items will be cleared.
Check the system for the programs required to run mpp.
List all color names known to mpp.
Remove all files created by mpp.
Ignore recoverable errors.
Make less verbose output. This should give hardly any messages on the terminal. You are supposed to check the error file, though.
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).
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.
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.
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
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
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>
Carsten Dominik
(c) 1995 1996 2001 Carsten Dominik
Mpp may be copied, changed, and redistributed under the same terms as PERL.