Blame SOURCES/netpbm-manual-pages.patch

1ab173
diff --git a/userguide/cameratopam.html b/userguide/cameratopam.html
1ab173
index 7a6391e..89f6939 100644
1ab173
--- a/userguide/cameratopam.html
1ab173
+++ b/userguide/cameratopam.html
1ab173
@@ -163,7 +163,7 @@ means.
1ab173
 href="http://www.cybercom.net/~dcoffin/dcraw/">dcraw by Dave
1ab173
 Coffin, by Bryan Henderson in April 2005.  Bryan replaced the part
1ab173
 that generates the Netpbm output image and removed the Adobe Photoshop
1ab173
-output function.  Bryan changed the command syntax and and made other
1ab173
+output function.  Bryan changed the command syntax and made other
1ab173
 small changes to make the program consistent with Netpbm.  He also
1ab173
 split the source code into manageable pieces (dcraw has a
1ab173
 single 5000 line source file).
1ab173
diff --git a/userguide/fiascotopnm.html b/userguide/fiascotopnm.html
1ab173
index 2cd4f01..f1f1b17 100644
1ab173
--- a/userguide/fiascotopnm.html
1ab173
+++ b/userguide/fiascotopnm.html
1ab173
@@ -76,7 +76,7 @@ Set magnification of the decompressed image. Positive values enlarge
1ab173
 and negative values reduce the image width and height by a factor of
1ab173
 2^|N|.
1ab173
 
1ab173
-
-s N, --smooth=N
1ab173
+
-s N, --smoothing=N
1ab173
 
1ab173
 Smooth decompressed image(s) along the partitioning borders by the
1ab173
 given amount N. N is 1 (minimum) to 100 (maximum); default
1ab173
@@ -88,6 +88,10 @@ FIASCO file is used (defined by the FIASCO coder).
1ab173
 Set number of frames per second to N. When using this option,
1ab173
 the frame rate specified in the FIASCO file is overridden.
1ab173
 
1ab173
+
--verbose=N
1ab173
+
1ab173
+Set verbose of fiascotopnm to N.
1ab173
+
1ab173
 
-v, --version
1ab173
 
1ab173
 Print fiascotopnm version number, then exit.
1ab173
diff --git a/userguide/pamdepth.html b/userguide/pamdepth.html
1ab173
index 1a2b5fd..c188e44 100644
1ab173
--- a/userguide/pamdepth.html
1ab173
+++ b/userguide/pamdepth.html
1ab173
@@ -52,7 +52,7 @@ files before April 2000.
1ab173
 pnmdepth, by Jef Poskanzer.  pamdepth is backward compatible
1ab173
 with pnmdepth and adds the ability to process arbitrary PAM images
1ab173
 and the ability to process multi-image input streams.  pnmdepth
1ab173
-handled only PNM images and ignored all but the the first in any stream.
1ab173
+handled only PNM images and ignored all but the first in any stream.
1ab173
 
1ab173
 
1ab173
 

Table Of Contents

1ab173
diff --git a/userguide/pamdice.html b/userguide/pamdice.html
1ab173
index 0659e15..9053113 100644
1ab173
--- a/userguide/pamdice.html
1ab173
+++ b/userguide/pamdice.html
1ab173
@@ -139,7 +139,7 @@ in each direction.
1ab173
 pgmslice,
1ab173
 ppmglobe
1ab173
 pnm
1ab173
-pnm
1ab173
+pam
1ab173
 
1ab173
 
1ab173
 

Table Of Contents

1ab173
diff --git a/userguide/pamstereogram.html b/userguide/pamstereogram.html
1ab173
index c337547..652b887 100644
1ab173
--- a/userguide/pamstereogram.html
1ab173
+++ b/userguide/pamstereogram.html
1ab173
@@ -319,7 +319,7 @@ be.  Lower (darker) numbers mean further from the eye.
1ab173
 
1ab173
 

Input Images

1ab173
 
1ab173
-

pamstereogram pays no attention the the image's tuple

1ab173
+

pamstereogram pays no attention the image's tuple

1ab173
 type and ignores all planes other than plane 0.

1ab173
 
1ab173
 

Like any Netpbm program, pamstereogram will accept PNM

1ab173
diff --git a/userguide/pamtofits.html b/userguide/pamtofits.html
1ab173
index 445b326..0ecc806 100644
1ab173
--- a/userguide/pamtofits.html
1ab173
+++ b/userguide/pamtofits.html
1ab173
@@ -54,7 +54,7 @@ approximation.
1ab173
 

Pixel Order

1ab173
 
1ab173
 

The FITS specification does not specify which data in the file corresponds

