*******************************************************************************
*                           MPEGTool Version 1.03                             *
*                                     by                                      *
*                  Toshiyuki Urabe, Hassan Afzal,  Grace Ho                   *
*                       Pramod Pancha,  Magda El Zarki                        *
*                         University of Pennsylvania                          *
*******************************************************************************
                     <<< README file Table of Contents >>>
*******************************************************************************
*                         0) About MPEGTool                                   *
*                         1) System requirement                               *
*                         2) How to compile                                   *
*                         3) Encoder                                          *
*                         4) Statistics                                       *
*                         5) Data Structures                                  *
*                         6) Remarks                                          *
*******************************************************************************
0) About MPEGTool

MPEGTool is an application which combines an MPEG encoder and a
statistics tool with an X11/Motif based Graphical User Interface
(GUI). The encoder utilized in MPEGTool generates MPEG-1
compatible bitstreams for RGB and CCIR-601 format input video
sequences. The statistics tool can be used to analyze the
statistical properties of the encoding process graphically.
MPEGTool allows a user to specify several of the MPEG parameters
such as the intraframe to interframe ratio, and the quantizer
scale through its GUI.

1) System Requirement

Machine architecture

MPEGTool has been tested on Sun SparcStation, HP9000 and RS6000's
currently.  To compile under these machines, see instructions in
Makefile.

GUI

The MPEGTool GUI is based on the Motif toolkit from the Open
Software Foundation (OSF). Motif (Xm) libraries and include files
as well as X Toolkit (Xt) libraries are required to compile
MPEGTool.  Although MPEGTool can be executed under several window
managers, Motif window manager (mwm) is recommended. It has been
tested under mwm, Open look window manager (olwm) and Tab window
manager (twm). With the twm, it is recommended that the
'DecorateTransients'property is added to your .twmrc file.

Device support

MPEGTool supports disk and tape device for video data input and
MPEG code output. Also, MPEGTool creates a statistics data file
on disk. This statistics data is around 100K for 2 seconds of
video.  The encoded MPEG data is compressed to between requires
1/50 to 1/30 depending on the parameters utilized as well as the
input vidoe sequence.

Utility

MPEGTool statistics requires gnuplot ver 3.0 or higher to display
graphs and create PostScript files of graphs. The statistics tool
functions by creating data and command macros for gnuplot.
Gnuplot is not required for encoding video data.

2) How to compile

MPEGTool requires Motif (Xm) libraries as well as X Toolkit (Xt)
libraries and include files to be installed on your machine in
order to compile. The paths for these libraries and include files
can be set in the Makefile. MPEGTool has several compile options
that the user can select. To select these options, make
appropriate modifications in the Makefile after referring to the
instruction in it.

Followings are description of MPEGTool compile options, which can
be added to FLAG_OPT in Makefile.

  DISPLACE=<n> : Define searching area of MOTION VECTOR
                   (default=15)
  FAST_MV : Use fast MV search routine.

Since computing the motion vectors is the most time consuming
part of MPEG encoding, speeding up these routines through
appropriate shortcuts can help to increase the performance of the
software based MPEG encoder. These two options can be selected
for computing motion vectors. DISPLACE sets the block matching
search area for finding motion vectors.  FAST_MV option uses fast
motion vector computation routine which uses a binary search-like
method to find motion vectors.  Without FAST_MV, motion vectors
are determined after examining the entire search area
exhaustively. Since the MPEG draft does not specify how these
vectors are to be computed, you should choose appropriate methods
depending on your needs, picture quality required, encoding time,
computer performance, etc.

  NO_PROGRESS : hide progress report window during encode
  FREQUENT_UPDATE : progress report update in every slice

MPEGTool can display a progress report window while encoding.  By
this window, the status of MPEG encoding, which takes a
relatively long time, is updated in every frames.  With
FREQUENT_UPDATE option, the window will be updated in every
slices. If you don't need this window, you can choose NO_PROGRESS
option, which does not create progress report window.

  DISPSTAT : display frame statistics to console during encode
  DEBUG : debug mode. This displays progress resport and
             some other parameter information to console.

