SYNOPSIS
ppmtompeg [options] parameter-file


DESCRIPTION
This program is part of Netpbm.

ppmtompeg produces an MPEG-1 video stream. MPEG-1 is the first great
video compression method, and is what is used in Video CDs (VCD).
ppmtompeg originated in the year 1995. DVD uses a more advanced
method, MPEG-2. There is an even newer method called MPEG-4 which is
also called Divx. I don't know where one finds that used.

There's technically a difference between a compression method for
video and an actual file (stream) format for a movie, and I don't know
if it can be validly said that the format of the stream ppmtompeg pro-
duces is MPEG-1.

Mencoder from the Mplayer package is probably superior for most video
format generation needs, if for no other reason than that it is more
popular.

The programming library PM2V generates MPEG-2 streams.

Use Mplayer (not part of Netpbm) to do the reverse conversion: to
create a series of PNM files from an MPEG stream.

param_file is a parameter file which includes a list of input files
and other parameters. The file is described in detail below.

To understand this program, you need to understand something about the
complex MPEG-1 format. One source of information about this standard
format is the section Introduction to MPEG in the Compression FAQ .


OPTIONS
The -gop, -combine_gops, -frames, and -combine_frames options are all
mutually exclusive.



-stat stat_file




-quiet num_seconds


-realquiet



-no_frame_summary


-float_dct


-gop gop_num


-combine_gops





-frames first_frame last_frame




-combine_frames





-nice This option causes ppmtompeg to run any remote processes


-max_machines num_machines


-snr This option causes ppmtompeg to include the signal-to-noise


-mse This option causes ppmtompeg to report the mean squared error


-bit_rate_info rate_file


-mv_histogram



-debug_sockets


-debug_machines




PARAMETER FILE
The parameter file must contain the following lines (except when using
the -combine_gops or -combine_frames options):




PATTERN pattern




OUTPUT output file


INPUT_DIR directory



