1Ppmtompeg User Manual(0)                              Ppmtompeg User Manual(0)
2
3
4

NAME

6       ppmtompeg - encode an MPEG-1 bitstream
7
8

SYNOPSIS

10       ppmtompeg [options] parameter-file
11
12

DESCRIPTION

14       This program is part of Netpbm(1).
15
16       ppmtompeg  produces  an MPEG-1 video stream.  MPEG-1 is the first great
17       video compression method, and is what is used in Video CDs (VCD).  ppm‐
18       tompeg  originated  in the year 1995.  DVD uses a more advanced method,
19       MPEG-2.  There is an even newer method  called  MPEG-4  which  is  also
20       called Divx.  I don't know where one finds that used.
21
22       There's technically a difference between a compression method for video
23       and an actual file (stream) format for a movie, and I don't know if  it
24       can be validly said that the format of the stream ppmtompeg produces is
25       MPEG-1.
26
27       Mencoder from the Mplayer package ⟨http://www.mplayerhq.hu⟩  is  proba‐
28       bly  superior  for  most video format generation needs, if for no other
29       reason than that it is more popular.
30
31       The programming library PM2V http://pm2v.free.fr⟩    generates  MPEG-2
32       streams.
33
34       Use  Mplayer  ⟨http://www.mplayerhq.hu⟩  (not part of Netpbm) to do the
35       reverse conversion: to create a  series  of  PNM  files  from  an  MPEG
36       stream.
37
38       param_file is a parameter file which includes a list of input files and
39       other parameters.  The file is described in detail below.
40
41       To understand this program, you need to understand something about  the
42       complex  MPEG-1  format.  One source of information about this standard
43       format is the section Introduction  to  MPEG  in  the  Compression  FAQ
44http://www.faqs.org/faqs/compression-faq/⟩ .
45
46

OPTIONS

48       The  -gop,  -combine_gops, -frames, and -combine_frames options are all
49       mutually exclusive.
50
51
52
53       -stat stat_file
54              This option causes ppmtompeg to append the  statistics  that  it
55              write  to  Standard  Output  to the file stat_file as well.  The
56              statistics use  the  following  abbreviations:  bits  per  block
57              (bpb),  bits  per frame (bpf), seconds per frame (spf), and bits
58              per second (bps).
59
60              These statistics include how many I, P, and B frames there were,
61              and information about compression and quality.
62
63
64
65       -quiet num_seconds
66               causes  ppmtompeg  not to report remaining time more often than
67              every num_seconds seconds (unless the time estimate rises, which
68              will  happen  near  the beginning of the run).  A negative value
69              tells ppmtompeg not to report at all.  0 is the default (reports
70              once  after each frame).  Note that the time remaining is an es‐
71              timate and does not take into account time to read in frames.
72
73
74       -realquiet
75               causes ppmtompeg to run silently, with the only  screen  output
76              being  errors.   Particularly  useful  when  reading  input from
77              stdin.  The equivalent of the -quiet common option of most other
78              Netpbm programs.
79
80
81
82       -no_frame_summary
83               This option prevents ppmtompeg from printing a summary line for
84              each frame
85
86
87       -float_dct
88               forces ppmtompeg to use a more accurate, yet more  computation‐
89              ally expensive version of the DCT.
90
91
92       -gop gop_num
93              causes  ppmtompeg  to encode only the numbered GOP (first GOP is
94              0).  The parameter file is the same as for  normal  usage.   The
95              output  file  will  be  the  normal  output file with the suffix
96              .gop.gop_num.  ppmtompeg does not output any  sequence  informa‐
97              tion.
98
99
100       -combine_gops
101               causes ppmtompeg simply to combine some GOP files into a single
102              MPEG output stream.  ppmtompeg inserts  a  sequence  header  and
103              trailer.  In this case, the parameter file needs only to contain
104              the SIZE value, an output file, and perhaps a list of input  GOP
105              files (see below).
106
107              If you don't supply a list of input GOP files is used, then ppm‐
108              tompeg assumes you're using the same  parameter  file  you  used
109              when you created the input (with the -gop option) and calculates
110              the corresponding gop filenames itself.   If  this  is  not  the
111              case, you can specify input GOP files in the same manner as nor‐
112              mal input files -- except instead of using INPUT_DIR, INPUT, and
113              END_INPUT,  use GOP_INPUT_DIR, GOP_INPUT, and GOP_END_INPUT.  If
114              no input GOP files are specified, then the default is to use the
115              output file name with suffix .gop.gop_num, with gop_num starting
116              from 0, as the input files.
117
118              Thus, unless you're mixing and matching GOP files from different
119              sources, you can simply use the same parameter file for creating
120              the GOP files (-gop) and for later turning  them  into  an  MPEG
121              stream (-combine_gops).
122
123
124
125       -frames first_frame last_frame
126              This  option causes ppmtompeg to encode only the frames numbered
127              first_frame to last_frame, inclusive.  The parameter file is the
128              same as for normal usage.  The output will be placed in separate
129              files, one per frame, with the file names being the normal  out‐
130              put  file  name with the suffix .frame.frame_num.  No GOP header
131              information is output.  (Thus, the parameter file need  not  in‐
132              clude the GOP_SIZE value)
133
134              Use ppmtompeg -combine_frames to combine these frames later into
135              an MPEG stream.
136
137
138
139       -combine_frames
140               This option causes ppmtompeg simply to combine some  individual
141              MPEG  frames (such as you might have created with an earlier run
142              of ppmtompeg -frames) into a single MPEG stream.   Sequence  and
143              GOP  headers  are inserted appropriately.  In this case, the pa‐
144              rameter file needs to contain only the SIZE value, the  GOP_SIZE
145              value,  an  output  file, and perhaps a list of frame files (see
146              below).
147
148              The parameter file may specify input frame  files  in  the  same
149              manner  as  normal  input  files  -- except instead of using IN‐
150              PUT_DIR, INPUT, and END_INPUT, use FRAME_INPUT_DIR, FRAME_INPUT,
151              and FRAME_END_INPUT. If no input frame files are specified, then
152              the  default  is  to  use  the  output  file  name  with  suffix
153              .frame.frame_num,  with  frame_num starting from 0, as the input
154              files.
155
156
157
158
159       -nice  This  option  causes  ppmtompeg  to  run  any  remote  processes
160              "nicely,"  i.e.  at low priority.  (This is relevant only if you
161              are running ppmtompeg in parallel mode.  Otherwise, there are no
162              remote processes).  See 'man nice.'
163
164
165       -max_machines num_machines
166              This  option  causes  ppmtompeg to use no more than num_machines
167              machines as slaves for use in parallel encoding.
168
169
170       -snr   This option causes ppmtompeg to include the signal-to-noise  ra‐
171              tio in the reported statistics.  Prints SNR (Y U V) and peak SNR
172              (Y U V) for each frame.  In summary, prints  averages  of  lumi‐
173              nance  only  (Y).   SNR  is defined as 10*log(variance of origi‐
174              nal/variance   of   error).    Peak   SNR    is    defined    as
175              20*log(255/RMSE).  Note that ppmtompeg runs a little slower when
176              you use this option.
177
178
179       -mse   This option causes ppmtompeg to report the  mean  squared  error
180              per block.  It also automatically reports the quality of the im‐
181              ages, so there is no need to specify -snr then.
182
183
184       -bit_rate_info rate_file
185               This option makes ppmtompeg write bit rate information into the
186              file  rate_file.   Bit  rate  information is bits per frame, and
187              also bits per I-frame-to-I-frame.
188
189
190       -mv_histogram
191               This option causes ppmtompeg to print a histogram of the motion
192              vectors  as  part  of statistics.  There are three histograms --
193              one for P frame, one for forward B frame, and one for backward B
194              frame motion vectors.
195
196              The  output is in the form of a matrix, each entry corresponding
197              to one motion vector in the search window. The center of the ma‐
198              trix represents (0,0) motion vectors.
199
200
201       -debug_sockets
202              This  option  causes  ppmtompeg to print to Standard Output mes‐
203              sages that narrate the communication between the  machines  when
204              you run ppmtompeg in parallel mode ⟨#parallel⟩ .
205
206
207       -debug_machines
208              This  option  causes  ppmtompeg to print to Standard Output mes‐
209              sages that narrate the progress of the conversion on the various
210              machines when you run ppmtompeg in parallel mode ⟨#parallel⟩ .
211
212
213
214