DISPSTAT displays frame based statistics to console after
encoding each group. This statistics contains number of generated
bits in each slice and encoding modes in each macroblock. Each
macroblock encoding mode is represented as the following
characters.

  '*' : Intra mode
  '-' : Forward Prediction mode without motion compensation
  '>' : Forward Prediction mode
  '<' : Backward Prediction mode
  '%' : Bi-Directional Prediction mode

DEBUG option displays progress report and some other parameter
information to console. If you have trouble with progress report
window, you may choose this option to show the progress of the
encoder.  Since these two options output information to console,
MPEGTool will not be a pure X-application with these options.

  BLOCK_LENGTH=<n>: Block length of input data on tape device
                    (default=1024)
  WRITE_LENGTH=<n>: Block length of encoded data on tape device
                    (default=4096)

These options set the block length of input/encoded data on the
tape device.  The length of the last block of encoded data is not
fixed but varies from 1 to WRITE_LENGTH. These parameters have
not effect for disk device.

3) Encoder

MPEGTool encoder encodes RGB/CCIR-601 format video input data
from tape or disk device by MPEG-1 specification and write the
encoded data into tape or disk. In addition, the statistics data
can be stored into disk device for MPEGTool statistics analysis.

We can set several encoding parameters from the MPEGTool Encoder
window.  For setting device related parameters, click the
Configure button and modify parameters of the MPEGTool Encoder
Configuration window. To start Encoding, click Start and MPEGTool
begins to encode if there is no parameter or device related
error.

The following are breif descriptions of the MPEGTool encoder
parameters.  These parameters are read from MPEGTool.cfg file as
a default value.  For details on the MPEGTool.cfg file, refer to
the comments of the sample MPEGTool.cfg file given in the
distribution.

MPEGTool Encoder parameters

  N : intra mode frame interval
  M : intra/prediction mode frame interval
  Quantization Scale : specified in MPEG coding standard
  DCT coefficients : layering parameter

N and M deal with the intraframe to interframe coding ratio and a
sequence of I, P and B frames is defined. N specifies the I frame
interval whereas M specifies the I or P frame interval. Some
examples of (N, M) combinations and the resultant frame coding
sequences are shown below.

  1. N = 1, M = 1 : I I I I I I I I I I I I I (I frames only)
  2. N = 4, M = 1 : I P P P I P P P I P P P I (I and P frames)
  3. N = 6, M = 2 : I B P B P B I B P B P B I (I, P and B frames)
  4. N = 6, M = 3 : I B B P B B I B B P B B I (I, P and B frames)
  5. N = 6, M = 6 : I B B B B B I B B B B B I (I and B frames)

Quantization Scale is a parameter which is specified in MPEG
coding standard.  DCT coefficients is the layering parameter for
the prioritized coder, which specifies the number of AC
coefficients to be placed in the HP and LP streams. The above
four parameters characterize MPEG coding scheme.

Start Frame and Number of Frame specify start frame of the video
data and the number of frames to encode consecutively. Data Name
is used to identify the video data source.  The file name for
video data, encoded data and statistics data are defined by using
the Data Name unless specified.

MPEGTool Encoder Configuration Parameters

Video Format selects the data format of video input data to
encode.  For the RGB data format, the width and height of picture
have to be specified with the number that are multiples of 16.

Input Device and Output Device select video data input device and
MPEG encoded data output device. When the tape device is
selected, the device name has to be specified. In the case of
disk device, the file name can be selected. Unless specified, the
name is selected by the following rule.

  Video data : <Data Name>.rgb or <Data Name>.CCIR
  Encoded Data : <Data Name>NnMmQqBb.mpg

  where n, m, q, b are the values of parameter N, M, Quantization
  Scale and number of DCT coefficients consecutively.

Record Statistics selects whether to create statistics file or
not, which are required for MPEGTool statistics. The statistics
file is created on disk with the following name.

  Statistics Data : <Data Name>NnMmQqBb.stat