INPUT This line must be followed by a list of the input files (in








BASE_FILE_FORMAT {PPM | PNM | YUV |


INPUT_CONVERT conversion_command










SIZE widthxheight






YUV_SIZE widthxheight


YUV_FORMAT {ABEKAS | PHILLIPS | UCB |



GOP_SIZE n




SLICES_PER_FRAME n


PIXEL {FULL | HALF}



RANGE n


PSEARCH_ALG {EXHAUSTIVE | TWOLEVEL |


BSEARCH_ALG {SIMPLE | CROSS2 | EXHAUSTIVE}


IQSCALE n


PQSCALE n


BQSCALE n


REFERENCE_FRAME {ORIGINAL | DECODED}








The following lines are optional:




FORCE_ENCODE_LAST_FRAME




NIQTABLE



IQTABLE


ASPECT_RATIO ratio



FRAME_RATE rate



BIT_RATE rate



BUFFER_SIZE size






WARN_VBV_UNDERFLOW

WARN_VBV_OVERFLOW









PARALLEL


END PARALLEL


PARALLEL_TEST_FRAMES n





PARALLEL_TIME_CHUNKS t




PARALLEL_CHUNK_TAPER




PARALLEL_PERFECT




RSH remote_shell_command




FORCE_I_ALIGN



KEEP_TEMP_FILES








Parameter File Notes
If you use the -combine_gops option, then you need to specify only
the SIZE and OUTPUT values in the parameter file. In addition, the
parameter file may specify input GOP files in the same manner as nor-
mal input files -- except instead of using INPUT_DIR, INPUT, and
END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT. If you
specify no input GOP files, then ppmtompeg uses by default the output
file name with suffix .gop.gop_num, with gop_num starting from 0, as
the input files.

If you use the -combine_frames option, then you need to specify only
the SIZE, GOP_SIZE, and OUTPUT values in the parameter file. In addi-
tion, the parameter file may specify input frame files in the same
manner as normal input files -- except instead of using INPUT_DIR,
INPUT, and END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and
FRAME_END_INPUT. If no input frame files are specified, then the
default is to use the output file name with suffix .frame.frame_num,
with frame_num starting from 0, as the input files.

Any number of spaces and tabs may come between each option and value.
Lines beginning with # are ignored. Any other lines are ignored
except for those between INPUT and END_INPUT. This allows you to use
the same parameter file for normal usage and for -combine_gops and
-combine_frames.

The file format is case-sensitive so all keywords should be in upper
case.

The statements may appear in any order, except that the order within a
block statement (such as INPUT ... END INPUT) is significant.

ppmtompeg is prepared to handle up to 16 B frames between reference
frames when encoding with input from stdin. (To build a modified ppm-
tompeg with a higher limit, change the constant B_FRAME_RUN in frame.c
and recompile).


GENERAL USAGE INFORMATION
Qscale
The quantization scale values (qscale) give a trade-off between qual-
ity and compression. Using different Qscale values has very little
effect on speed. The qscale values can be set separately for I, P,
and B frames.

You select the qscale values with the IQSCALE, PQSCALE, and BSCALE
parameter file statements.

A qscale value is an integer from 1 to 31. Larger numbers give better
compression, but worse quality. In the following, the quality numbers
are peak signal-to-noise ratio, defined as: signal-to-noise formula
where MSE is the mean squared error.


Flower garden tests:

Qscale vs Quality

----------------------------------------
Qscale I Frames P Frames B Frames
1 43.2 46.3 46.5
6 32.6 34.6 34.3
11 28.6 29.5 30.0
16 26.3 26.8 28.6
21 24.7 25.0 27.9
26 23.5 23.9 27.5
31 22.6 23.0 27.3

Qscale vs Compression

----------------------------------------
Qscale I Frames P Frames B Frames
1 2 2 2
6 7 10 15
11 11 18 43
16 15 29 97
21 19 41 173
26 24 56 256
31 28 73 330



Search Techniques
There are several different motion vector search techniques available.
There are different techniques available for P frame search and B
frame search. Using different search techniques present little
difference in quality, but a large difference in compression and
speed.


There are 4 types of P frame search: Exhaustive, TwoLevel, SubSample,
and Logarithmic.


There are 3 types of B frame search: Exhaustive, Cross2, and Simple.

The recommended search techniques are TwoLevel and Logarithmic for P
frame search, and Cross2 and Simple for B frame search. Here are some
numbers comparing the different search methods:

P frame Motion Vector Search (Normalized)

--------------------------------------------------
Technique Compression 1 Speed 2 Quality 3
Exhaustive 1000 1000 1000
SubSample 1008 2456 1000
TwoLevel 1009 3237 1000
Logarithmic 1085 8229 998

B frame Motion Vector Search (Normalized)

-------------------------------------------------
Technique Compression 1 Speed 2 Quality 3
Exhaustive 1000 1000 1000
Cross2 975 1000 996
Simple 938 1765 991

1Smaller numbers are better compression.

2Larger numbers mean faster execution.

3Larger numbers mean better quality.

For some reason, Simple seems to give better compression, but it
depends on the image sequence.

Select the search techniques with the PSEARCH_ALG and BSEARCH_ALG
parameter file statements.



Group Of Pictures (GOP)
A Group of Pictures (GOP) is a roughly independently decodable
sequence of frames. An MPEG video stream is made of one or more
GOP's. You may specify how many frames should be in each GOP with the
GOP_SIZE parameter file statement. A GOP always starts with an I
frame.

Instead of encoding an entire sequence, you can encode a single GOP.
To do this, use the -gop command option. You can later join the
resulting GOP files at any time by running ppmtompeg with the -com-
bine_gops command option.



Slices
A slice is an independently decodable unit in a frame. It can be as
small as one macroblock, or it can be as big as the entire frame.
Barring transmission error, adding slices does not change quality or
speed; the only effect is slightly worse compression. More slices are
used for noisy transmission so that errors are more recoverable. Since
usually errors are not such a problem, we usually just use one slice
per frame.


Control the slice size with the SLICES_PER_FRAME parameter file
statement.

Some MPEG playback systems require that each slice consist of whole
rows of macroblocks. If you are encoding for this kind of player, if
the height of the image is H pixels, then you should set the
SLICES_PER_FRAME to some number which divides H/16. For example, if
the image is 240 pixels (15 macroblocks) high, then you should use
only 15, 5, 3, or 1 slices per frame.


Note: these MPEG playback systems are really wrong, since the MPEG
standard says this doesn't have to be so.




Search Window
The search window is the window in which ppmtompeg searches for motion
vectors. The window is a square. You can specify the size of the
square, and whether to allow half-pixel motion vectors or not, with
the RANGE and PIXEL parameter file statements.


I Frames, P Frames, B Frames
In MPEG-1, a movie is represented as a sequence of MPEG frames, each
of which is an I Frame, a P Frame, or a B Frame. Each represents an
actual frame of the movie (don't get confused by the dual use of the
word "frame." A movie frame is a graphical image. An MPEG frame is a
set of data that describes a movie frame).

An I frame ("intra" frame) describes a movie frame in isolation --
without respect to any other frame in the movie. A P frame ("predic-
tive" frame) describes a movie frame by describing how it differs from
the movie frame described by the latest preceding I or P frame. A B
frame ("bidirectional" frame) describes a movie frame by describing
how it differs from the the movie frames described by the nearest I or
P frame before and after it.

Note that the first frame of a movie must be described by an I frame
(because there is no previous movie frame) and the last movie frame
must be described by an I or P frame (because there is no subsequent
movie frame).

Beyond that, you can choose which frames are represented by which
types. You specify a pattern, such as IBPBP and ppmtompeg simply
repeats it over and over throughout the movie. The pattern affects
speed, quality, and stream size. Here is a chart which shows some of
the trade-offs:

Comparison of I/P/B Frames (Normalized)

------------------------------------
Frame Type Size Speed Quality
I frames 1000 1000 1000
P frames 409 609 969
B frames 72 260 919

(this is with constant qscale)


A standard sequence is IBBPBBPBBPBBPBB.


Select the sequence with the PATTERN parameter file statement.

Since the last MPEG frame cannot be a B frame (see above), if the pat-
tern you specify indicates a B frame for the last movie frame of the
movie, ppmtompeg makes it an I frame instead.

Before Netpbm 10.26 (January 2005), ppmtompeg instead drops the
trailing B frames by default, and you need the FORCE_ENCODE_LAST_FRAME
parameter file statement to make it do this.

The MPEG frames don't appear in the MPEG-1 stream in the same order
that the corresponding movie frames appear in the movie -- the B
frames come after the I and P frames on which they are based. For
example, if the movie is 4 frames that you will represent with the
pattern IBBP, the MPEG-1 stream will start with an I frame describing
movie frame 0. The next frame in the MPEG-1 stream is a P frame
describing movie frame 3. The last two frames in the MPEG-1 stream
are B frames describing movie frames 1 and 2, respectively.



Specifying Input and Output Files
Specify the input frame images with the INPUT_DIR, INPUT, END_INPUT,
BASE_FILE_FORMAT, SIZE, YUV_FORMAT and INPUT_CONVERT parameter file
statements.

Specify the output file with the OUTPUT parameter file statement.



Statistics
ppmtompeg can generate a variety of statistics about the encoding.
See the -stat, -snr, -mv_histogram, -quiet, -no_frame_summary, and
-bit_rate_info options.



PARALLEL OPERATION
You can run ppmtompeg on multiple machines at once, encoding the same
MPEG stream. When you do, the machines are used as shown in the fol-
lowing diagram. We call this 'parallel mode.'

ppmtompeg-par.gif

To do parallel processing, put the statement

PARALLEL

in the parameter file, followed by a listing of the machines, one
machine per line, then

END_PARALLEL

Each of the machine lines must be in one of two forms. If the machine
has filesystem access to the input files, then the line is:

machine user executable

The executable is normally ppmtompeg (you may need to give the com-
plete path if you've built for different architectures). If the
machine does not have filesystem access to the input files, the line
is:

REMOTE machine user executable parameter file

The -max_machines command option limits the number of machines ppmtom-
peg will use. If you specify more machines in the parameter file than
-max_machines allows, ppmtompeg uses only the machines listed first.
This is handy if you want to experiment with different amounts of par-
allelism.

In general, you should use full path file names when describing exe-
cutables and parameter files. This includes the parameter file argu-
ment on the original invocation of ppmtompeg.

All file names must be the same on all systems (so if e.g. you're
using an NFS filesystem, you must make sure it is mounted at the same
mountpoint on all systems).

Because not all of the processes involved in parallel operation have
easy access to the input files, you must specify the SIZE parameter
file statement when you do parallel operation.

The machine on which you originally invoke ppmtompeg is the master
machine. It hosts a 'combine server,', a 'decode server,' and a num-
ber of 'i/o servers,' all as separate processes. The other machines
in the network (listed in the parameter file) are slave machines.
Each hosts a single process that continuously requests work from the
master and does it. The slave process does the computation to encode
MPEG frames. It processes frames in batches identified by the master.

The master uses a remote shell command to start a process on a slave
machine. By default, it uses an rsh shell command to do this. But
use the RSH parameter file statement to control this. The shell com-
mand the master executes remotely is ppmtompeg, but with options to
indicate that it is to perform slave functions.

The various machines talk to each other over TCP connections. Each
machine finds and binds to a free TCP port number and tells its part-
ners the port number. These port numbers are at least 2048.

Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS, and PARALLEL_PER-
FECT parameter file statements to control the way the master divides
up work among the slaves.

Use the -nice command option to cause all slave processes to run
"nicely," i.e. as low priority processes. That way, this substantial
and long-running CPU load will have minimal impact on other, possibly
interactive, users of the systems.


SPEED
Here is a look at ppmtompeg speed, in single-node (not parallel) oper-
ation:

Compression Speed

---------------------------------------
Machine Type Macroblocks per second1
HP 9000/755 280
DEC 3000/400 247
HP 9000/750 191
Sparc 10 104
DEC 5000 68
1A macroblock is a 16x16 pixel square

The measurements in the table are with inputs and outputs via a con-
ventional locally attached filesystem. If you are using a network
filesystem over a single 10 MB/s Ethernet, that constrains your speed
more than your CPU speed. In that case, don't expect to get better
than 4 or 5 frames per second no matter how fast your CPUs are.

Network speed is even more of a bottleneck when the slaves do not have
filesystem access to the input files -- i.e. you declare them REMOTE.

Where I/O is the bottleneck, size of the input frames can make a big
difference. So YUV input is better than PPM, and JPEG is better than
both.

When you're first trying to get parallel mode working, be sure to use
the -debug_machines option so you can see what's going on. Also,
-debug_sockets can help you diagnose communication problems.



AUTHORS
? Kevin Gong - University of California, Berkeley, kev-


? Ketan Patel - University of California, Berkeley, kpa-


? Dan Wallach - University of California, Berkeley, dwal-


? Darryl Brown - University of California, Berkeley, dar-


? Eugene Hung - University of California, Berkeley,


? Steve Smoot - University of California, Berkeley,



netpbm documentation 23 July 2006 Ppmtompeg User Manual(0)