PARAMETER FILE

216       The  parameter file must contain the following lines (except when using
217       the -combine_gops or -combine_frames options):
218
219
220
221
222       PATTERN pattern
223              This statement specifies the pattern (sequence) of I  frames,  P
224              frames, and B frames.  pattern is just a sequence of the letters
225              I, P, and B with nothing between.  Example:
226
227                  PATTERN IBBPBBPBBPBBPBB
228              </pre>
229
230              See
231              I Frames, P Frames, B Frames
232              ⟨#ipb⟩
233              .
234
235
236       OUTPUT output file
237              This names the file where the output MPEG stream goes.
238
239
240       INPUT_DIR directory
241              This statement tells where the input images (frames) come from.
242              If each frame is in a separate file, directory is the directory
243              where they all are.  You may use . to refer to the current
244              directory.  A null directory refers to the root directory of the
245              system file tree.
246
247              To have ppmtompeg read all the frames serially from Standard
248              Input, specify
249                  INPUT_DIR stdin
250
251
252
253       INPUT  This line must be followed by a list of the input files (in dis‐
254              play order) and then the line END_INPUT.
255
256              There  are  three  types  of  lines between INPUT and END_INPUT.
257              First, a line may simply be the name of an input file.   Second,
258              the  line  may  be  of  the  form  single_star_expr [x-y].  sin‐
259              gle_star_expr can have a single * in it.  It is replaced by  all
260              the  numbers  between  x  and y inclusive.  So, for example, the
261              line tennis*.ppm [12-15] refers to the files tennis12.ppm,  ten‐
262              nis13.ppm, tennis14.ppm, tennis15.ppm.
263
264              Uniform  zero-padding  occurs,  as  well.  For example, the line
265              football.*.ppm [001-130] refers to the  files  football.001.ppm,
266              football.002.ppm,  ..., football.009.ppm, football.010.ppm, ...,
267              football.130.ppm.
268
269              The third type of line is: single_star_expr [x-y+s],  where  the
270              line  is  treated  exactly  as  above, except that we skip by s.
271              Thus, the line football.*.ppm [001-130+4] refers  to  the  files
272              football.001.ppm,   football.005.ppm,   football.009.ppm,  foot‐
273              ball.013.ppm, etc.
274
275              Furthermore, a line may specify a shell command  to  execute  to
276              generate lines to be interpreted as described above, as if those
277              lines were in the parameter file instead.  Use back ticks,  like
278              in the Bourne Shell, like this:
279
280                  `cat myfilelist`
281
282
283              If  input  is from Standard Input (per the INPUT_DIR statement),
284              ppmtompeg ignores the INPUT/END_INPUT block, but it  still  must
285              be present.
286
287
288       BASE_FILE_FORMAT {PPM | PNM | YUV |
289                   JPEG  |  JMOVIE}  ppmtompeg must convert all input files to
290              one of the following formats as a first step of processing: PNM,
291              YUV,  JPEG(v4),  or  JMOVIE.   (The conversion may be trivial if
292              your input files are already in one  of  these  formats).   This
293              line  specifies  which  of  the four formats.  PPM is actually a
294              subset of PNM.  The separate specification is allowed for  back‐
295              ward compatibility.  Use PNM instead of PPM in new applications.
296
297
298       INPUT_CONVERT conversion_command
299              You  must specify how to convert a file to the base file format.
300              If no conversion is necessary, then you would just say:
301
302                   INPUT_CONVERT *
303
304
305              Otherwise, conversion_command is a shell command that causes  an
306              image  in  the format your specified with BASE_FILE_FORMAT to be
307              written to Standard Output.  ppmtompeg executes the command once
308              for  each  line  between INPUT and END_INPUT (which is normally,
309              but not necessarily, a file name).  In the  conversion  command,
310              ppmtompeg replaces each '*' with the contents of that line.
311
312                   If you had a bunch of gif files, you might say:
313                   INPUT_CONVERT giftopnm *
314
315
316                   If  you  have  a  bunch of separate a.Y, a.U, and a.V files
317              (where
318                   the U and V have already been subsampled), then  you  might
319              say:
320
321                   INPUT_CONVERT cat *.Y *.U *.V
322
323
324              Input conversion is not allowed with input from stdin, so use
325
326                   INPUT_CONVERT *
327
328
329              as described above.
330
331
332       SIZE widthxheight
333
334              width  and height are the width and height of each frame in pix‐
335              els.
336
337              When ppmtompeg can get this information  from  the  input  image
338              files, it ignores the SIZE parameter and you may omit it.
339
340              When  the image files are in YUV format, the files don't contain
341              dimension information, so SIZE is required.
342
343              When ppmtompeg is running in parallel mode, not all of the  pro‐
344              cesses in the network have access to the image files, so SIZE is
345              required and must give the same dimensions as  the  input  image
346              files.
347
348
349       YUV_SIZE widthxheight
350              This is an obsolete synonym of SIZE.
351
352
353       YUV_FORMAT {ABEKAS | PHILLIPS | UCB |
354                                    EYUV  |  pattern}  This is meaningful only
355              when BASE_FILE_FORMAT specifies YUV format, and then it  is  re‐
356              quired.  It specifies the sub-format of the YUV class.
357
358
359
360       GOP_SIZE n
361              n  is  the number of frames in a Group of Pictures.  Except that
362              because a GOP must start with an I frame, ppmtompeg makes a  GOP
363              as  much  longer  than n as it has to to make the next GOP start
364              with an I frame.
365
366              Normally, it makes sense to make your GOP  size  a  multiple  of
367              your pattern length (the latter is determined by the PATTERN pa‐
368              rameter file statement).
369
370              See Group Of Pictures ⟨#gop⟩ .
371
372
373       SLICES_PER_FRAME n
374              n is roughly the number of slices per frame.  Note, at least one
375              MPEG player may complain if slices do not start at the left side
376              of an image.  To ensure this does not happen, make sure the num‐
377              ber of rows is divisible by SLICES_PER_FRAME.
378
379
380       PIXEL {FULL | HALF}
381              use  half-pixel  motion  vectors,  or just full-pixel ones It is
382              usually important that you use half-pixel  motion  vectors,  be‐
383              cause it results in both better quality and better compression.
384
385
386
387       RANGE n
388              Use  a  search  range of n pixels in each of the four directions
389              from a subject pixel.  (So the search window  is  a  square  n*2
390              pixels on a side).
391
392
393       PSEARCH_ALG {EXHAUSTIVE | TWOLEVEL |
394                   SUBSAMPLE  |  LOGARITHMIC}  This  statement tells ppmtompeg
395              what kind of search
396                  technique (algorithm) to use for P frames.  You  select  the
397              desired
398                  combination of speed and compression.  EXHAUSTIVE gives the
399                  best compression, but LOGARITHMIC is the fastest.
400                  TWOLEVEL is an exhaustive full-pixel search, followed by a
401                  local  half-  pixel search around the best full-pixel vector
402              (the
403                  PIXEL option is ignored for this search technique).
404
405
406       BSEARCH_ALG {SIMPLE | CROSS2 | EXHAUSTIVE}
407              This statement tells ppmtompeg what kind of search
408                  technique (algorithm) to use for B frames.  SIMPLE means
409                  find best forward and backward vectors, then interpolate.
410                  CROSS2 means find those two vectors, then see what backward
411                  vector best matches the best forward vector, and vice versa.
412                  EXHAUSTIVE does an n-squared search and is
413                  extremely slow in relation to the others (CROSS2
414                  is about half as fast as SIMPLE).
415
416
417       IQSCALE n
418              Use n as the qscale for I frames.
419                   See Qscale ⟨#qscale⟩ .
420
421
422       PQSCALE n
423              Use n as the qscale for P frames.
424                   See Qscale ⟨#qscale⟩ .
425
426
427       BQSCALE n
428              Use n as the qscale for B frames.
429                   See Qscale ⟨#qscale⟩ .
430
431
432       REFERENCE_FRAME {ORIGINAL | DECODED}
433              This statement determines whether ppmtompeg  uses  the  original
434              images or the decoded images when computing motion vectors.  Us‐
435              ing decoded images is more  accurate  and  should  increase  the
436              playback  quality  of the output, but it makes the encoding take
437              longer and seems to give worse compression.  It also causes some
438              complications with parallel encoding. (see the section on paral‐
439              lel encoding).  One thing you can do as a  trade-off  is  select
440              ORIGINAL  here,  and lower the qscale (see QSCALE if the quality
441              is not good enough.
442
443              Original or Decoded? (Normalized)
444
445              ────────────────────────────────────────────────────────────────────
446              Reference   Compression   Speed   Quality I   Quality P   Quality B
447                Decoded      1000       1000      1000         969         919
448               Original       885       1373      1000         912         884
449
450
451
452
453
454
455       The following lines are optional:
456
457
458
459
460       FORCE_ENCODE_LAST_FRAME
461              This statement is obsolete.  It does nothing.
462
463              Before Netpbm 10.26 (January 2005), ppmtompeg would drop  trail‐
464              ing  B  frames from your movie, since a movie can't end with a B
465              frame.  (See I Frames, P Frames, B Frames ⟨#ipb⟩ .)   You  would
466              have  to  specify FORCE_ENCODE_LAST_FRAME to stop that from hap‐
467              pening and get the same function that ppmtompeg has today.
468
469
470
471       NIQTABLE
472              This statement specifies a custom non-intra quantization  table.
473              If  you  don't  specify this statement, ppmtompeg uses a default
474              non-intra quantization table.
475
476              The 8 lines immediately following NIQTABLE specify the quantiza‐
477              tion table.  Each line defines a table row and consists of 8 in‐
478              tegers, whitespace-delimited, which define the table columns.
479
480
481       IQTABLE
482              This is analogous to NIQTABLE, but for  the  intra  quantization
483              table.
484
485
486       ASPECT_RATIO ratio
487              This statement specifies the aspect ratio for ppmtompeg to spec‐
488              ify in the MPEG output.  I'm not sure what this is used for.
489
490              ratio must be  1.0,  0.6735,  0.7031,  0.7615,  0.8055,  0.8437,
491              0.8935,  0.9157,  0.9815,  1.0255,  1.0695,  1.0950,  1.1575, or
492              1.2015.
493
494
495       FRAME_RATE rate
496              This specifies the frame rate for ppmtompeg to  specify  in  the
497              MPEG output.  Some players use this value to determine the play‐
498              back rate.
499
500              rate must be 23.976, 24, 25, 29.97, 30, 50, 59.94, or 60.
501
502
503       BIT_RATE rate
504              This specifies the bit rate for Constant Bit Rate  (CBR)  encod‐
505              ing.
506
507              rate must be an integer.
508
509
510       BUFFER_SIZE size
511              This  specifies  the  value  ppmtompeg is to specify in the MPEG
512              output for the Video Buffering Verifier (VBV) buffer size needed
513              to decode the sequence.
514
515              A  Video  Verifying  Buffer is a buffer in which a decoder keeps
516              the decoded bits in order to match the uneven speed of  the  de‐
517              coding with the required constant playback speed.
518
519              As  ppmtompeg  encodes  the  image,  it  simulates  the decoding
520              process in terms of how many bits would be in the  VBV  as  each
521              frame gets decoded, assuming a VBV of the size you indicate.
522
523              If  you  specify the WARN_VBV_UNDERFLOW statement, ppmtompeg is‐
524              sues a warning each time the simulation underflows  the  buffer,
525              which  suggests that an underflow would occur on playback, which
526              suggests the buffer is too small.
527
528              If you specify the WARN_VBV_OVERFLOW statement, ppmtompeg issues
529              a  warning  each time the simulation overflows the buffer, which
530              suggests that an overflow would occur on  playback,  which  sug‐
531              gests the buffer is too small.
532
533
534       WARN_VBV_UNDERFLOW
535
536       WARN_VBV_OVERFLOW
537              See BUFFER_SIZE.
538
539              These  options  were new in Netpbm 10.26 (January 2005).  Before
540              that, ppmtompeg issued the warnings always.
541
542
543
544
545              The following statements apply only to parallel operation:
546
547
548
549
550       PARALLEL
551              This statement, paired with END PARALLEL, is what causes ppmtom‐
552              peg  to  operate  in  parallel  mode.   See  Parallel  Operation
553              ⟨#parallel⟩ .
554
555
556       END PARALLEL
557              This goes with PARALLEL.
558
559
560       PARALLEL_TEST_FRAMES n
561              The master starts off by measuring each slave's speed.  It  does
562              this by giving each slave n frames to encode and noting how long
563              the slave takes to finish.  These  are  not  just  test  frames,
564              though -- they're real frames and the results become part of the
565              output.  ppmtompeg is old and measures time  in  undivided  sec‐
566              onds,  so  to  get useful timings, specify enough frames that it
567              will take at least 5 seconds to process them.   The  default  is
568              10.
569
570              If  you  specify FORCE_I_ALIGN, ppmtompeg will increase the test
571              frames value enough to maintain the alignment.
572
573              If there aren't enough frames for every slave to have the  indi‐
574              cated  number  of  test  frames, ppmtompeg will give some slaves
575              fewer.
576
577
578
579       PARALLEL_TIME_CHUNKS t
580              When you specify this statement, the  master  attempts  to  feed
581              work to the slaves in chunks that take t seconds to process.  It
582              uses the speed measurement it made when it started up (see  PAR‐
583              ALLEL_TEST_FRAMES)  to  decide  how  many  frames  to put in the
584              chunk.  This statement obviously doesn't affect the first  batch
585              of work sent to each slave, which is the one used to measure the
586              slave's speed.
587
588              Smaller values of t increase  communication,  but  improve  load
589              balancing.  The default is 30 seconds.
590
591              You   may  specify  only  one  of  PARALLEL_TIME_CHUNKS,  PARAL‐
592              LEL_CHUNK_TAPER, and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER  is
593              usually best.
594
595
596       PARALLEL_CHUNK_TAPER
597              When  you  specify  this  statement, the master distributes work
598              like with PARALLEL_TIME_CHUNKS, except that the  master  chooses
599              the  number  of  seconds for the chunks.  It starts with a large
600              number and, as it gets closer to finishing the job, reduces  it.
601              That way, it reduces scheduling overhead when precise scheduling
602              isn't helpful, but still prevents a slave from  finishing  early
603              after  all  the  work  has  already been handed out to the other
604              slaves, and then sitting idle while there's still work to do.
605
606              You  may  specify  only  one  of  PARALLEL_TIME_CHUNKS,   PARAL‐
607              LEL_CHUNK_TAPER,  and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER is
608              usually best.
609
610
611
612       PARALLEL_PERFECT
613              If this statement is present, ppmtompeg schedules on the assump‐
614              tion that each machine is about the same speed.  The master will
615              simply divide up the frames evenly between the  slaves  --  each
616              slave gets the same number of frames.  If some slaves are faster
617              than others, they will finish first and remain  idle  while  the
618              slower slaves continue.
619
620              This  has  the  advantage of minimal scheduling overhead.  Where
621              slaves have different speeds, though, it makes  inefficient  use
622              of  the fast ones.  Where slaves are the same speed, it also has
623              the disadvantage that they all finish at the same time and  feed
624              their  output  to  the  single  Combine Server in a burst, which
625              makes less efficient use of the Combine Server and thus can  in‐
626              crease the total elapsed time.
627
628              You   may  specify  only  one  of  PARALLEL_TIME_CHUNKS,  PARAL‐
629              LEL_CHUNK_TAPER, and PARALLEL_PERFECT.  PARALLEL_CHUNK_TAPER  is
630              usually best.
631
632
633       RSH remote_shell_command
634              ppmtompeg  executes  the  shell  command remote_shell_command to
635              start a process on another machine.  The default command is rsh,
636              and whatever command you specify must have compatible semantics.
637              ssh is usually compatible.  The command ppmtompeg  uses  is  one
638              like this: ssh remote.host.com -l username shellcommand.
639
640              Be  sure to set up .rhosts files or SSH key authorizations where
641              needed.  Otherwise, you'll have to type in passwords.
642
643              On some HP machines, rsh is the restricted shell, and  you  want
644              to specify remsh.
645
646
647       FORCE_I_ALIGN
648              This  statement  forces  each  slave to encode a chunk of frames
649              which is a multiple of the pattern length (see PATTERN).   Since
650              the  first  frame in any pattern is an I frame, this forces each
651              chunk encoded by a slave to begin with an I frame.
652
653              This document used to say there was an argument to FORCE_I_ALIGN
654              which  was the number of frames ppmtompeg would use (and was re‐
655              quired to be a multiple of the pattern length).   But  ppmtompeg
656              has apparently always ignored that argument, and it does now.
657
658
659       KEEP_TEMP_FILES
660              This  statement  causes  ppmtompeg  not  to delete the temporary
661              files it uses to transmit encoded frames to the combine  server.
662              This means you will be left with a file for each frame, the same
663              as you would get with the -frames option.
664
665              This is mostly useful for debugging.
666
667              This works only if you're using a shared filesystem to  communi‐
668              cate between the servers.
669
670              This option was new in Netpbm 10.26 (January 2005).
671
672
673
674
675
676   Parameter File Notes
677        If you use the -combine_gops option, then you need to specify only the
678       SIZE and OUTPUT values in the parameter file.  In addition, the parame‐
679       ter file may specify input GOP files in the same manner as normal input
680       files -- except instead of using INPUT_DIR, INPUT, and  END_INPUT,  use
681       GOP_INPUT_DIR,  GOP_INPUT,  and GOP_END_INPUT.  If you specify no input
682       GOP files, then ppmtompeg uses by default the  output  file  name  with
683       suffix .gop.gop_num, with gop_num starting from 0, as the input files.
684
685       If  you  use  the -combine_frames option, then you need to specify only
686       the SIZE, GOP_SIZE, and OUTPUT values in the parameter file.  In  addi‐
687       tion, the parameter file may specify input frame files in the same man‐
688       ner as normal input files -- except instead of using INPUT_DIR,  INPUT,
689       and  END_INPUT,  use FRAME_INPUT_DIR, FRAME_INPUT, and FRAME_END_INPUT.
690       If no input frame files are specified, then the default is to  use  the
691       output  file name with suffix .frame.frame_num, with frame_num starting
692       from 0, as the input files.
693
694       Any number of spaces and tabs may come between each option  and  value.
695       Lines beginning with # are ignored.  Any other lines are ignored except
696       for those between INPUT and END_INPUT.  This allows you to use the same
697       parameter  file  for  normal  usage  and  for  -combine_gops  and -com‐
698       bine_frames.
699
700       The file format is case-sensitive so all keywords should  be  in  upper
701       case.
702
703       The  statements may appear in any order, except that the order within a
704       block statement (such as INPUT ... END INPUT) is significant.
705
706       ppmtompeg is prepared to handle up to 16  B  frames  between  reference
707       frames  when encoding with input from stdin.  (To build a modified ppm‐
708       tompeg with a higher limit, change the constant B_FRAME_RUN in  frame.c
709       and recompile).
710
711

GENERAL USAGE INFORMATION

713   Qscale
714       The quantization scale values (qscale) give a trade-off between quality
715       and compression.  Using different Qscale values has very little  effect
716       on  speed.   The  qscale  values  can be set separately for I, P, and B
717       frames.
718
719       You select the qscale values with the IQSCALE, PQSCALE, and BSCALE  pa‐
720       rameter file statements.
721
722       A  qscale value is an integer from 1 to 31.  Larger numbers give better
723       compression, but worse quality.  In the following, the quality  numbers
724       are  peak  signal-to-noise  ratio,  defined as: signal-to-noise formula
725       where MSE is the mean squared error.
726
727
728       Flower garden tests:
729
730       Qscale vs Quality
731
732       ────────────────────────────────────────
733       Qscale   I Frames   P Frames   B Frames
734            1       43.2       46.3       46.5
735            6       32.6       34.6       34.3
736           11       28.6       29.5       30.0
737           16       26.3       26.8       28.6
738           21       24.7       25.0       27.9
739           26       23.5       23.9       27.5
740           31       22.6       23.0       27.3
741
742       Qscale vs Compression
743
744       ────────────────────────────────────────
745       Qscale   I Frames   P Frames   B Frames
746            1          2          2          2
747            6          7         10         15
748           11         11         18         43
749           16         15         29         97
750           21         19         41        173
751           26         24         56        256
752           31         28         73        330
753
754
755
756   Search Techniques
757       There are several different motion vector search techniques  available.
758       There are different techniques available for P frame search and B frame
759       search. Using different search techniques present little difference  in
760       quality, but a large difference in compression and speed.
761
762
763       There  are  4 types of P frame search: Exhaustive, TwoLevel, SubSample,
764       and Logarithmic.
765
766
767       There are 3 types of B frame search: Exhaustive, Cross2, and Simple.
768
769       The recommended search techniques are TwoLevel and  Logarithmic  for  P
770       frame  search,  and Cross2 and Simple for B frame search. Here are some
771       numbers comparing the different search methods:
772
773       P frame Motion Vector Search (Normalized)
774
775       ─────────────────────────────────────────────────────────────────────
776         Technique   Compression    1   Speed          2   Quality        3
777                     ⟨#smallbetter⟩     ⟨#largefaster⟩     ⟨#largebetter⟩
778        Exhaustive         1000               1000               1000
779         SubSample         1008               2456               1000
780          TwoLevel         1009               3237               1000
781       Logarithmic         1085               8229               998
782
783       B frame Motion Vector Search (Normalized)
784
785       ────────────────────────────────────────────────────────────────────
786        Technique   Compression    1   Speed          2   Quality        3
787                    ⟨#smallbetter⟩     ⟨#largefaster⟩     ⟨#largebetter⟩
788       Exhaustive         1000               1000               1000
789           Cross2         975                1000               996
790           Simple         938                1765               991
791
792       1Smaller numbers are better compression.
793
794       2Larger numbers mean faster execution.
795
796       3Larger numbers mean better quality.
797
798       For some reason, Simple seems to give better compression,  but  it  de‐
799       pends on the image sequence.
800
801       Select  the  search techniques with the PSEARCH_ALG and BSEARCH_ALG pa‐
802       rameter file statements.
803
804
805
806   Group Of Pictures (GOP)
807       A Group of Pictures (GOP) is a roughly independently decodable sequence
808       of frames.  An MPEG video stream is made of one or more GOP's.  You may
809       specify how many frames should be in each GOP with the GOP_SIZE parame‐
810       ter file statement.  A GOP always starts with an I frame.
811
812       Instead  of  encoding  an entire sequence, you can encode a single GOP.
813       To do this, use the -gop command option.  You can later  join  the  re‐
814       sulting  GOP  files  at  any  time  by running ppmtompeg with the -com‐
815       bine_gops command option.
816
817
818
819   Slices
820       A slice is an independently decodable unit in a frame.  It  can  be  as
821       small as one macroblock, or it can be as big as the entire frame.  Bar‐
822       ring transmission error, adding  slices  does  not  change  quality  or
823       speed;  the only effect is slightly worse compression.  More slices are
824       used for noisy transmission so that errors are more recoverable.  Since
825       usually  errors  are  not such a problem, we usually just use one slice
826       per frame.
827
828
829       Control the slice size with the SLICES_PER_FRAME parameter file  state‐
830       ment.
831
832       Some  MPEG  playback  systems  require that each slice consist of whole
833       rows of macroblocks.  If you are encoding for this kind of  player,  if
834       the  height  of  the  image  is  H  pixels,  then  you  should  set the
835       SLICES_PER_FRAME to some number which divides H/16.   For  example,  if
836       the image is 240 pixels (15 macroblocks) high, then you should use only
837       15, 5, 3, or 1 slices per frame.
838
839
840       Note: these MPEG playback systems are  really  wrong,  since  the  MPEG
841       standard says this doesn't have to be so.
842
843
844
845
846   Search Window
847       The  search window is the window in which ppmtompeg searches for motion
848       vectors.  The window is a square.  You can  specify  the  size  of  the
849       square, and whether to allow half-pixel motion vectors or not, with the
850       RANGE and PIXEL parameter file statements.
851
852
853   I Frames, P Frames, B Frames
854       In MPEG-1, a movie is represented as a sequence of MPEG frames, each of
855       which  is  an I Frame, a P Frame, or a B Frame.  Each represents an ac‐
856       tual frame of the movie (don't get confused by the dual use of the word
857       "frame."   A  movie frame is a graphical image.  An MPEG frame is a set
858       of data that describes a movie frame).
859
860       An I frame ("intra" frame) describes a  movie  frame  in  isolation  --
861       without  respect  to any other frame in the movie.  A P frame ("predic‐
862       tive" frame) describes a movie frame by describing how it differs  from
863       the  movie  frame described by the latest preceding I  or P frame.  A B
864       frame ("bidirectional" frame) describes a movie frame by describing how
865       it  differs from the movie frames described by the nearest I or P frame
866       before and after it.
867
868       Note that the first frame of a movie must be described by  an  I  frame
869       (because  there  is  no  previous movie frame) and the last movie frame
870       must be described by an I or P frame (because there  is  no  subsequent
871       movie frame).
872
873       Beyond  that,  you  can  choose  which  frames are represented by which
874       types.  You specify a pattern, such as IBPBP and ppmtompeg  simply  re‐
875       peats  it  over  and  over  throughout  the movie.  The pattern affects
876       speed, quality, and stream size.  Here is a chart which shows  some  of
877       the trade-offs:
878
879       Comparison of I/P/B Frames (Normalized)
880
881       ────────────────────────────────────
882       Frame Type   Size   Speed   Quality
883         I frames   1000   1000     1000
884         P frames   409     609      969
885         B frames    72     260      919
886
887       (this is with constant qscale)
888
889
890       A standard sequence is IBBPBBPBBPBBPBB.
891
892
893       Select the sequence with the PATTERN parameter file statement.
894
895       Since  the last MPEG frame cannot be a B frame (see above), if the pat‐
896       tern you specify indicates a B frame for the last movie  frame  of  the
897       movie, ppmtompeg makes it an I frame instead.
898
899       Before  Netpbm 10.26 (January 2005), ppmtompeg instead drops the trail‐
900       ing B frames by default, and you need the  FORCE_ENCODE_LAST_FRAME  pa‐
901       rameter file statement to make it do this.
902
903       The  MPEG  frames  don't  appear in the MPEG-1 stream in the same order
904       that the corresponding movie frames appear in the movie -- the B frames
905       come after the I and P frames on which they are based.  For example, if
906       the movie is 4 frames that you will represent with  the  pattern  IBBP,
907       the  MPEG-1 stream will start with an I frame describing movie frame 0.
908       The next frame in the MPEG-1 stream is a P frame describing movie frame
909       3.   The  last  two frames in the MPEG-1 stream are B frames describing
910       movie frames 1 and 2, respectively.
911
912
913
914   Specifying Input and Output Files
915       Specify the input frame images with the  INPUT_DIR,  INPUT,  END_INPUT,
916       BASE_FILE_FORMAT,  SIZE,  YUV_FORMAT  and  INPUT_CONVERT parameter file
917       statements.
918
919       Specify the output file with the OUTPUT parameter file statement.
920
921
922
923   Statistics
924       ppmtompeg can generate a variety of statistics about the encoding.  See
925       the   -stat,   -snr,   -mv_histogram,  -quiet,  -no_frame_summary,  and
926       -bit_rate_info options.
927
928
929

PARALLEL OPERATION

931       You can run ppmtompeg on multiple machines at once, encoding  the  same
932       MPEG  stream.   When you do, the machines are used as shown in the fol‐
933       lowing diagram.  We call this "parallel mode."
934
935       ppmtompeg-par.gif
936
937       To do parallel processing, put the statement
938
939           PARALLEL
940
941
942       in the parameter file, followed by a listing of the machines,  one  ma‐
943       chine per line, then
944
945           END_PARALLEL
946
947
948       Each  of the machine lines must be in one of two forms.  If the machine
949       has filesystem access to the input files, then the line is:
950
951       machine user executable
952
953       The executable is normally ppmtompeg (you may need to give the complete
954       path if you've built for different architectures).  If the machine does
955       not have filesystem access to the input files, the line is:
956
957       REMOTE machine user executable parameter file
958
959       The -max_machines command option limits the number of machines  ppmtom‐
960       peg  will use.  If you specify more machines in the parameter file than
961       -max_machines allows, ppmtompeg uses only the  machines  listed  first.
962       This  is handy if you want to experiment with different amounts of par‐
963       allelism.
964
965       In general, you should use full path file names  when  describing  exe‐
966       cutables  and  parameter files.  This includes the parameter file argu‐
967       ment on the original invocation of ppmtompeg.
968
969       All file names must be the same on all systems (so if e.g. you're using
970       an  NFS filesystem, you must make sure it is mounted at the same mount‐
971       point on all systems).
972
973       Because not all of the processes involved in  parallel  operation  have
974       easy  access  to  the  input files, you must specify the SIZE parameter
975       file statement when you do parallel operation.
976
977       The machine on which you originally invoke ppmtompeg is the master  ma‐
978       chine.   It  hosts a "combine server,", a "decode server," and a number
979       of "i/o servers," all as separate processes.  The other machines in the
980       network  (listed in the parameter file) are slave machines.  Each hosts
981       a single process that continuously requests work from  the  master  and
982       does it.  The slave process does the computation to encode MPEG frames.
983       It processes frames in batches identified by the master.
984
985       The master uses a remote shell command to start a process  on  a  slave
986       machine.  By default, it uses an rsh shell command to do this.  But use
987       the RSH parameter file statement to control this.   The  shell  command
988       the master executes remotely is ppmtompeg, but with options to indicate
989       that it is to perform slave functions.
990
991       The various machines talk to each other over TCP connections.  Each ma‐
992       chine  finds and binds to a free TCP port number and tells its partners
993       the port number.  These port numbers are at least 2048.
994
995       Use the PARALLEL_TEST_FRAMES, PARALLEL_TIME_CHUNKS,  and  PARALLEL_PER‐
996       FECT parameter file statements to control the way the master divides up
997       work among the slaves.
998
999       Use the -nice command option  to  cause  all  slave  processes  to  run
1000       "nicely,"  i.e.  as low priority processes.  That way, this substantial
1001       and long-running CPU load will have minimal impact on  other,  possibly
1002       interactive, users of the systems.
1003
1004

SPEED

1006       Here is a look at ppmtompeg speed, in single-node (not parallel) opera‐
1007       tion:
1008
1009       Compression Speed
1010
1011       ───────────────────────────────────────
1012       Machine Type   Macroblocks per second1
1013        HP 9000/755             280
1014       DEC 3000/400             247
1015        HP 9000/750             191
1016           Sparc 10             104
1017           DEC 5000             68
1018       1A macroblock is a 16x16 pixel square
1019
1020       The measurements in the table are with inputs and outputs via a conven‐
1021       tional  locally  attached  filesystem.   If  you  are  using  a network
1022       filesystem over a single 10 MB/s Ethernet, that constrains  your  speed
1023       more  than  your  CPU  speed.  In that case, don't expect to get better
1024       than 4 or 5 frames per second no matter how fast your CPUs are.
1025
1026       Network speed is even more of a bottleneck when the slaves do not  have
1027       filesystem access to the input files -- i.e. you declare them REMOTE.
1028
1029       Where  I/O  is  the bottleneck, size of the input frames can make a big
1030       difference.  So YUV input is better than PPM, and JPEG is  better  than
1031       both.
1032
1033       When  you're  first trying to get parallel mode working, be sure to use
1034       the -debug_machines option so you can see what's going on.  Also,  -de‐
1035       bug_sockets can help you diagnose communication problems.
1036
1037
1038

AUTHORS

1040       •      Kevin   Gong   -   University   of  California,  Berkeley,  kev‐
1041              ing@cs.berkeley.edu
1042
1043
1044       •      Ketan  Patel  -  University  of   California,   Berkeley,   kpa‐
1045              tel@cs.berkeley.edu
1046
1047
1048       •      Dan   Wallach   -  University  of  California,  Berkeley,  dwal‐
1049              lach@cs.berkeley.edu
1050
1051
1052       •      Darryl  Brown  -  University  of  California,   Berkeley,   dar‐
1053              ryl@cs.berkeley.edu
1054
1055
1056       •      Eugene   Hung   -   University   of  California,  Berkeley,  ey‐
1057              hung@cs.berkeley.edu
1058
1059
1060       •      Steve   Smoot   -   University    of    California,    Berkeley,
1061              smoot@cs.berkeley.edu
1062

DOCUMENT SOURCE

1064       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
1065       source.  The master documentation is at
1066
1067              http://netpbm.sourceforge.net/doc/ppmtompeg.html
1068
1069netpbm documentation             23 July 2006         Ppmtompeg User Manual(0)
Impressum