1ab173
-to which pixel in the image (i.e. which bytes are the the top left pixel,
1ab173
+to which pixel in the image (i.e. which bytes are the top left pixel,
1ab173
 etc.).  Netpbm uses the common sense, most popular arrangement: row major, top
1ab173
 to bottom, left to right.  That means in a 10 wide by 20 high image, the first
1ab173
 10 pixels in the file are the top row and the last 10 are the bottom row.
1ab173
diff --git a/userguide/pamtojpeg2k.html b/userguide/pamtojpeg2k.html
1ab173
index 06b6113..046d740 100644
1ab173
--- a/userguide/pamtojpeg2k.html
1ab173
+++ b/userguide/pamtojpeg2k.html
1ab173
@@ -181,7 +181,7 @@ its goal is similar to JPEG.  It has two main differences from JPEG.
1ab173
 

One difference is that it does a much better job on most images of

1ab173
 throwing out information in order to achieve a smaller output.  That
1ab173
 means when you reconstruct the image from the resulting compressed
1ab173
-file, it looks a lot closer to the image you started with with
1ab173
+file, it looks a lot closer to the image you started with
1ab173
 JPEG-2000 than with JPEG, for the same compressed file size.  Or, looked
1ab173
 at another way, with JPEG-2000 you get a much smaller file than with 
1ab173
 JPEG for the same image quality.
1ab173
diff --git a/userguide/pamtotiff.html b/userguide/pamtotiff.html
1ab173
index f07d227..c7a48a0 100644
1ab173
--- a/userguide/pamtotiff.html
1ab173
+++ b/userguide/pamtotiff.html
1ab173
@@ -124,7 +124,7 @@ format it produces are therefore controlled by that library.
1ab173
 

By default, pamtotiff creates a TIFF file with no

1ab173
 compression.  This is your best bet most of the time.  If you want to
1ab173
 try another compression scheme or tweak some of the other even more
1ab173
-obscure output options, there are a number of options which which to
1ab173
+obscure output options, there are a number of options which to
1ab173
 play.
1ab173
 
1ab173
 

Before Netpbm 8.4 (April 2000), the default was to use LZW compression.

1ab173
diff --git a/userguide/pamtouil.html b/userguide/pamtouil.html
1ab173
index 1074119..6c2356b 100644
1ab173
--- a/userguide/pamtouil.html
1ab173
+++ b/userguide/pamtouil.html
1ab173
@@ -57,7 +57,7 @@ in the RGB database.
1ab173
  
1ab173
 

SEE ALSO

1ab173
 
1ab173
-pam
1ab173
+pamstack
1ab173
 pam
1ab173
 ppm
1ab173
 
1ab173
diff --git a/userguide/pamundice.html b/userguide/pamundice.html
1ab173
index 2b789b4..bf366d6 100644
1ab173
--- a/userguide/pamundice.html
1ab173
+++ b/userguide/pamundice.html
1ab173
@@ -208,7 +208,7 @@ clips the bottom edge of each image before joining it to the one below.
1ab173
 pnmindex,
1ab173
 pnmtile,
1ab173
 pnm
1ab173
-pnm
1ab173
+pam
1ab173
 
1ab173
 
1ab173
 

Table Of Contents

1ab173
diff --git a/userguide/pbm.html b/userguide/pbm.html
1ab173
index 63dfa40..7db4886 100644
1ab173
--- a/userguide/pbm.html
1ab173
+++ b/userguide/pbm.html
1ab173
@@ -136,7 +136,7 @@ P1
1ab173
 accepting anything that looks remotely like a bitmap.
1ab173
 
1ab173
 

All characters referred to herein are encoded in ASCII.

1ab173
-"newline" refers the the character known in ASCII as Line
1ab173
+"newline" refers the character known in ASCII as Line
1ab173
 Feed or LF.  A "white space" character is space, CR, LF,
1ab173
 TAB, VT, or FF (I.e. what the ANSI standard C isspace() function
1ab173
 calls white space).
1ab173
diff --git a/userguide/pbmtolj.html b/userguide/pbmtolj.html
1ab173
index ce7e9bb..6da4555 100644
1ab173
--- a/userguide/pbmtolj.html
1ab173
+++ b/userguide/pbmtolj.html
1ab173
@@ -83,7 +83,7 @@ and end of the output file.
1ab173
 
1ab173
 
-copies
1ab173
 
1ab173
-
Specifies the the number of copies. The default is 1. This option
1ab173
+
Specifies the number of copies. The default is 1. This option
1ab173
 controls the "number of copies" printer control;
1ab173
 pbmtolj generates only one copy of the image.
1ab173
 
1ab173
diff --git a/userguide/pgm.html b/userguide/pgm.html
1ab173
index d75c9ef..7df1abc 100644
1ab173
--- a/userguide/pgm.html
1ab173
+++ b/userguide/pgm.html
1ab173
@@ -153,7 +153,7 @@ P2
1ab173
 accepting anything that looks remotely like a PGM.
1ab173
 
1ab173
 

All characters referred to herein are encoded in ASCII.

1ab173
-"newline" refers the the character known in ASCII as Line
1ab173
+"newline" refers the character known in ASCII as Line
1ab173
 Feed or LF.  A "white space" character is space, CR, LF,
1ab173
 TAB, VT, or FF (I.e. what the ANSI standard C isspace() function
1ab173
 calls white space).
1ab173
diff --git a/userguide/pngtopam.html b/userguide/pngtopam.html
1ab173
index 8185843..09406ef 100644
1ab173
--- a/userguide/pngtopam.html
1ab173
+++ b/userguide/pngtopam.html
1ab173
@@ -269,7 +269,7 @@ change to the package in Netpbm's renaissance.  It and pnmtopng
1ab173
 were simply copied from the 
1ab173
 href="http://www.libpng.org/pub/png/apps/pnmtopng.html">
1ab173
 pnmtopng package by Greg Roelofs.  Those were based on
1ab173
-simpler reference applications by by Alexander Lehmann
1ab173
+simpler reference applications by Alexander Lehmann
1ab173
 <alex@hal.rhein-main.de> and Willem van Schaik
1ab173
 <willem@schaik.com> and distributed with their PNG library.
1ab173
 
1ab173
diff --git a/userguide/pnmnorm.html b/userguide/pnmnorm.html
1ab173
index c4d2558..5d3ca49 100644
1ab173
--- a/userguide/pnmnorm.html
1ab173
+++ b/userguide/pnmnorm.html
1ab173
@@ -146,7 +146,7 @@ value 99 or the white value 101.
1ab173
 option.  Sometimes, too much contrast is a bad thing.  If your
1ab173
 intensities are all concentrated in the middle, -bpercent=2 and
1ab173
 -wpercent=1 might mean that an intensity of 60 gets stretched
1ab173
-up to 100 and and intensity of 20 gets stretched down to zero, for a
1ab173
+up to 100 and intensity of 20 gets stretched down to zero, for a
1ab173
 range expansion of 150% (from a range of 40 to a range of 100).  That
1ab173
 much stretching means two adjacent pixels that used to differ in
1ab173
 intensity by 4 units now differ by 10, and that might be unsightly.
1ab173
diff --git a/userguide/pnmtopalm.html b/userguide/pnmtopalm.html
1ab173
index 94aa6ff..9ca9c0d 100644
1ab173
--- a/userguide/pnmtopalm.html
1ab173
+++ b/userguide/pnmtopalm.html
1ab173
@@ -164,7 +164,7 @@ the -colormap option, for much the same reason.
1ab173
 
1ab173
 
-withdummy
1ab173
 
1ab173
-This option tells pnmtopalm to put in the stream, after after
1ab173
+This option tells pnmtopalm to put in the stream, after
1ab173
 the image, a dummy image header to introduce subsequent high density
1ab173
 images.
1ab173
 
1ab173
diff --git a/userguide/ppm.html b/userguide/ppm.html
1ab173
index c71aaa4..8e7a111 100644
1ab173
--- a/userguide/ppm.html
1ab173
+++ b/userguide/ppm.html
1ab173
@@ -158,7 +158,7 @@ P3
1ab173
 accepting anything that looks remotely like a PPM image.
1ab173
 
1ab173
 

All characters referred to herein are encoded in ASCII.

1ab173
-"newline" refers the the character known in ASCII as Line
1ab173
+"newline" refers the character known in ASCII as Line
1ab173
 Feed or LF.  A "white space" character is space, CR, LF,
1ab173
 TAB, VT, or FF (I.e. what the ANSI standard C isspace() function
1ab173
 calls white space).
1ab173
diff --git a/userguide/ppmtopj.html b/userguide/ppmtopj.html
1ab173
index c07c1d9..b50be28 100644
1ab173
--- a/userguide/ppmtopj.html
1ab173
+++ b/userguide/ppmtopj.html
1ab173
@@ -61,7 +61,7 @@ You could convert your input to this format like this:
1ab173
     pnmremap -map 8color.pam testimg.pam | ppmtopj
1ab173
 
1ab173
 
1ab173
-Or you could use use
1ab173
+Or you could use 
1ab173
 
1ab173
     ppmdither -red 2 -green 2 -blue 2
1ab173
 
1ab173
diff --git a/userguide/qrttoppm.html b/userguide/qrttoppm.html
1ab173
index b6bf976..112bf50 100644
1ab173
--- a/userguide/qrttoppm.html
1ab173
+++ b/userguide/qrttoppm.html
1ab173
@@ -22,7 +22,7 @@ qrttoppm - convert output from the QRT ray tracer to a PPM image
1ab173
 
1ab173
 

This program is part of Netpbm.

1ab173
 
1ab173
-

qrttoppm reads a QRT file as input and and produces a PPM

1ab173
+

qrttoppm reads a QRT file as input and produces a PPM

1ab173
 image as output.
1ab173
 
1ab173
  
1ab173
diff --git a/userguide/sbigtopgm.html b/userguide/sbigtopgm.html
1ab173
index 400bcaf..78f9454 100644
1ab173
--- a/userguide/sbigtopgm.html
1ab173
+++ b/userguide/sbigtopgm.html
1ab173
@@ -22,7 +22,7 @@ sbigtopgm - convert an SBIG CCDOPS file to PGM
1ab173
 
1ab173
 

This program is part of Netpbm.

1ab173
 
1ab173
-

sbigtopgm reads an an image file in the native format used

1ab173
+

sbigtopgm reads an image file in the native format used

1ab173
 by the Santa Barbara Instrument Group (SBIG) astronomical CCD cameras,
1ab173
 and produces a PGM image as output.  Additional information on SBIG
1ab173
 cameras and documentation of the file format is available at the Web
1ab173
diff --git a/userguide/srftopam.html b/userguide/srftopam.html
1ab173
index b27f133..c98586f 100644
1ab173
--- a/userguide/srftopam.html
1ab173
+++ b/userguide/srftopam.html
1ab173
@@ -30,7 +30,7 @@
1ab173
 
1ab173
 

This program is part of Netpbm.

1ab173
 
1ab173
-

srftopam reads a a SRF image file as input and produces a

1ab173
+

srftopam reads a SRF image file as input and produces a

1ab173
 multi-image stream of PAM images as output.
1ab173
 
1ab173
 

This program performs the inverse of the conversion that pamtosrf

1ab173
diff --git a/userguide/sunicontopnm.html b/userguide/sunicontopnm.html
1ab173
index 6ccbcde..0290f7b 100644
1ab173
--- a/userguide/sunicontopnm.html
1ab173
+++ b/userguide/sunicontopnm.html
1ab173
@@ -54,7 +54,7 @@ mostly XPM files.
1ab173
 xbmtoppm,
1ab173
 infotopam,
1ab173
 pbm
1ab173
-pbm
1ab173
+pgm
1ab173
 
1ab173
 

HISTORY

1ab173
 
1ab173
diff --git a/userguide/xpmtoppm.html b/userguide/xpmtoppm.html
1ab173
index c7c857b..f96b249 100644
1ab173
--- a/userguide/xpmtoppm.html
1ab173
+++ b/userguide/xpmtoppm.html
1ab173
@@ -46,7 +46,7 @@ alpha output to Standard Output and discards the image.
1ab173
 the alpha output file.
1ab173
 
1ab173
 

xpmtoppm can't handle a line longer than 8K characters in

1ab173
-the the XPM input.  If an input line exceeds this limit,
1ab173
+the XPM input.  If an input line exceeds this limit,
1ab173
 xpmtoppm quits with an error message to that effect.  Before
1ab173
 Netpbm 10.30 (October 2005), the limit was 2K.
1ab173
 
1ab173
diff --git a/userguide/infotopam.html b/userguide/infotopam.html
1ab173
index 9818c59..177f4d4 100644
1ab173
--- a/userguide/infotopam.html
1ab173
+++ b/userguide/infotopam.html
1ab173
@@ -110,7 +110,7 @@ using the -forcecolor option.

1ab173
   

To override the colors, first specify how many colors to override using

1ab173
   -numcolors, then specify an (index color) pair for each color
1ab173
   you want to override, where index is a value from 0 to 3 and
1ab173
-  color the the new color for that index.  Specify color as
1ab173
+  color the new color for that index.  Specify color as
1ab173
   described for the ppm_parsecolor()
1ab173
   argument.

1ab173
 
1ab173
diff --git a/userguide/pbmtoppa.html b/userguide/pbmtoppa.html
1ab173
index f2ccf11..e0abe05 100644
1ab173
--- a/userguide/pbmtoppa.html
1ab173
+++ b/userguide/pbmtoppa.html
1ab173
@@ -254,7 +254,7 @@ StartEntry: DeskJet720C
1ab173
   About: { \
1ab173
         This driver supports the HP DeskJet 720C \
1ab173
         inkjet printer. \
1ab173
-        It does does not support color printing. \
1ab173
+        It does not support color printing. \
1ab173
         IMPORTANT! Insert \
1ab173
              "- | pbm2ppa -" \
1ab173
         in the "Extra GS Options" field.\
1ab173
diff --git a/userguide/pnmgamma.html b/userguide/pnmgamma.html
1ab173
index 574d7d9..4c884f5 100644
1ab173
--- a/userguide/pnmgamma.html
1ab173
+++ b/userguide/pnmgamma.html
1ab173
@@ -242,7 +242,7 @@ the output is the same as that of the input.
1ab173
 
1ab173
 

Because the transformation is not linear, you need a greater maxval

1ab173
 in the output in order not to lose any information from the input.
1ab173
-For example, if you convert to radiance-linear sample values with with
1ab173
+For example, if you convert to radiance-linear sample values with 
1ab173
 -ungamma -bt709ramp and default gamma value, and your maxval is
1ab173
 255 on both input and output, 3 different input sample values all
1ab173
 generate output sample value 254.  In order to have a different output
1ab173
diff --git a/userguide/ppmtompeg.html b/userguide/ppmtompeg.html
1ab173
deleted file mode 100644
1ab173
index 4fa4a53..0000000
1ab173
--- a/userguide/ppmtompeg.html
1ab173
+++ /dev/null
1ab173
@@ -1,1291 +0,0 @@
1ab173
-
1ab173
-<HTML>
1ab173
-<HEAD>
1ab173
-<TITLE>Ppmtompeg User Manual</TITLE>
1ab173
-</HEAD>
1ab173
-<BODY>
1ab173
-

Ppmtompeg

1ab173
-Updated: 23 July 2006
1ab173
-
1ab173
-Table Of Contents
1ab173
-
1ab173
-

NAME

1ab173
-ppmtompeg - encode an MPEG-1 bitstream
1ab173
-
1ab173
-

SYNOPSIS

1ab173
-
1ab173
-ppmtompeg
1ab173
-[options]
1ab173
-parameter-file
1ab173
-
1ab173
-

DESCRIPTION

1ab173
-
1ab173
-

This program is part of Netpbm.

1ab173
-
1ab173
-

ppmtompeg produces an MPEG-1 video stream. MPEG-1 is the

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

There's technically a difference between a compression method for

1ab173
-video and an actual file (stream) format for a movie, and I don't know
1ab173
-if it can be validly said that the format of the stream
1ab173
-ppmtompeg produces is MPEG-1.
1ab173
-
1ab173
-

Mencoder from the Mplayer

1ab173
-package is probably superior for most video format generation
1ab173
-needs, if for no other reason than that it is more popular.
1ab173
-
1ab173
-

The programming library PM2V

1ab173
-generates MPEG-2 streams.
1ab173
-
1ab173
-

Use Mplayer (not part of Netpbm)

1ab173
-to do the reverse conversion: to create a series of PNM files from an MPEG
1ab173
-stream.
1ab173
-
1ab173
-

param_file is a parameter file which includes a list of

1ab173
-input files and other parameters.  The file is described in detail
1ab173
-below.
1ab173
-
1ab173
-

To understand this program, you need to understand something about

1ab173
-the complex MPEG-1 format.  One source of information about this
1ab173
-standard format is the section Introduction to MPEG in the 
1ab173
-href="http://www.faqs.org/faqs/compression-faq">Compression FAQ.
1ab173
-
1ab173
-

OPTIONS

1ab173
-
1ab173
-

The -gop, -combine_gops, -frames, and

1ab173
--combine_frames options are all mutually exclusive.
1ab173
-
1ab173
-
1ab173
-
-stat stat_file
1ab173
-
1ab173
-
This option causes ppmtompeg to append the statistics that
1ab173
-it write to Standard Output to the file stat_file as well.  The
1ab173
-statistics use the following abbreviations: bits per block (bpb), bits
1ab173
-per frame (bpf), seconds per frame (spf), and bits per second (bps).
1ab173
-
1ab173
-

These statistics include how many I, P, and B frames there were,

1ab173
-and information about compression and quality.
1ab173
-
1ab173
-
1ab173
-
-quiet num_seconds
1ab173
-
1ab173
-
causes ppmtompeg not to report remaining time more often
1ab173
-than every num_seconds seconds (unless the time estimate rises,
1ab173
-which will happen near the beginning of the run).  A negative value
1ab173
-tells ppmtompeg not to report at all.  0 is the default
1ab173
-(reports once after each frame).  Note that the time remaining is an
1ab173
-estimate and does not take into account time to read in frames.
1ab173
-
1ab173
-
-realquiet
causes ppmtompeg to run silently,
1ab173
-with the only screen output being errors.  Particularly useful when
1ab173
-reading input from stdin.
1ab173
-
1ab173
-
1ab173
--no_frame_summary
1ab173
-
1ab173
-
This option prevents ppmtompeg from printing a summary
1ab173
-line for each frame
1ab173
-
1ab173
-
-float_dct
1ab173
-
1ab173
-
forces ppmtompeg to use a more accurate, yet more
1ab173
-computationally expensive version of the DCT.
1ab173
-
1ab173
-
-gop gop_num
1ab173
-
1ab173
-causes ppmtompeg to encode only the numbered GOP (first GOP is 0).  The
1ab173
-parameter file is the same as for normal usage.  The output file will be
1ab173
-the normal output file with the suffix .gop.gop_num.
1ab173
-ppmtompeg does not output any sequence information.
1ab173
-
1ab173
-
-combine_gops
1ab173
-
1ab173
-
causes ppmtompeg simply to combine some GOP files into a
1ab173
-single MPEG output stream.  ppmtompeg inserts a sequence header
1ab173
-and trailer.  In this case, the parameter file needs only to contain 
1ab173
-the SIZE value, an output file, and perhaps a list of input GOP
1ab173
-files (see below).
1ab173
-
1ab173
-If you don't supply a list of input GOP files is used, then
1ab173
-ppmtompeg assumes you're using the same parameter file you used
1ab173
-when you created the input (with the -gop option) and
1ab173
-calculates the corresponding gop filenames itself.  If this is not the
1ab173
-case, you can specify input GOP files in the same manner as normal
1ab173
-input files -- except instead of using INPUT_DIR, INPUT, and
1ab173
-END_INPUT, use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT.  If no
1ab173
-input GOP files are specified, then the default is to use the output
1ab173
-file name with suffix .gop.gop_num, with gop_num
1ab173
-starting from 0, as the input files.
1ab173
-     
1ab173
-

Thus, unless you're mixing and matching GOP files from different

1ab173
-sources, you can simply use the same parameter file for creating the
1ab173
-GOP files (-gop) and for later turning them into an MPEG stream
1ab173
-(-combine_gops).
1ab173
-     
1ab173
-
1ab173
-
-frames first_frame last_frame
1ab173
-
1ab173
-
This option causes ppmtompeg to encode only the frames numbered
1ab173
-first_frame to last_frame, inclusive.  The parameter
1ab173
-file is the same as for normal usage.  The output will be placed in
1ab173
-separate files, one per frame, with the file names being the normal
1ab173
-output file name with the suffix .frame.frame_num.  No
1ab173
-GOP header information is output.  (Thus, the parameter file need not
1ab173
-include the GOP_SIZE value)
1ab173
-
1ab173
-

Use ppmtompeg -combine_frames to combine these frames later into

1ab173
-an MPEG stream.
1ab173
-
1ab173
-
1ab173
-
-combine_frames
1ab173
-
1ab173
-
This option causes ppmtompeg simply to combine some
1ab173
-individual MPEG frames (such as you might have created with an earlier
1ab173
-run of ppmtompeg -frames) into a single MPEG stream.  Sequence
1ab173
-and GOP headers are inserted appropriately.  In this case, the
1ab173
-parameter file needs to contain only the SIZE value, the GOP_SIZE
1ab173
-value, an output file, and perhaps a list of frame files (see below).
1ab173
-
1ab173
-

The parameter file may specify input frame files in the same manner

1ab173
-as normal input files -- except instead of using INPUT_DIR, INPUT, and
1ab173
-END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT, and FRAME_END_INPUT. If
1ab173
-no input frame files are specified, then the default is to use the
1ab173
-output file name with suffix .frame.frame_num, with
1ab173
-frame_num starting from 0, as the input files.
1ab173
-     
1ab173
-
1ab173
-
1ab173
-
-nice
1ab173
-
1ab173
-
This option causes ppmtompeg to run any remote processes
1ab173
-"nicely," i.e.  at low priority.  (This is relevant only if you are
1ab173
-running ppmtompeg in parallel mode.  Otherwise, there are no
1ab173
-remote processes).  See 'man nice.'
1ab173
-
1ab173
-
-max_machines num_machines
1ab173
-
1ab173
-
This option causes ppmtompeg to use no more than
1ab173
-num_machines machines as slaves for use in parallel encoding.
1ab173
-
1ab173
-
-snr
1ab173
-
1ab173
-
This option causes ppmtompeg to include the signal-to-noise
1ab173
-ratio in the reported statistics.  Prints SNR (Y U V) and peak SNR (Y
1ab173
-U V) for each frame.  In summary, prints averages of luminance only
1ab173
-(Y).  SNR is defined as 10*log(variance of original/variance of
1ab173
-error).  Peak SNR is defined as 20*log(255/RMSE).  Note that
1ab173
-ppmtompeg runs a little slower when you use this option.
1ab173
-
1ab173
-
-mse
1ab173
-
1ab173
-
This option causes ppmtompeg to report the mean squared
1ab173
-error per block.  It also automatically reports the quality of the
1ab173
-images, so there is no need to specify -snr then.
1ab173
-
1ab173
-
-bit_rate_info rate_file
1ab173
-
1ab173
-
This option makes ppmtompeg write bit rate information
1ab173
-into the file rate_file.  Bit rate information is bits per frame, and
1ab173
-also bits per I-frame-to-I-frame.
1ab173
-
1ab173
-
-mv_histogram
1ab173
-
1ab173
-
This option causes ppmtompeg to print a histogram of the
1ab173
-motion vectors as part of statistics.  There are three histograms --
1ab173
-one for P frame, one for forward B frame, and one for backward B frame
1ab173
-motion vectors.
1ab173
-
1ab173
-

The output is in the form of a matrix, each entry corresponding to one

1ab173
-motion vector in the search window. The center of the matrix
1ab173
-represents (0,0) motion vectors.
1ab173
-
1ab173
-
-debug_sockets
1ab173
-
1ab173
-
This option causes ppmtompeg to print to Standard Output
1ab173
-messages that narrate the communication between the machines when you run
1ab173
-ppmtompeg in parallel mode.
1ab173
-
1ab173
-
-debug_machines
1ab173
-
1ab173
-
This option causes ppmtompeg to print to Standard Output
1ab173
-messages that narrate the progress of the conversion on the various
1ab173
-machines when you run ppmtompeg in parallel
1ab173
-mode.
1ab173
-     
1ab173
-
1ab173
-
1ab173
-

PARAMETER FILE

1ab173
-
1ab173
-

The parameter file must contain the following

1ab173
-lines (except when using the -combine_gops or -combine_frames
1ab173
-options):
1ab173
-
1ab173
-
1ab173
-
1ab173
-
PATTERN pattern
1ab173
-
1ab173
-
This statement specifies the pattern (sequence) of I frames, P frames,
1ab173
-and B frames.  pattern is just a sequence of the letters I, P, and
1ab173
-B with nothing between.  Example:
1ab173
-
1ab173
-
1ab173
-    PATTERN IBBPBBPBBPBBPBB
1ab173
-     
1ab173
-
1ab173
-

See I Frames, P Frames, B Frames.

1ab173
-
1ab173
-
OUTPUT output file
1ab173
-
This names the file where the output MPEG stream goes.
1ab173
-     
1ab173
-
INPUT_DIR directory
1ab173
-
1ab173
-
This statement tells where the input images (frames) come from.
1ab173
-If each frame is in a separate file, directory is the directory
1ab173
-where they all are.  You may use . to refer to the current 
1ab173
-directory.  A null directory refers to the root directory of the
1ab173
-system file tree.
1ab173
-
1ab173
-

To have ppmtompeg read all the frames serially from Standard

1ab173
-Input, specify
1ab173
-
1ab173
-    INPUT_DIR stdin
1ab173
-
1ab173
-
1ab173
-
INPUT
1ab173
-
1ab173
-This line must be followed by a list of the input files (in display order)
1ab173
-and then the line END_INPUT.
1ab173
-
1ab173
-

There are three types of lines between INPUT and END_INPUT. First,

1ab173
-a line may simply be the name of an input file.  Second, the line
1ab173
-may be of the form single_star_expr
1ab173
-[x-y].
1ab173
-single_star_expr can have a single * in it.  It is
1ab173
-replaced by all the numbers between x and y inclusive.  So, for
1ab173
-example, the line tennis*.ppm [12-15] refers to the files
1ab173
-tennis12.ppm, tennis13.ppm, tennis14.ppm, tennis15.ppm.
1ab173
-
1ab173
-

Uniform zero-padding occurs, as well. For example, the line

1ab173
-football.*.ppm [001-130] refers to the files football.001.ppm,
1ab173
-football.002.ppm, ..., football.009.ppm, football.010.ppm, ...,
1ab173
-football.130.ppm.
1ab173
-
1ab173
-

The third type of line is: single_star_expr

1ab173
-[x-y+s], where the
1ab173
-line is treated exactly as above, except that we skip by s.  Thus, the
1ab173
-line football.*.ppm [001-130+4] refers to the files
1ab173
-football.001.ppm, football.005.ppm, football.009.ppm,
1ab173
-football.013.ppm, etc.
1ab173
-
1ab173
-

Furthermore, a line may specify a shell command to execute to

1ab173
-generate lines to be interpreted as described above, as if those lines
1ab173
-were in the parameter file instead.  Use back ticks, like in the
1ab173
-Bourne Shell, like this:
1ab173
-
1ab173
-
1ab173
-    `cat myfilelist`
1ab173
-
1ab173
-
1ab173
-

1ab173
-If input is from Standard Input (per the INPUT_DIR statement), 
1ab173
-ppmtompeg ignores the INPUT/END_INPUT block, but
1ab173
-it still must be present.
1ab173
-     
1ab173
-
BASE_FILE_FORMAT {PPM | PNM | YUV |
1ab173
-     JPEG | JMOVIE}
1ab173
-
1ab173
-
ppmtompeg must convert all input files to one of the
1ab173
-following formats as a first step of processing: PNM, YUV, JPEG(v4),
1ab173
-or JMOVIE.  (The conversion may be trivial if your input files are
1ab173
-already in one of these formats).  This line specifies which of the
1ab173
-four formats.  PPM is actually a subset of PNM.  The separate
1ab173
-specification is allowed for backward compatibility.  Use PNM instead
1ab173
-of PPM in new applications.
1ab173
-
1ab173
-
INPUT_CONVERT conversion_command
1ab173
-
1ab173
-
You must specify how to convert a file to the base file format.
1ab173
-If no conversion is necessary, then you would just say:
1ab173
-
1ab173
-     
1ab173
-     INPUT_CONVERT *
1ab173
-     
1ab173
-     
1ab173
-

Otherwise, conversion_command is a shell command that causes

1ab173
-an image in the format your specified with BASE_FILE_FORMAT to
1ab173
-be written to Standard Output.  ppmtompeg executes the command
1ab173
-once for each line between INPUT and END_INPUT (which is
1ab173
-normally, but not necessarily, a file name).  In the conversion
1ab173
-command, ppmtompeg replaces each '*' with the contents of that
1ab173
-line.
1ab173
-     
1ab173
-     If you had a bunch of gif files, you might say:
1ab173
-     
1ab173
-     INPUT_CONVERT giftopnm *
1ab173
-     
1ab173
-
1ab173
-     If you have a bunch of separate a.Y, a.U, and a.V files (where
1ab173
-     the U and V have already been subsampled), then you might say:
1ab173
-
1ab173
-     
1ab173
-     INPUT_CONVERT cat *.Y *.U *.V
1ab173
-     
1ab173
-
1ab173
-

Input conversion is not allowed with input from stdin, so use

1ab173
-
1ab173
-     
1ab173
-     INPUT_CONVERT *
1ab173
-     
1ab173
-
1ab173
-as described above.
1ab173
-     
1ab173
-
SIZE widthxheight
1ab173
-
1ab173
-
1ab173
-
1ab173
-

width and height are the width and height of each

1ab173
-frame in pixels.
1ab173
-
1ab173
-

When ppmtompeg can get this information from the input image

1ab173
-files, it ignores the SIZE parameter and you may omit it.
1ab173
-
1ab173
-

When the image files are in YUV format, the files don't contain

1ab173
-dimension information, so SIZE is required.
1ab173
-
1ab173
-

When ppmtompeg is running in parallel mode, not all of the

1ab173
-processes in the network have access to the image files, so
1ab173
-SIZE is required and must give the same dimensions as the
1ab173
-input image files.
1ab173
-
1ab173
-
YUV_SIZE widthxheight
1ab173
-
1ab173
-
This is an obsolete synonym of SIZE.
1ab173
-
1ab173
-
YUV_FORMAT {ABEKAS | PHILLIPS | UCB |
1ab173
-                      EYUV | pattern}
1ab173
-
1ab173
-
This is meaningful only when BASE_FILE_FORMAT specifies
1ab173
-YUV format, and then it is required.  It specifies the sub-format of
1ab173
-the YUV class.
1ab173
-
1ab173
-
1ab173
-
GOP_SIZE n
1ab173
-
1ab173
-
n is the number of frames in a Group of Pictures. Except that
1ab173
-because a GOP must start with an I frame, ppmtompeg makes a GOP as
1ab173
-much longer than n as it has to to make the next GOP start with an
1ab173
-I frame. 
1ab173
-
1ab173
-

Normally, it makes sense to make your GOP size a multiple of your

1ab173
-pattern length (the latter is determined by the PATTERN parameter file
1ab173
-statement).
1ab173
-
1ab173
-

See Group Of Pictures.

1ab173
-
1ab173
-
SLICES_PER_FRAME n
1ab173
-
n is roughly the number of slices per frame. Note, at
1ab173
-least one MPEG player may complain if slices do not start at the left
1ab173
-side of an image.  To ensure this does not happen, make sure the
1ab173
-number of rows is divisible by SLICES_PER_FRAME.
1ab173
-
1ab173
-
PIXEL {FULL | HALF}
1ab173
-
1ab173
-
use half-pixel motion vectors, or just full-pixel ones It is
1ab173
-usually important that you use half-pixel motion vectors, because it
1ab173
-results in both better quality and better compression.
1ab173
-     
1ab173
-
1ab173
-
RANGE n
1ab173
-
Use a search range of n pixels in each of the four directions
1ab173
-from a subject pixel.  (So the search window is a square n*2 pixels
1ab173
-on a side).
1ab173
-
1ab173
-
PSEARCH_ALG {EXHAUSTIVE | TWOLEVEL |
1ab173
-     SUBSAMPLE | LOGARITHMIC}
1ab173
-
1ab173
-
This statement tells ppmtompeg what kind of search
1ab173
-    technique (algorithm) to use for P frames.  You select the desired
1ab173
-    combination of speed and compression.  EXHAUSTIVE gives the
1ab173
-    best compression, but LOGARITHMIC is the fastest.
1ab173
-    TWOLEVEL is an exhaustive full-pixel search, followed by a
1ab173
-    local half- pixel search around the best full-pixel vector (the
1ab173
-    PIXEL option is ignored for this search technique).
1ab173
-
1ab173
-
BSEARCH_ALG {SIMPLE | CROSS2 | EXHAUSTIVE}
1ab173
-
1ab173
-
This statement tells ppmtompeg what kind of search
1ab173
-    technique (algorithm) to use for B frames.  SIMPLE means
1ab173
-    find best forward and backward vectors, then interpolate.
1ab173
-    CROSS2 means find those two vectors, then see what backward
1ab173
-    vector best matches the best forward vector, and vice versa.
1ab173
-    EXHAUSTIVE does an n-squared search and is
1ab173
-    extremely slow in relation to the others (CROSS2
1ab173
-    is about half as fast as SIMPLE).
1ab173
-
1ab173
-
IQSCALE n
1ab173
-
Use n as the qscale for I frames.
1ab173
-     See Qscale.
1ab173
-
1ab173
-
PQSCALE n
1ab173
-
Use n as the qscale for P frames.
1ab173
-     See Qscale.
1ab173
-
1ab173
-
BQSCALE n
1ab173
-
Use n as the qscale for B frames.
1ab173
-     See Qscale.
1ab173
-
1ab173
-
REFERENCE_FRAME {ORIGINAL | DECODED}
This
1ab173
-statement determines whether ppmtompeg uses the original images
1ab173
-or the decoded images when computing motion vectors.  Using decoded
1ab173
-images is more accurate and should increase the playback quality of
1ab173
-the output, but it makes the encoding take longer and seems to give
1ab173
-worse compression.  It also causes some complications with parallel
1ab173
-encoding. (see the section on parallel encoding).  One thing you can
1ab173
-do as a trade-off is select ORIGINAL here, and lower the
1ab173
-qscale (see QSCALE if the quality is not good enough.
1ab173
-
1ab173
-
1ab173
-summary="comparison of original to decoded">
1ab173
-  <caption>Original or Decoded? (Normalized)</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Reference
1ab173
-    Compression
1ab173
-    Speed
1ab173
-    Quality I
1ab173
-    Quality P
1ab173
-    Quality B
1ab173
-    
1ab173
-  
1ab173
-    Decoded
1ab173
-    1000
1ab173
-    1000
1ab173
-    1000
1ab173
-    969
1ab173
-    919
1ab173
-    
1ab173
-  
1ab173
-    Original
1ab173
-    885
1ab173
-    1373
1ab173
-    1000
1ab173
-    912
1ab173
-    884
1ab173
-    
1ab173
-  
1ab173
-
1ab173
-
1ab173
-
1ab173
-
1ab173
-     
1ab173
-

The following lines are optional:

1ab173
-
1ab173
-
1ab173
-
1ab173
-
FORCE_ENCODE_LAST_FRAME
1ab173
-
1ab173
-
This statement is obsolete. It does nothing.
1ab173
-
1ab173
-

Before Netpbm 10.26 (January 2005), ppmtompeg would drop

1ab173
-trailing B frames from your movie, since a movie can't end with a B
1ab173
-frame.  (See I Frames, P Frames, B Frames.
1ab173
-You would have to specify FORCE_ENCODE_LAST_FRAME to stop
1ab173
-that from happening and get the same function that ppmtompeg
1ab173
-has today.
1ab173
-
1ab173
-
1ab173
-
NIQTABLE
1ab173
-
1ab173
-
This statement specifies a custom non-intra quantization table.
1ab173
-If you don't specify this statement, ppmtompeg uses a default
1ab173
-non-intra quantization table.
1ab173
-
1ab173
-

1ab173
-The 8 lines immediately following NIQTABLE specify the quantization
1ab173
-table.  Each line defines a table row and consists of 8 integers,
1ab173
-whitespace-delimited, which define the table columns.
1ab173
-
1ab173
-
IQTABLE
1ab173
-
1ab173
-
This is analogous to NIQTABLE, but for the intra quantization table.
1ab173
-
1ab173
-
ASPECT_RATIO ratio
1ab173
-
1ab173
-
This statement specifies the aspect ratio for ppmtompeg to
1ab173
-specify in the MPEG output.  I'm not sure what this is used for.
1ab173
-
1ab173
-

ratio must be 1.0, 0.6735, 0.7031, 0.7615, 0.8055, 0.8437,

1ab173
-0.8935, 0.9157, 0.9815, 1.0255, 1.0695, 1.0950, 1.1575, or 1.2015.
1ab173
-
1ab173
-
FRAME_RATE rate
1ab173
-
This specifies the frame rate for ppmtompeg to specify in the
1ab173
-MPEG output.  Some players use this value to determine the playback rate.
1ab173
-
1ab173
-

rate must be 23.976, 24, 25, 29.97, 30, 50, 59.94, or 60.

1ab173
-
1ab173
-
BIT_RATE rate
1ab173
-
This specifies the bit rate for Constant Bit Rate (CBR) encoding.
1ab173
-
1ab173
-

rate must be an integer.

1ab173
-
1ab173
-
BUFFER_SIZE size
1ab173
-
1ab173
-
This specifies the value
1ab173
-ppmtompeg is to specify in the MPEG output for the Video
1ab173
-Buffering Verifier (VBV) buffer size needed to decode the sequence.
1ab173
-
1ab173
-

A Video Verifying Buffer is a buffer in which a decoder keeps the

1ab173
-decoded bits in order to match the uneven speed of the decoding with
1ab173
-the required constant playback speed.
1ab173
-
1ab173
-

As ppmtompeg encodes the image, it simulates the decoding

1ab173
-process in terms of how many bits would be in the VBV as each frame gets
1ab173
-decoded, assuming a VBV of the size you indicate.  
1ab173
-
1ab173
-

If you specify the WARN_VBV_UNDERFLOW statement,

1ab173
-ppmtompeg issues a warning each time the simulation underflows
1ab173
-the buffer, which suggests that an underflow would occur on playback,
1ab173
-which suggests the buffer is too small.
1ab173
-
1ab173
-

If you specify the WARN_VBV_OVERFLOW statement,

1ab173
-ppmtompeg issues a warning each time the simulation overflows
1ab173
-the buffer, which suggests that an overflow would occur on playback,
1ab173
-which suggests the buffer is too small.
1ab173
-
1ab173
-
WARN_VBV_UNDERFLOW
1ab173
-
WARN_VBV_OVERFLOW
1ab173
-
1ab173
-
See BUFFER_SIZE.
1ab173
-
1ab173
-

These options were new in Netpbm 10.26 (January 2005). Before that,

1ab173
-ppmtompeg issued the warnings always.
1ab173
-
1ab173
-
1ab173
-
1ab173
-
1ab173
-The following statements apply only to parallel operation:
1ab173
-
1ab173
-
1ab173
-
1ab173
-
PARALLEL
1ab173
-
1ab173
-
This statement, paired with END PARALLEL, is what causes
1ab173
-ppmtompeg to operate in parallel mode.  See 
1ab173
-href="#parallel">Parallel Operation.
1ab173
-
1ab173
-
END PARALLEL
1ab173
-
1ab173
-
This goes with PARALLEL.
1ab173
-
1ab173
-
PARALLEL_TEST_FRAMES n
1ab173
-
1ab173
-
The master starts off by measuring each slave's speed. It does
1ab173
-this by giving each slave n frames to encode and noting how
1ab173
-long the slave takes to finish.  These are not just test frames,
1ab173
-though -- they're real frames and the results become part of the
1ab173
-output.
1ab173
-ppmtompeg is old and measures time in undivided seconds, so
1ab173
-to get useful timings, specify enough frames that it will take at
1ab173
-least 5 seconds to process them.  The default is 10.
1ab173
-
1ab173
-

If you specify FORCE_I_ALIGN, ppmtompeg will increase

1ab173
-the test frames value enough to maintain the alignment.
1ab173
-
1ab173
-

If there aren't enough frames for every slave to have the indicated

1ab173
-number of test frames, ppmtompeg will give some slaves fewer.
1ab173
-
1ab173
-
1ab173
-
PARALLEL_TIME_CHUNKS t
1ab173
-
1ab173
-
When you specify this statement, the master attempts to feed work
1ab173
-to the slaves in chunks that take t seconds to process.  It uses
1ab173
-the speed measurement it made when it started up (see PARALLEL_TEST_FRAMES)
1ab173
-to decide how many frames to put in the chunk.  This statement obviously
1ab173
-doesn't affect the first batch of work sent to each slave, which is the
1ab173
-one used to measure the slave's speed.
1ab173
-
1ab173
-

Smaller values of t increase communication, but improve load

1ab173
-balancing.  The default is 30 seconds.
1ab173
-
1ab173
-

You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER,

1ab173
-and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.
1ab173
-
1ab173
-
PARALLEL_CHUNK_TAPER
1ab173
-
1ab173
-
When you specify this statement, the master distributes work like
1ab173
-with PARALLEL_TIME_CHUNKS, except that the master chooses the number
1ab173
-of seconds for the chunks.  It starts with a large number and, as it
1ab173
-gets closer to finishing the job, reduces it.  That way, it reduces
1ab173
-scheduling overhead when precise scheduling isn't helpful, but still
1ab173
-prevents a slave from finishing early after all the work has already
1ab173
-been handed out to the other slaves, and then sitting idle while
1ab173
-there's still work to do.
1ab173
-
1ab173
-

You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER,

1ab173
-and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.
1ab173
-
1ab173
-
1ab173
-
PARALLEL_PERFECT
1ab173
-
1ab173
-
If this statement is present, ppmtompeg schedules on the
1ab173
-assumption that each machine is about the same speed.  The master will
1ab173
-simply divide up the frames evenly between the slaves -- each
1ab173
-slave gets the same number of frames.  If some slaves are faster than
1ab173
-others, they will finish first and remain idle while the slower slaves
1ab173
-continue.  
1ab173
-
1ab173
-

This has the advantage of minimal scheduling overhead. Where slaves

1ab173
-have different speeds, though, it makes inefficient use of the fast
1ab173
-ones.  Where slaves are the same speed, it also has the disadvantage
1ab173
-that they all finish at the same time and feed their output to the
1ab173
-single Combine Server in a burst, which makes less efficient use of
1ab173
-the Combine Server and thus can increase the total elapsed time.
1ab173
-
1ab173
-

You may specify only one of PARALLEL_TIME_CHUNKS, PARALLEL_CHUNK_TAPER,

1ab173
-and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.
1ab173
-
1ab173
-
RSH remote_shell_command
1ab173
-
1ab173
-
ppmtompeg executes the shell command
1ab173
-remote_shell_command to start a process on another machine.
1ab173
-The default command is rsh, and whatever command you specify
1ab173
-must have compatible semantics.  ssh is usually compatible.
1ab173
-The command ppmtompeg uses is one like this:
1ab173
-ssh remote.host.com -l username shellcommand.
1ab173
-
1ab173
-

Be sure to set up .rhosts files or SSH key authorizations

1ab173
-where needed.  Otherwise, you'll have to type in passwords.
1ab173
-
1ab173
-

On some HP machines, rsh is the restricted shell, and you want

1ab173
-to specify remsh.
1ab173
-
1ab173
-
FORCE_I_ALIGN
1ab173
-
1ab173
-
This statement forces each slave to encode a chunk of frames which
1ab173
-is a multiple of the pattern length (see PATTERN).  Since the
1ab173
-first frame in any pattern is an I frame, this forces each chunk
1ab173
-encoded by a slave to begin with an I frame.
1ab173
-
1ab173
-

This document used to say there was an argument to

1ab173
-FORCE_I_ALIGN which was the number of frames ppmtompeg
1ab173
-would use (and was required to be a multiple of the pattern length).
1ab173
-But ppmtompeg has apparently always ignored that argument, and
1ab173
-it does now.
1ab173
-
1ab173
-
KEEP_TEMP_FILES
1ab173
-
1ab173
-
This statement causes ppmtompeg not to delete the temporary
1ab173
-files it uses to transmit encoded frames to the combine server.  This
1ab173
-means you will be left with a file for each frame, the same as you
1ab173
-would get with the -frames option.  
1ab173
-
1ab173
-

This is mostly useful for debugging.

1ab173
-
1ab173
-

This works only if you're using a shared filesystem to communicate

1ab173
-between the servers.
1ab173
-
1ab173
-

This option was new in Netpbm 10.26 (January 2005).

1ab173
-
1ab173
-
1ab173
-
1ab173
-
1ab173
-

Parameter File Notes

1ab173
-
1ab173
-

If you use the -combine_gops option, then you need to specify

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

If you use the -combine_frames option, then you need to

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

Any number of spaces and tabs may come between each option and value. Lines

1ab173
-beginning with # are ignored.  Any other lines are ignored except for
1ab173
-those between INPUT and END_INPUT.  This allows you to use the same
1ab173
-parameter file for normal usage and for -combine_gops and
1ab173
--combine_frames.
1ab173
-
1ab173
-

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

1ab173
-upper case.
1ab173
-
1ab173
-

The statements may appear in any order, except that the order within

1ab173
-a block statement (such as INPUT ... END INPUT) is significant.
1ab173
-
1ab173
-

ppmtompeg is prepared to handle up to 16 B frames between

1ab173
-reference frames when encoding with input from stdin.  (To build a
1ab173
-modified ppmtompeg with a higher limit, change the constant
1ab173
-B_FRAME_RUN in frame.c and recompile).
1ab173
-
1ab173
-

GENERAL USAGE INFORMATION

1ab173
-
1ab173
-

Qscale

1ab173
-
1ab173
-

The quantization scale values (qscale) give a trade-off between

1ab173
-quality and compression.  Using different Qscale values has very little
1ab173
-effect on speed.  The qscale values can be set separately for I, P, and
1ab173
-B frames.
1ab173
-
1ab173
-

You select the qscale values with the IQSCALE,

1ab173
-PQSCALE, and BSCALE parameter file statements.
1ab173
-
1ab173
-

A qscale value is an integer from 1 to 31. Larger numbers give

1ab173
-better compression, but worse quality.  In the following, the quality
1ab173
-numbers are peak signal-to-noise ratio, defined as:
1ab173
-signal-to-noise formula
1ab173
-where MSE is the mean squared error.
1ab173
-     
1ab173
-
1ab173
-

Flower garden tests:

1ab173
-
1ab173
-
1ab173
-  <caption>Qscale vs Quality</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Qscale
1ab173
-    I Frames
1ab173
-    P Frames
1ab173
-    B Frames
1ab173
-    
1ab173
-  
1ab173
-    1
1ab173
-    43.2
1ab173
-    46.3
1ab173
-    46.5
1ab173
-    
1ab173
-  
1ab173
-    6
1ab173
-    32.6
1ab173
-    34.6
1ab173
-    34.3
1ab173
-    
1ab173
-  
1ab173
-    11
1ab173
-    28.6
1ab173
-    29.5
1ab173
-    30.0
1ab173
-    
1ab173
-  
1ab173
-    16
1ab173
-    26.3
1ab173
-    26.8
1ab173
-    28.6
1ab173
-    
1ab173
-  
1ab173
-    21
1ab173
-    24.7
1ab173
-    25.0
1ab173
-    27.9
1ab173
-    
1ab173
-  
1ab173
-    26
1ab173
-    23.5
1ab173
-    23.9
1ab173
-    27.5
1ab173
-    
1ab173
-  
1ab173
-    31
1ab173
-    22.6
1ab173
-    23.0
1ab173
-    27.3
1ab173
-    
1ab173
-
1ab173
-
1ab173
-
1ab173
-summary="Qscale vs Compression">
1ab173
-  <caption>Qscale vs Compression</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Qscale
1ab173
-    I Frames
1ab173
-    P Frames
1ab173
-    B Frames
1ab173
-    
1ab173
-  
1ab173
-    1
1ab173
-    2
1ab173
-    2
1ab173
-    2
1ab173
-    
1ab173
-  
1ab173
-    6
1ab173
-    7
1ab173
-    10
1ab173
-    15
1ab173
-    
1ab173
-  
1ab173
-    11
1ab173
-    11
1ab173
-    18
1ab173
-    43
1ab173
-    
1ab173
-  
1ab173
-    16
1ab173
-    15
1ab173
-    29
1ab173
-    97
1ab173
-    
1ab173
-  
1ab173
-    21
1ab173
-    19
1ab173
-    41
1ab173
-    173
1ab173
-    
1ab173
-  
1ab173
-    26
1ab173
-    24
1ab173
-    56
1ab173
-    256
1ab173
-    
1ab173
-  
1ab173
-    31
1ab173
-    28
1ab173
-    73
1ab173
-    330
1ab173
-    
1ab173
-
1ab173
-
1ab173
-
1ab173
-

Search Techniques

1ab173
-     
1ab173
-

There are several different motion vector search techniques

1ab173
-available.  There are different techniques available for P frame
1ab173
-search and B frame search. Using different search techniques present
1ab173
-little difference in quality, but a large difference in compression
1ab173
-and speed.
1ab173
-     
1ab173
-

There are 4 types of P frame search: Exhaustive, TwoLevel,

1ab173
-SubSample, and Logarithmic.
1ab173
-     
1ab173
-

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

1ab173
-Simple.
1ab173
-     
1ab173
-The recommended search techniques are TwoLevel and Logarithmic for
1ab173
-P frame search, and Cross2 and Simple for B frame search. Here are
1ab173
-some numbers comparing the different search methods:
1ab173
-     
1ab173
-
1ab173
-summary="P frame motion vector search">
1ab173
-  <caption>P frame Motion Vector Search (Normalized)</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Technique
1ab173
-    Compression<sup>1</sup>
1ab173
-    Speed      <sup>2</sup>
1ab173
-    Quality    <sup>3</sup>
1ab173
-    
1ab173
-  
1ab173
-    Exhaustive
1ab173
-    1000
1ab173
-    1000
1ab173
-    1000
1ab173
-    
1ab173
-  
1ab173
-    SubSample
1ab173
-    1008
1ab173
-    2456
1ab173
-    1000
1ab173
-    
1ab173
-  
1ab173
-    TwoLevel
1ab173
-    1009
1ab173
-    3237
1ab173
-    1000
1ab173
-    
1ab173
-  
1ab173
-    Logarithmic
1ab173
-    1085
1ab173
-    8229
1ab173
-    998
1ab173
-    
1ab173
-
1ab173
-
1ab173
-
1ab173
-summary="B frame motion vector search">
1ab173
-  <caption>B frame Motion Vector Search (Normalized)</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Technique
1ab173
-    Compression<sup>1</sup>
1ab173
-    Speed<sup>2</sup>
1ab173
-    Quality<sup>3</sup>
1ab173
-    
1ab173
-  
1ab173
-    Exhaustive
1ab173
-    1000
1ab173
-    1000
1ab173
-    1000
1ab173
-    
1ab173
-  
1ab173
-    Cross2
1ab173
-    975
1ab173
-    1000
1ab173
-    996
1ab173
-    
1ab173
-  
1ab173
-    Simple
1ab173
-    938
1ab173
-    1765
1ab173
-    991
1ab173
-    
1ab173
-
1ab173
-
1ab173
- <sup>1</sup>Smaller numbers are better
1ab173
-compression.
1ab173
-
1ab173
- <sup>2</sup>Larger numbers mean faster
1ab173
-execution.
1ab173
-
1ab173
- <sup>3</sup>Larger numbers mean better quality.
1ab173
-
1ab173
-

For some reason, Simple seems to give better compression, but it

1ab173
-depends on the image sequence.
1ab173
-
1ab173
-

Select the search techniques with the PSEARCH_ALG and

1ab173
-BSEARCH_ALG parameter file statements.
1ab173
-
1ab173
-
1ab173
-
1ab173
-

Group Of Pictures (GOP)

1ab173
-
1ab173
-

A Group of Pictures (GOP) is a roughly independently decodable

1ab173
-sequence of frames.  An MPEG video stream is made of one or more
1ab173
-GOP's.  You may specify how many frames should be in each GOP with the
1ab173
-GOP_SIZE parameter file statement.  A GOP always starts with an
1ab173
-I frame.
1ab173
-
1ab173
-

Instead of encoding an entire sequence, you can encode a single

1ab173
-GOP.  To do this, use the -gop command option.  You can later
1ab173
-join the resulting GOP files at any time by running ppmtompeg
1ab173
-with the -combine_gops command option.
1ab173
-     
1ab173
-     
1ab173
-

Slices

1ab173
-
1ab173
-

A slice is an independently decodable unit in a frame. It can be

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

Control the slice size with the SLICES_PER_FRAME parameter

1ab173
-file statement.
1ab173
-
1ab173
-

Some MPEG playback systems require that each slice consist of whole

1ab173
-rows of macroblocks.  If you are encoding for this kind of player, if
1ab173
-the height of the image is H pixels, then you should set the
1ab173
-SLICES_PER_FRAME to some number which divides H/16.  For example, if
1ab173
-the image is 240 pixels (15 macroblocks) high, then you should use
1ab173
-only 15, 5, 3, or 1 slices per frame.
1ab173
-     
1ab173
-

Note: these MPEG playback systems are really wrong, since the MPEG

1ab173
-standard says this doesn't have to be so.
1ab173
-
1ab173
-
1ab173
-
1ab173
-

Search Window

1ab173
-     
1ab173
-

The search window is the window in which ppmtompeg searches

1ab173
-for motion vectors.  The window is a square.  You can specify the size
1ab173
-of the square, and whether to allow half-pixel motion vectors or not,
1ab173
-with the RANGE and PIXEL parameter file statements.
1ab173
-
1ab173
-

I Frames, P Frames, B Frames

1ab173
-
1ab173
-

In MPEG-1, a movie is represented as a sequence of MPEG frames,

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

An I frame ("intra" frame) describes a movie frame in isolation --

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

Note that the first frame of a movie must be described by an I

1ab173
-frame (because there is no previous movie frame) and the last movie
1ab173
-frame must be described by an I or P frame (because there is no
1ab173
-subsequent movie frame).
1ab173
-
1ab173
-

Beyond that, you can choose which frames are represented by which

1ab173
-types.  You specify a pattern, such as IBPBP and ppmtompeg
1ab173
-simply repeats it over and over throughout the movie.  The pattern
1ab173
-affects speed, quality, and stream size.  Here is a chart which shows
1ab173
-some of the trade-offs:
1ab173
-
1ab173
-
1ab173
-summary="Comparison of I/P/B Frames">
1ab173
-  <caption>Comparison of I/P/B Frames (Normalized)</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Frame Type
1ab173
-    Size
1ab173
-    Speed
1ab173
-    Quality
1ab173
-    
1ab173
-  
1ab173
-    I frames
1ab173
-    1000
1ab173
-    1000
1ab173
-    1000
1ab173
-    
1ab173
-  
1ab173
-    P frames
1ab173
-    409
1ab173
-    609
1ab173
-    969
1ab173
-    
1ab173
-  
1ab173
-    B frames
1ab173
-    72
1ab173
-    260
1ab173
-    919
1ab173
-    
1ab173
-  
1ab173
-
1ab173
-(this is with constant qscale)
1ab173
-     
1ab173
-

A standard sequence is IBBPBBPBBPBBPBB.

1ab173
-     
1ab173
-

Select the sequence with the PATTERN parameter file statement.

1ab173
-
1ab173
-

Since the last MPEG frame cannot be a B frame (see above), if the

1ab173
-pattern you specify indicates a B frame for the last movie frame of
1ab173
-the movie, ppmtompeg makes it an I frame instead.
1ab173
-
1ab173
-

Before Netpbm 10.26 (January 2005), ppmtompeg instead drops

1ab173
-the trailing B frames by default, and you need the
1ab173
-FORCE_ENCODE_LAST_FRAME parameter file statement to make it do
1ab173
-this.
1ab173
-
1ab173
-

The MPEG frames don't appear in the MPEG-1 stream in the same order that

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

Specifying Input and Output Files

1ab173
-
1ab173
-

Specify the input frame images with the INPUT_DIR,

1ab173
-INPUT, END_INPUT, BASE_FILE_FORMAT,
1ab173
-SIZE, YUV_FORMAT and INPUT_CONVERT parameter
1ab173
-file statements.
1ab173
-
1ab173
-

Specify the output file with the OUTPUT parameter file statement.

1ab173
-
1ab173
-
1ab173
-

Statistics

1ab173
-
1ab173
-

ppmtompeg can generate a variety of statistics about the

1ab173
-encoding.  See the -stat, -snr, -mv_histogram,
1ab173
--quiet, -no_frame_summary, and -bit_rate_info
1ab173
-options.
1ab173
-     
1ab173
-
1ab173
-

PARALLEL OPERATION

1ab173
-
1ab173
-

You can run ppmtompeg on multiple machines at once, encoding

1ab173
-the same MPEG stream.  When you do, the machines are used as shown in
1ab173
-the following diagram.  We call this "parallel mode."
1ab173
-
1ab173
-

ppmtompeg-par.gif

1ab173
-
1ab173
-

To do parallel processing, put the statement

1ab173
-
1ab173
-
1ab173
-    PARALLEL
1ab173
-
1ab173
-
1ab173
-in the parameter file, followed by a listing of the machines, one
1ab173
-machine per line, then
1ab173
-
1ab173
-
1ab173
-    END_PARALLEL
1ab173
-
1ab173
-
1ab173
-Each of the machine lines must be in one of two forms.  If the machine
1ab173
-has filesystem access to the input files, then the line is:
1ab173
-
1ab173
-

1ab173
-machine user executable
1ab173
-
1ab173
-

The executable is normally ppmtompeg (you may need to give

1ab173
-the complete path if you've built for different architectures).  If
1ab173
-the machine does not have filesystem access to the input files, the line
1ab173
-is:
1ab173
-
1ab173
-

REMOTE machine user executable

1ab173
-parameter file
1ab173
-
1ab173
-

The -max_machines command option limits the number of

1ab173
-machines ppmtompeg will use.  If you specify more machines in
1ab173
-the parameter file than -max_machines allows, ppmtompeg
1ab173
-uses only the machines listed first.  This is handy if you want to
1ab173
-experiment with different amounts of parallelism.
1ab173
-
1ab173
-

In general, you should use full path file names when describing

1ab173
-executables and parameter files.  This includes the parameter
1ab173
-file argument on the original invocation of ppmtompeg.
1ab173
-
1ab173
-

All file names must be the same on all systems (so if e.g. you're

1ab173
-using an NFS filesystem, you must make sure it is mounted at the same
1ab173
-mountpoint on all systems).
1ab173
-
1ab173
-

Because not all of the processes involved in parallel operation

1ab173
-have easy access to the input files, you must specify the SIZE
1ab173
-parameter file statement when you do parallel operation.
1ab173
-
1ab173
-

The machine on which you originally invoke ppmtompeg is the

1ab173
-master machine.  It hosts a "combine server,", a
1ab173
-"decode server," and a number of "i/o servers,"
1ab173
-all as separate processes.  The other machines in the network (listed
1ab173
-in the parameter file) are slave machines.  Each hosts a single
1ab173
-process that continuously requests work from the master and does it.
1ab173
-The slave process does the computation to encode MPEG frames.  It
1ab173
-processes frames in batches identified by the master.
1ab173
-
1ab173
-

The master uses a remote shell command to start a process on a

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

The various machines talk to each other over TCP connections. Each

1ab173
-machine finds and binds to a free TCP port number and tells its
1ab173
-partners the port number.  These port numbers are at least 2048.
1ab173
-
1ab173
-

Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS, and

1ab173
-PARALLEL_PERFECT parameter file statements to control the way the
1ab173
-master divides up work among the slaves.
1ab173
-
1ab173
-

Use the -nice command option to cause all slave processes to run

1ab173
-"nicely," i.e. as low priority processes.  That way, this substantial and
1ab173
-long-running CPU load will have minimal impact on other, possibly
1ab173
-interactive, users of the systems.
1ab173
-
1ab173
- 
1ab173
-

SPEED

1ab173
-
1ab173
-

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

1ab173
-operation:
1ab173
-
1ab173
-
1ab173
-  <caption>Compression Speed</caption>
1ab173
-
1ab173
-
1ab173
-  
1ab173
-    Machine Type
1ab173
-    Macroblocks per second<sup>1</sup>
1ab173
-    
1ab173
-  
1ab173
-    HP 9000/755
1ab173
-    280
1ab173
-    
1ab173
-  
1ab173
-    DEC 3000/400
1ab173
-    247
1ab173
-    
1ab173
-  
1ab173
-    HP 9000/750
1ab173
-    191
1ab173
-    
1ab173
-  
1ab173
-    Sparc 10
1ab173
-    104
1ab173
-    
1ab173
-  
1ab173
-    DEC 5000
1ab173
-    68
1ab173
-    
1ab173
-
1ab173
-<sup>1</sup>A macroblock is a 16x16 pixel square
1ab173
-
1ab173
-

The measurements in the table are with inputs and outputs via a

1ab173
-conventional locally attached filesystem.  If you are using a network
1ab173
-filesystem over a single 10 MB/s Ethernet, that constrains your speed more
1ab173
-than your CPU speed.  In that case, don't expect to get better than 4
1ab173
-or 5 frames per second no matter how fast your CPUs are.
1ab173
-
1ab173
-

Network speed is even more of a bottleneck when the slaves do not

1ab173
-have filesystem access to the input files -- i.e. you declare them
1ab173
-REMOTE.
1ab173
-
1ab173
-

Where I/O is the bottleneck, size of the input frames can make a big

1ab173
-difference.  So YUV input is better than PPM, and JPEG is better than
1ab173
-both.
1ab173
-
1ab173
-

When you're first trying to get parallel mode working, be sure to

1ab173
-use the -debug_machines option so you can see what's going on.
1ab173
-Also, -debug_sockets can help you diagnose communication
1ab173
-problems.
1ab173
-
1ab173
-
1ab173
-

AUTHORS

1ab173
-
1ab173
-
    1ab173
    -
    1ab173
    -
  • Kevin Gong - University of California, Berkeley,
  • 1ab173
    -HREF="mailto:keving@cs.berkeley.edu">keving@cs.berkeley.edu
    1ab173
    -
    1ab173
    -
  • Ketan Patel - University of California, Berkeley,
  • 1ab173
    -HREF="mailto:kpatel@cs.berkeley.edu">kpatel@cs.berkeley.edu
    1ab173
    -
    1ab173
    -
  • Dan Wallach - University of California, Berkeley,
  • 1ab173
    -HREF="mailto:dwallach@cs.berkeley.edu">dwallach@cs.berkeley.edu
    1ab173
    -
    1ab173
    -
  • Darryl Brown - University of California, Berkeley,
  • 1ab173
    -HREF="mailto:darryl@cs.berkeley.edu">darryl@cs.berkeley.edu
    1ab173
    -
    1ab173
    -
  • Eugene Hung - University of California, Berkeley,
  • 1ab173
    -HREF="mailto:eyhung@cs.berkeley.edu">eyhung@cs.berkeley.edu
    1ab173
    -
    1ab173
    -
  • Steve Smoot - University of California, Berkeley,
  • 1ab173
    -HREF="mailto:smoot@cs.berkeley.edu">smoot@cs.berkeley.edu
    1ab173
    -
    1ab173
    -
    1ab173
    -
    1ab173
    -
    1ab173
    - 
    1ab173
    -

    Table Of Contents

    1ab173
    -
      1ab173
      -
    • SYNOPSIS
    • 1ab173
      -
    • DESCRIPTION
    • 1ab173
      -
    • OPTIONS
    • 1ab173
      -
    • PARAMETER FILE
    • 1ab173
      -
    • GENERAL USAGE INFORMATION
    • 1ab173
      -
    • PARALLEL OPERATION
    • 1ab173
      -
    • SPEED
    • 1ab173
      -
    • AUTHORS
    • 1ab173
      -
      1ab173
      -</BODY>
      1ab173
      -</HTML>