4) Statistics

MPEGTool statistics creates several types of graphs to analyze
statistical properties of MPEG encoded video stream. Four types
of graphs can be selected, Distribution, Generation Record,
Autocorrelation and Interarrival Time. First three of these plot
each statistics of MPEG code in five levels, Bit/Frame,
Bit/Slice, Bit/MacroBlock, ATM/Frame and ATM/Slice. Interarrival
Time plots the time elapsed between arrivals of ATM packets
within a frame.  The interarrival times are calculated from the
bits generated per macroblock within a frame.  This interarrival
time is normalized to units of X seconds (where X will depend on
the hardware implementation of the coder).

To create graphs, the MPEGTool statistics files have to be
prepared at the time of encoding and can then be chosen from the
Statistics Data File option in MPEGTool Statistics window. After
setting graph options, click Makegraph button. Then MPEGTool
creates command macros (plot.gnu) and data (plot.dat) for gnuplot
and display graphs on screen until clicking clear button.
PostScript file will be created after displaying graph if you set
Create PostScript File option on MPEGTool Statistics window.

5) Data Structures

Data structures which are used in MPEGTool are as follows:

a) Video data (RGB and CCIR)

  RGB or CCIR frame * number of frames

RGB video frame structure

  R * width * height -> G * width * height -> B * width * height

  where R, G, B are the level of red, green and blue.
  R, G, B are unsigned char(= byte) ranged from 0 to 255

CCIR video frame structure :

  CCIR-601 specification

b) MPEG encoded data

  MPEG-1 specification

c) MPEG statistics data

  General Header -> each Frame Statistics * number of frames

General Header

   8 * char : "MPEGTool", identifier of MPEGTool stat file
       int : Intra frame interval
       int : Intra/Prediction frame interval
       int : quantization scale
       int : DCT coefficients in HP stream
       int : start frame number
       int : number of frames to encode
       int : width of frame
       int : height of frame

Frame Statistics

  MB(macroblock) coding mode (char) * number of MB ->
  number of bits in each MB (HP) * number of MB ->
  number of bits in each MB (LP) * number of MB
  (LP only exist when DCT coefficient < 64)

  where MB coding mode is represented as
    0: Intra
    1: Forward Prediction
   11: Forward Prediction without Motion Compensation
    2: Backward Prediction
    3: Interpolate

d) Gnuplot data file (plot.dat), ASCII format

Generation Record/Autocorrelation

  n H L H+L "0 * number of data

Distribution/Interarrival Time

  c H 0 H L 0 L H+L 0 H+L "0 * number of class

  where n is data number (e.g. macroblock number, slice number,
  frame number), c is class of distribution/interarrival time,
  H, L, H+L are the data value (e.g. number of bits, number of
  ATM cells, autocorrelation, number of data in class, etc.) of
  high priority stream, low priority stream, sum of these.

6) Remarks

BUGS

We have found several bugs in MPEGTool.  In some rare cases,
MPEGTool progress window crashes with a segmentation fault. If
this happens frequently, put the NO_PROGRESS option while
compiling MPEGTool.

Please send bugs/comments/suggestions to mpegtool@ee.upenn.edu.

ACKNOWLEDGEMENT

Some part of Motif function refers "Dan Heller. Motif Programming
Manual, O'Reilly & Associates, Inc., 1991". COPYRIGHT of These
part follows instruction shown below.

  Written by Dan Heller.  Copyright 1991, O'Reilly && Associates.
  This program is freely distributable without licensing fees and
  is provided without guarantee or warrantee expressed or
  implied. This program is -not- in the public domain.

SEE ALSO

"MPEGTool: An X windows based MPEG encoder and statistics tool",
Proceedings of ACM Multimedia '93, Anaheim, CA

This paper contains more details and several examples about
MPEGTool.  PostScript file of this paper is placed on anonymous
ftp on atum.ee.upenn.edu.
