Ppmtompeg User Manual(0)               Ppmtompeg User Manual(0)



Table Of Contents


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.  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 some-
       thing  about  the  complex MPEG-1 format.  One source of
       information about this standard format  is  Introduction
       to MPEG (1).


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



       -stat stat_file
              This option causes ppmtompeg to append  the  sta-
              tistics  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 compres-
              sion 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.



       -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 informa-
              tion.


       -combine_gops
               causes ppmtompeg  simply  to  combine  some  GOP
              files  into a single MPEG output stream.  ppmtom-
              peg inserts a sequence header  and  trailer.   In
              this  case, the parameter file needs only to con-
              tain 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 suf-
              fix .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, inclu-
              sive.  The parameter file is the same as for nor-
              mal 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 paral-
              lel encoding.


       -snr   This  option causes ppmtompeg to include the sig-
              nal-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  his-
              togram  of  the motion vectors as part of statis-
              tics.  There are three histograms --  one  for  P
              frame, one for forward B frame, and one for back-
              ward 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 .


       -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 .




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

              See I Frames, P Frames, B Frames .


       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  sepa-
              rate  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,   ten-
              nis14.ppm, tennis15.ppm.

              Uniform  zero-padding occurs, as well.  For exam-
              ple, 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 foot-
              ball.*.ppm [001-130+4] refers to the files  foot-
              ball.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 compatibil-
              ity.  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  speci-
              fies 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 state-
              ment).

              See Group Of Pictures .


       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 tech-
              nique).


       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 .


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


       BQSCALE n
              Use n as the qscale for B frames.
                   See 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 .  You would have to
              specify FORCE_ENCODE_LAST_FRAME to stop that from
              happening  and get the same function that ppmtom-
              peg has today.



       NIQTABLE
              This statement specifies a custom non-intra quan-
              tization table.  If you don't specify this state-
              ment, ppmtompeg uses a default non-intra  quanti-
              zation table.

              The  8 lines immediately following NIQTABLE spec-
              ify 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  Veri-
              fier  (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, assum-
              ing a VBV of the size you indicate.

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

              If you specify the  WARN_VBV_OVERFLOW  statement,
              ppmtompeg  issues a warning each time the simula-
              tion 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 warn-
              ings 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 .


       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, ppmtom-
              peg 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 sec-
              onds.

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


       PARALLEL_CHUNK_TAPER
              When you specify this statement, the master  dis-
              tributes  work  like  with  PARALLEL_TIME_CHUNKS,
              except that the master chooses the number of sec-
              onds for the chunks.  It starts with a large num-
              ber 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.  PAR-
              ALLEL_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 effi-
              cient 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.  PAR-
              ALLEL_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 com-
              mand  ppmtompeg  uses  is  one  like  this:   ssh
              remote.host.com -l username shellcommand.

              Be sure to set up .rhosts files or SSH key autho-
              rizations 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 pat-
              tern 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 filesys-
              tem 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 val-
       ues 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 num-
       bers 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 tech-
       niques available.  There are different techniques avail-
       able  for  P frame search and B frame search. Using dif-
       ferent 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 Loga-
       rithmic  for P frame search, and Cross2 and Simple for B
       frame search. Here are some numbers comparing  the  dif-
       ferent search methods:

       P frame Motion Vector Search (Normalized)
       --------------------------------------------------
         Technique   Compression 1   Speed 2   Quality 3
        Exhaustive       1000         1000       1000
         SubSample       1008         2456       1000
          TwoLevel       1009         3237       1000
       Logarithmic       1085         8229        998

       B frame Motion Vector Search (Normalized)
       -------------------------------------------------
        Technique   Compression 1   Speed 2   Quality 3
       Exhaustive       1000         1000       1000
           Cross2        975         1000        996
           Simple        938         1765        991

       1Smaller numbers are better compression.

       2Larger numbers mean faster execution.

       3Larger numbers mean better quality.

       For  some  reason,  Simple seems to give better compres-
       sion, 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 prob-
       lem, we usually just use one slice per frame.


       Control the slice size with the SLICES_PER_FRAME parame-
       ter file statement.

       Some  MPEG playback systems require that each slice con-
       sist 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  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  B  frames
       for the last movie frames, 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 connec-
       tions.   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 pro-
       cesses 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  out-
       puts 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
       o      Kevin  Gong - University of California, Berkeley,
              keving@cs.berkeley.edu


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


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


       o      Darryl Brown - University of  California,  Berke-
              ley, darryl@cs.berkeley.edu


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


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



netpbm documentation      14 July 2001 Ppmtompeg User Manual(0)
