Provided by: netpbm_11.01.00-2build1_amd64 bug

NAME

       ppmtompeg - encode an MPEG-1 bitstream

SYNOPSIS

       ppmtompeg [options] parameter-file

DESCRIPTION

       This program is part of Netpbm(1).

       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 produces is MPEG-1.

       Mencoder from the Mplayer package ⟨http://www.mplayerhq.hu⟩  is probably superior for most
       video format generation needs, if for no other reason than that it is more popular.

       The programming library PM2Vhttp://pm2v.free.fr⟩  generates MPEG-2 streams.

       Use  Mplayer ⟨http://www.mplayerhq.hu⟩  (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 ⟨http://www.faqs.org/faqs/compression-faq/⟩ .

OPTIONS

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

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

              These statistics include how many I, P, and B frames there  were,  and  information
              about compression and quality.

       -quiet num_seconds
               causes  ppmtompeg  not  to report remaining time more often than every num_seconds
              seconds (unless the time estimate rises, which will happen near  the  beginning  of
              the run).  A negative value tells ppmtompeg not to report at all.  0 is the default
              (reports once after each frame).  Note that the time remaining is an  estimate  and
              does not take into account time to read in frames.

       -realquiet
               causes  ppmtompeg  to  run  silently,  with  the  only screen output being errors.
              Particularly useful when reading input from stdin.  The equivalent  of  the  -quiet
              common option of most other Netpbm programs.

       -no_frame_summary
               This option prevents ppmtompeg from printing a summary line for each frame

       -float_dct
               forces  ppmtompeg  to  use  a  more  accurate,  yet more computationally expensive
              version of the DCT.

       -gop gop_num
              causes ppmtompeg to encode only the numbered GOP (first GOP is 0).   The  parameter
              file  is  the  same as for normal usage.  The output file will be the normal output
              file with  the  suffix  .gop.gop_num.   ppmtompeg  does  not  output  any  sequence
              information.

       -combine_gops
               causes  ppmtompeg  simply  to  combine  some  GOP  files into a single MPEG output
              stream.  ppmtompeg inserts a sequence  header  and  trailer.   In  this  case,  the
              parameter  file needs only to contain the SIZE value, an output file, and perhaps a
              list of input GOP files (see below).

              If you don't supply a list of input GOP  files  is  used,  then  ppmtompeg  assumes
              you're  using the same parameter file you used when you created the input (with the
              -gop option) and calculates the corresponding gop filenames itself.  If this is not
              the  case, you can specify input GOP files in the same manner as normal input files
              -- except instead of using INPUT_DIR,  INPUT,  and  END_INPUT,  use  GOP_INPUT_DIR,
              GOP_INPUT,  and  GOP_END_INPUT.   If  no  input  GOP  files are specified, then the
              default is to use the output file  name  with  suffix  .gop.gop_num,  with  gop_num
              starting from 0, as the input files.

              Thus,  unless  you're mixing and matching GOP files from different sources, you can
              simply use the same parameter file for creating the GOP files (-gop) and for  later
              turning them into an MPEG stream (-combine_gops).

       -frames first_frame last_frame
              This  option  causes  ppmtompeg  to  encode only the frames numbered first_frame to
              last_frame, inclusive.  The parameter file is the same as for  normal  usage.   The
              output  will  be placed in separate files, one per frame, with the file names being
              the normal output file name  with  the  suffix  .frame.frame_num.   No  GOP  header
              information  is  output.   (Thus,  the parameter file need not include the GOP_SIZE
              value)

              Use ppmtompeg -combine_frames to combine these frames later into an MPEG stream.

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

              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.

       -nice  This option causes ppmtompeg to run any remote processes  "nicely,"  i.e.   at  low
              priority.   (This  is  relevant only if you are running ppmtompeg in parallel mode.
              Otherwise, there are no remote processes).  See 'man nice.'

       -max_machines num_machines
              This option causes ppmtompeg to use no more than num_machines  machines  as  slaves
              for use in parallel encoding.

       -snr   This  option  causes ppmtompeg to include the signal-to-noise ratio in the reported
              statistics.  Prints SNR (Y U V) and peak SNR (Y U V) for each frame.   In  summary,
              prints  averages  of  luminance  only  (Y).   SNR  is defined as 10*log(variance of
              original/variance of error).  Peak SNR is defined as 20*log(255/RMSE).   Note  that
              ppmtompeg runs a little slower when you use this option.

       -mse   This  option  causes ppmtompeg to report the mean squared error per block.  It also
              automatically reports the quality of the images, so there is  no  need  to  specify
              -snr then.

       -bit_rate_info rate_file
               This  option  makes  ppmtompeg write bit rate information into the file rate_file.
              Bit rate information is bits per frame, and also bits per I-frame-to-I-frame.

       -mv_histogram
               This option causes ppmtompeg to print a histogram of the motion vectors as part of
              statistics.   There  are  three  histograms  --  one for P frame, one for forward B
              frame, and one for backward B frame motion vectors.

              The output is in the form of a matrix,  each  entry  corresponding  to  one  motion
              vector  in  the  search  window.  The  center of the matrix represents (0,0) motion
              vectors.

       -debug_sockets
              This option causes ppmtompeg to print to Standard Output messages that narrate  the
              communication  between  the  machines  when  you  run  ppmtompeg  in  parallel mode
              ⟨#parallel⟩ .

       -debug_machines
              This option causes ppmtompeg to print to Standard Output messages that narrate  the
              progress  of  the  conversion  on  the  various  machines when you run ppmtompeg in
              parallel mode ⟨#parallel⟩ .

PARAMETER FILE

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

       PATTERN pattern
              This  statement  specifies  the  pattern  (sequence)  of  I frames, P frames, and B
              frames.  pattern is just a sequence of  the  letters  I,  P,  and  B  with  nothing
              between.  Example:

                  PATTERN IBBPBBPBBPBBPBB
              </pre>

              See
              I Frames, P Frames, B Frames
              ⟨#ipb⟩
              .

       OUTPUT output file
              This names the file where the output MPEG stream goes.

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

              To have ppmtompeg read all the frames serially from Standard
              Input, specify
                  INPUT_DIR stdin

       INPUT  This line must be followed by a list of the input files (in display order) and then
              the line END_INPUT.

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

              Uniform  zero-padding  occurs,  as  well.   For  example,  the  line football.*.ppm
              [001-130]  refers   to   the   files   football.001.ppm,   football.002.ppm,   ...,
              football.009.ppm, football.010.ppm, ..., football.130.ppm.

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

              Furthermore, a line may specify a shell command to execute to generate lines to  be
              interpreted  as  described  above,  as  if  those  lines were in the parameter file
              instead.  Use back ticks, like in the Bourne Shell, like this:

                  `cat myfilelist`

              If input is from Standard Input (per the INPUT_DIR  statement),  ppmtompeg  ignores
              the INPUT/END_INPUT block, but it still must be present.

       BASE_FILE_FORMAT {PPM | PNM | YUV |
                   JPEG  | JMOVIE} ppmtompeg must convert all input files to one of the following
              formats as a first step  of  processing:  PNM,  YUV,  JPEG(v4),  or  JMOVIE.   (The
              conversion may be trivial if your input files are already in one of these formats).
              This line specifies which of the four formats.  PPM is actually a  subset  of  PNM.
              The  separate specification is allowed for backward compatibility.  Use PNM instead
              of PPM in new applications.

       INPUT_CONVERT conversion_command
              You must specify how to convert a file to the base file format.  If  no  conversion
              is necessary, then you would just say:

                   INPUT_CONVERT *

              Otherwise, conversion_command is a shell command that causes an image in the format
              your specified with BASE_FILE_FORMAT to be written to Standard  Output.   ppmtompeg
              executes  the  command  once  for  each  line between INPUT and END_INPUT (which is
              normally, but not necessarily, a file name).  In the conversion command,  ppmtompeg
              replaces each '*' with the contents of that line.

                   If you had a bunch of gif files, you might say:
                   INPUT_CONVERT giftopnm *

                   If you have a bunch of separate a.Y, a.U, and a.V files (where
                   the U and V have already been subsampled), then you might say:

                   INPUT_CONVERT cat *.Y *.U *.V

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

                   INPUT_CONVERT *

              as described above.

       SIZE widthxheight

              width and height are the width and height of each frame in pixels.

              When  ppmtompeg can get this information from the input image files, it ignores the
              SIZE parameter and you may omit it.

              When the image  files  are  in  YUV  format,  the  files  don't  contain  dimension
              information, so SIZE is required.

              When ppmtompeg is running in parallel mode, not all of the processes in the network
              have access to the image files,  so  SIZE  is  required  and  must  give  the  same
              dimensions as the input image files.

       YUV_SIZE widthxheight
              This is an obsolete synonym of SIZE.

       YUV_FORMAT {ABEKAS | PHILLIPS | UCB |
                                    EYUV | pattern} This is meaningful only when BASE_FILE_FORMAT
              specifies YUV format, and then it is required.  It specifies the sub-format of  the
              YUV class.

       GOP_SIZE n
              n  is  the number of frames in a Group of Pictures.  Except that because a GOP must
              start with an I frame, ppmtompeg makes a GOP as much longer than n as it has to  to
              make the next GOP start with an I frame.

              Normally,  it  makes  sense to make your GOP size a multiple of your pattern length
              (the latter is determined by the PATTERN parameter file statement).

              See Group Of Pictures ⟨#gop⟩ .

       SLICES_PER_FRAME n
              n is roughly the number of slices per frame.  Note, at least one  MPEG  player  may
              complain  if slices do not start at the left side of an image.  To ensure this does
              not happen, make sure the number of rows is divisible by SLICES_PER_FRAME.

       PIXEL {FULL | HALF}
              use half-pixel motion vectors, or just full-pixel ones It is usually important that
              you  use  half-pixel  motion vectors, because it results in both better quality and
              better compression.

       RANGE n
              Use a search range of n pixels in each of the four directions from a subject pixel.
              (So the search window is a square n*2 pixels on a side).

       PSEARCH_ALG {EXHAUSTIVE | TWOLEVEL |
                   SUBSAMPLE | LOGARITHMIC} This statement tells ppmtompeg what kind of search
                  technique (algorithm) to use for P frames.  You select the desired
                  combination of speed and compression.  EXHAUSTIVE gives the
                  best compression, but LOGARITHMIC is the fastest.
                  TWOLEVEL is an exhaustive full-pixel search, followed by a
                  local half- pixel search around the best full-pixel vector (the
                  PIXEL option is ignored for this search technique).

       BSEARCH_ALG {SIMPLE | CROSS2 | EXHAUSTIVE}
              This statement tells ppmtompeg what kind of search
                  technique (algorithm) to use for B frames.  SIMPLE means
                  find best forward and backward vectors, then interpolate.
                  CROSS2 means find those two vectors, then see what backward
                  vector best matches the best forward vector, and vice versa.
                  EXHAUSTIVE does an n-squared search and is
                  extremely slow in relation to the others (CROSS2
                  is about half as fast as SIMPLE).

       IQSCALE n
              Use n as the qscale for I frames.
                   See Qscale ⟨#qscale⟩ .

       PQSCALE n
              Use n as the qscale for P frames.
                   See Qscale ⟨#qscale⟩ .

       BQSCALE n
              Use n as the qscale for B frames.
                   See Qscale ⟨#qscale⟩ .

       REFERENCE_FRAME {ORIGINAL | DECODED}
              This statement determines whether ppmtompeg uses the original images or the decoded
              images when computing motion vectors.  Using decoded images is  more  accurate  and
              should  increase the playback quality of the output, but it makes the encoding take
              longer and seems to give worse compression.  It also causes some complications with
              parallel encoding. (see the section on parallel encoding).  One thing you can do as
              a trade-off is select ORIGINAL here, and  lower  the  qscale  (see  QSCALE  if  the
              quality is not good enough.

              Original or Decoded? (Normalized)

              ────────────────────────────────────────────────────────────────────
              Reference   Compression   Speed   Quality I   Quality P   Quality B
                Decoded      1000       1000      1000         969         919
               Original       885       1373      1000         912         884

       The following lines are optional:

       FORCE_ENCODE_LAST_FRAME
              This statement is obsolete.  It does nothing.

              Before  Netpbm  10.26  (January  2005), ppmtompeg would drop trailing B frames from
              your movie, since a movie can't end with a B frame.  (See I  Frames,  P  Frames,  B
              Frames  ⟨#ipb⟩  .)   You would have to specify FORCE_ENCODE_LAST_FRAME to stop that
              from happening and get the same function that ppmtompeg has today.

       NIQTABLE
              This statement specifies a custom  non-intra  quantization  table.   If  you  don't
              specify this statement, ppmtompeg uses a default non-intra quantization table.

              The  8  lines  immediately following NIQTABLE specify the quantization table.  Each
              line defines a table row and consists of 8  integers,  whitespace-delimited,  which
              define the table columns.

       IQTABLE
              This is analogous to NIQTABLE, but for the intra quantization table.

       ASPECT_RATIO ratio
              This  statement  specifies  the  aspect  ratio for ppmtompeg to specify in the MPEG
              output.  I'm not sure what this is used for.

              ratio must be 1.0, 0.6735, 0.7031, 0.7615, 0.8055, 0.8437, 0.8935, 0.9157,  0.9815,
              1.0255, 1.0695, 1.0950, 1.1575, or 1.2015.

       FRAME_RATE rate
              This  specifies  the  frame rate for ppmtompeg to specify in the MPEG output.  Some
              players use this value to determine the playback rate.

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

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

              rate must be an integer.

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

              A  Video  Verifying Buffer is a buffer in which a decoder keeps the decoded bits in
              order to match the uneven speed of the decoding with the required constant playback
              speed.

              As  ppmtompeg  encodes the image, it simulates the decoding process in terms of how
              many bits would be in the VBV as each frame gets decoded, assuming  a  VBV  of  the
              size you indicate.

              If  you  specify  the WARN_VBV_UNDERFLOW statement, ppmtompeg issues a warning each
              time the simulation underflows the buffer, which suggests that an  underflow  would
              occur on playback, which suggests the buffer is too small.

              If  you  specify  the  WARN_VBV_OVERFLOW statement, ppmtompeg issues a warning each
              time the simulation overflows the buffer, which suggests  that  an  overflow  would
              occur on playback, which suggests the buffer is too small.

       WARN_VBV_UNDERFLOW

       WARN_VBV_OVERFLOW
              See BUFFER_SIZE.

              These  options  were  new  in  Netpbm 10.26 (January 2005).  Before that, ppmtompeg
              issued the warnings always.

              The following statements apply only to parallel operation:

       PARALLEL
              This statement, paired with END PARALLEL, is what causes ppmtompeg  to  operate  in
              parallel mode.  See Parallel Operation ⟨#parallel⟩ .

       END PARALLEL
              This goes with PARALLEL.

       PARALLEL_TEST_FRAMES n
              The master starts off by measuring each slave's speed.  It does this by giving each
              slave n frames to encode and noting how long the slave takes to finish.  These  are
              not  just test frames, though -- they're real frames and the results become part of
              the output.  ppmtompeg is old and measures time in undivided  seconds,  so  to  get
              useful  timings,  specify  enough  frames  that  it will take at least 5 seconds to
              process them.  The default is 10.

              If you specify FORCE_I_ALIGN, ppmtompeg will increase the test frames value  enough
              to maintain the alignment.

              If  there aren't enough frames for every slave to have the indicated number of test
              frames, ppmtompeg will give some slaves fewer.

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

              Smaller values of t  increase  communication,  but  improve  load  balancing.   The
              default is 30 seconds.

              You  may  specify  only  one  of  PARALLEL_TIME_CHUNKS,  PARALLEL_CHUNK_TAPER,  and
              PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.

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

              You  may  specify  only  one  of  PARALLEL_TIME_CHUNKS,  PARALLEL_CHUNK_TAPER,  and
              PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.

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

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

              You  may  specify  only  one  of  PARALLEL_TIME_CHUNKS,  PARALLEL_CHUNK_TAPER,  and
              PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is usually best.

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

              Be sure to set up .rhosts files or SSH key authorizations where needed.  Otherwise,
              you'll have to type in passwords.

              On some HP machines, rsh is the restricted shell, and you want to specify remsh.

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

              This document used to say there was an argument  to  FORCE_I_ALIGN  which  was  the
              number  of  frames  ppmtompeg  would  use (and was required to be a multiple of the
              pattern length).  But ppmtompeg has apparently always ignored that argument, and it
              does now.

       KEEP_TEMP_FILES
              This  statement  causes  ppmtompeg  not  to  delete  the temporary files it uses to
              transmit encoded frames to the combine server.  This means you will be left with  a
              file for each frame, the same as you would get with the -frames option.

              This is mostly useful for debugging.

              This  works  only  if  you're  using a shared filesystem to communicate between the
              servers.

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

   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 normal 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 addition,  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 ppmtompeg 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 quality  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
                     ⟨#smallbetter⟩        ⟨#largefaster⟩        ⟨#largebetter⟩
        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
                    ⟨#smallbetter⟩        ⟨#largefaster⟩        ⟨#largebetter⟩
       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 -combine_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 ("predictive"  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 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  pattern  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 following 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  complete  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 ppmtompeg 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 parallelism.

       In  general, you should use full path file names when describing executables and parameter
       files.  This includes the parameter file argument 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 number  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 command 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  partners  the  port  number.   These  port
       numbers are at least 2048.

       Use  the  PARALLEL_TEST_FRAMES,  PARALLEL_TIME_CHUNKS, and PARALLEL_PERFECT 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) operation:

       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  conventional  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, keving@cs.berkeley.edu

       •      Ketan Patel - University of California, Berkeley, kpatel@cs.berkeley.edu

       •      Dan Wallach - University of California, Berkeley, dwallach@cs.berkeley.edu

       •      Darryl Brown - University of California, Berkeley, darryl@cs.berkeley.edu

       •      Eugene Hung - University of California, Berkeley, eyhung@cs.berkeley.edu

       •      Steve Smoot - University of California, Berkeley, smoot@cs.berkeley.edu

DOCUMENT SOURCE

       This  manual page was generated by the Netpbm tool 'makeman' from HTML source.  The master
       documentation is at

              http://netpbm.sourceforge.net/doc/ppmtompeg.html