This file contains seven sections

1. About the Software
2. Compiling the Software
3. Running the Encoder Software
4. Running the Decoder Software
5. Notes/Known Bugs/Problems
6. Using Traces in the Decoder
7. Using Random Access
8. Using software for bitstream exchange
9. Basic flags used in Makefile

Edited by: 

Noel Brady & Noel O'Connor
Teltec Ireland
Noel.Brady@Teltec.DCU.ie
Noel.OConnor@Teltec.DCU.ie
wollborn@tnt.uni-hannover.de
ferran@gps.tsc.upc.es
Robert.Danielsen@nta.no
zhou@hhi.de
Aasmund.Sandvand@nta.no
beifrig@nlvl.com
m-frater@adfa.oz.au

======================================================================

1. ABOUT THE SOFTWARE ------------------------------------------------

======================================================================

This README file accompanies the release of the MPEG-4 VM software as
developed within the framework of the European ACTS project MoMuSys.
The software contains an encoder and decoder compliant as much as
possible with FCD. 


Some of these options will be included in future releases.
Nevertheless, we encourage MPEG participants outside of MoMuSys to
provide these modules or some new modules that may have to be
implemented for future releases and we will integrate them. If you
have the intention to implement any new part, state this intention by
sending a mail to majordomo@research.kpn.com. It is still possible to have
some hidden bugs as it is extremely difficult to check all coding
possibilities the encoder has.  We are continually working on the
software to enhance it and to implement the MPEG-4 new capabilities.
Any problems or suggestions you have for improving the software should
also be sent to this reflector.

To subscribe to the MOMVM (MoMuSys MPEG4 VM) reflector:

Send the following  e-mail to MAILSERV@research.kpn.com :

     SUBSCRIBE MOMVM your-email-address

To unsubscribe from the MOMVM reflector:

Send the following  e-mail to MAILSERV@research.kpn.com :

     UNSUBSCRIBE MOMVM your-email-address


If you have some difficulties with subscribing/unsubscribing, please
contact Cor Quist (C.P.Quist@research.kpn.com).


In general, by providing this software, we are hoping to encourage
collaboration on software development within MPEG. We have provided
also on the same ftp sites a document covering the data structures and
programming rules which we have used within the software. Please read
the header copyright attached to all files in the vm_common, vm_enc and vm_dec
directories. For data structures used in MoMuSys please refer to the file vm_common/include/momusys.h.

======================================================================

2. COMPILING THE SOFTWARE --------------------------------------------

======================================================================

The software C sources are provided in 3 directories/modules
i.e. vm_enc, vm_common, vm_dec. The vm_enc directory
contains sources for implementing the encoder. The vm_common directory
contains sources which are used in both encoder and decoder
e.g. motion compensation. The vm_dec directory contains sources for
implementing the decoder. It may be integrated into one or more of the
other directories later on. Makefiles and documentation files are
provided in the top level directory.

The software is written to strict ANSI C rules and designed to compile
under a variety of compilers. The software is compiled using the GNU
make utility i.e. gmake. (Warning: the classical make does not work).
During compilation, the sources within each module are compiled into a
library and placed under the lib directory. Due to the module
structure described above, it is necessary always to compile the
vm_common library. If it is necessary only to compile the encoder for
instance, delete the the word vm_dec from line 32 of the Makefile.
Alternatively, the decoder executable only can be produced by deleting
the word vm_enc at the same line number.

The Makefiles provided are designed to maintain several library
versions in parallel. That is, at any one time, the lib directory can
store several library files built for different systems e.g. SOLARIS1,
SOLARIS2, LINUX.  Furthermore, libraries with debug information can
coexist with the normal libraries.

Currently, the software has been compiled and tested with the gcc
compiler on several hardware platforms, see the PORTABILITY file. Some
minor adjustments in the Makefiles may be required to compile with
other compilers.

Prior to compiling the software, one may need to edit the files in the
machines directory to set up the correct paths for the compiler and
other utilities.

For example, if your system is running SOLARIS1 then edit the file
machines/SOLARIS1_options and type

> make SYSTEM=SOLARIS1

to begin the compilation.


To view all the make options, type 

> make usage


Here is a summary of the utilities you will require to use this software:

Requirements 
------------
Mandatory: cproto-3pl7
           GNU make-3.74 or higher
           a GNU gcc compiler (see PORTABILITY file)           

Optional : GNU rcs-5.6.0.1 or higher for RCS revision control.
           GNU perl version 5.001 for automatic HTML documentation option.
           (and of course a HTML Web browser for this latter option) 



Please note: In the distributed version the prototype files are already
             generated. If you have any problems with them, please touch
             all the c-files in the source directory and they will be 
             created again, using your local cproto tool.




2.1 AUTOMATIC PROTOTYPE GENERATION

The makefiles support automatic prototype generation. For each C
source file in the directory vm_enc/src, there will be one *.p file
produced and placed in the vm_enc/include/proto directory. This *.p
file will contain a function prototype for each function defined in
the source file. It is recommended that this prototype file is
included within a header file (*.h) in the vm_enc/include
directory. The header file is then included within the relevant source
files.

To use this automatic feature, it is required that the 'cproto'
utility is available on your system. The source and makefiles for this
utility can be retrieved from the same ftp site where you downloaded
the VM software. The file is called cproto.tar.gz.




2.2 AUTOMATIC DOCUMENT GENERATION

Requirements: perl and a HTML viewer

* To generate the doc:
        - Modify the path of perl in the first line of generate_doc.pl
        - Run : make doc

It will create HTML files in the vm_common/doc, vm_enc/doc and vm_dec/doc 
directories.

To view the doc , load : vm_enc/doc/vm_enc.html 


To produce doc from your own source files :

generate_doc.pl recognizes the following keywords:
HeaderBegin
HeaderEnd
CommentBegin
CommentEnd
 --

Usually add a box like this on top on the file :
/*************************************************HeaderBegin****************/
/*                                                                          */
/* File :        vop.c                                                      */
/* Module :      vm                                                         */
/*                                                                          */
/*************************************************HeaderEnd******************/

Enclose your own comments (anywhere in the source file) between a line
containing "CommentBegin" and a line containing "CommentEnd", like this:

/***********************************************CommentBegin*****************
 *  -- VOP_CodeInter -- code one image normally or two images as a PB-frame
 *
 * put here your comments>
 *
 ***********************************************CommentEnd*******************/

The line starting with  " --"  will also be extracted.





2.3 SUPPORTING IMAGE FILE FORMATS

The software is capable of reading and writing RAW image file
formats. For example, a sequence stored in merged yuv format without
headers can be read and written. Alternatively, the y, u and v data
can be in separate files.  The source code for this is provided in
io_generic.c and io_raw.c in vm_common/src. If you wish to customise
the software for use with your own specific image file format, read
the next section


2.3.1 Customising the I/O Software

Each new user of the software must make some small modifications to
allow the software to operate with their specific image file
format. This involves including new code in the file
vm_common/src/io_generic.c and vm_common/include/ io_generic.h. For
example, an organisation named ACME uses a file format which is
unsupported. The lines

#ifdef _ACMEIO_
ReadVopACME(y_file,u_file,v_file,alpha_file,number,format,curr_vop_in);
#endif

are added to the function ReadVopGeneric(), and the lines

#ifdef _ACMEIO_
WriteVopACME(curr_vop_in,y_file,u_file,v_file,alpha_file,number,
             format,mode, write_alpha);
#endif

are added to the function WriteVopGeneric() in io_generic.c.

The source for the ACME i/o functions is put in a file io_acme.c and
placed in the vm_common/src directory. The corresponding header file
io_acme.h is placed in the vm_common/include directory

The lines

#ifdef _IO_ACME_
#include "io_acme.h"
#endif

are added to io_generic.h in the include directory. 

The software must then be compiled with the directive -D_IO_ACME_.
This is simply done by setting the EXTRA_CFLAGS variable in Makefile
(line 54).

e.g. EXTRA_CFLAGS = -D_IO_ACME_

In order to write compliant site-specific I/O routines, see the
prototypes below or the HTML documentation for ReadVopGeneric() and
WriteVopGeneric() i.e.  doc/io_generic.c.html.

The prototypes of these IO functions are:

        Void ReadVopGeneric(Char *y_file,
                                Char *u_file, 
                                Char *v_file,
                                Char *alpha_file,
                                Int  number, 
                                Char *format,  
                                Vop  *vop)
        
        Void WriteVopGeneric(Vop *vop, 
                                Char *y_file,
                                Char *u_file,
                                Char *v_file,
                                Char *alpha_file,
                                Int      number,
                                Char *format, 
                                Char *mode
                                Int write_alpha)

                                        
        where : y_file - name of vop Y file on disk
                u_file - name of vop U file on disk
                v_file - name of vop V file on disk
                alpha_file - name of vop alpha map on disk
                number - Temporal location of image fields (i.e. 
                                number = 0, is first frame in disk sequence,
                                number = 1, is second, and so on)
                format - Partners preferred image format (defined
                                         in io_generic.h)
                mode - For writing, either "APPEND" or "OVERWRITE"
                vop - pointer to vop to be filled
                write_alpha - a flag to indicate whether the alpha plane
                                of the vop is written to disk.
        
        *** n.b. *** For ReadVopGeneric(), the vop to be filled is assumed 
        to be allocated outside this function. MoMuSys vops are allocated 
        with the dimensions of U & V half that of Y & Alpha (when coding 
        a vop this is assumed in numerous places). Therefore this function
        should fill the image fields of the vop in this manner i.e.
        whatever way the sequences are stored on disk, any up/down
        sampling should be performed within this function.
        





======================================================================

3. RUNNING THE ENCODER SOFTWARE --------------------------------------

======================================================================

The encoder is controlled by a control file and some
arguments passed to it.

To run : vm_enc.exe control file [stats file]

control_file - Name of control file
stats_file - Name of file on disk to store the encoding statistics

If the user does not specify a parameter for stats file the encoding
statistics will be written to the file 'encode.dat'.
                                

3.1 CONTROL FILE

The control file contains high level control information required for
running the encoder. An example control file (encoder.ctl) is supplied
with the software. A .ctl file must contain:

n1               <-- Number of Video Objects (VOs) to code
n2               <-- Number of Video Objects (VTCs) to code
display.y       <-- The name of the composited display seq. on disk (Y comp.)
display.u       <-- The name of the composited display seq. on disk (U comp.)
display.v       <-- The name of the composited display seq. on disk (V comp.)
width           <-- Width in pixels of the display
height          <-- Height in pixels of the display
0		<-- {post-filter type: 0 - disabled, 1 - deblock, 
        			 2 - deringing, 3 - combined}
BitsPerPixel	<-- pixel depth
VO0.cfg         <-- Name of first VO configuration file
.
.
VOn1.cfg         <-- Name of N1th VO configuration file

VTC0.cfg         <-- Name of first VTC configuration file
.
.
VTCn2.cfg         <-- Name of N2th VTC configuration file

n		<-- {Type of rate control: 0-NONE, 1-VM4, 2-VM5+, 3-TM5}
n|n|n|n|n|n     <-- {RC String: Alg|rate_mod|dist_mod|Target|buffer|mode}



3.2 VO and VTC CONFIGURATION FILE

A configuration file contains all information required for coding all
Video Object Layers (VOLs) of a particular VO. Two example
configuration files (VO0.cfg & VO1.cfg) are supplied with the
software. A .cfg file must contain:

*****************************************************************
*                VO Configuration Information                   *
*****************************************************************

VO Id   <-- VO Id
n       <-- Number of layers   (1, single layer coding, 
                             2, temporally, Spatial scalable coding)

*****************************************************************
*                BASE VOL Configuration Information             *
*****************************************************************

VOL Id          <-- VOL Id  
Frame Rate      <-- VOL frame rate
M               <-- Number of B-VOPs (M-1) between two consecutive P-VOPs
VOL dim X       <-- These are the dimensions (of Y (= Alpha)) of the VOPs
VOL dim y           to be used in encoding this VOL (before bounding 
                    rectangle extraction.
disk seq frame rate <-- This is the frame rate of the VOL sequence (all 
                        components) on disk.
alpha type  <-- Type of alpha channel to be used 0-RECTANGULAR, 1-BINARY, 
                2-GREY LEVEL, 3- BINARY SHAPE CODING ONLY 
OBMC disable <-- OBMC disable: 1-disable, 0 -enable}
quantizer precision  <-- number of bits used to transmit quantiser
pixel depth          <-- number of bits per pixel
shape_effects	<-- Type of shape effects to be used
VOL.y   <-- This is the name of the file containing the Y image data for the VOL
VOL.u   <-- This is the name of the file containing the U image data for the VOL
VOL.v   <-- This is the name of the file containing the V image data for the VOL
VOL.a <-- This is the name of the file containing the alpha map for the VOL
write coded     <-- Write the coded VOPs to disk, 0 - no write, 1 - write
CODED.y <-- This is the name of the file containing the coded Y component
CODED.u <-- This is the name of the file containing the coded U component
CODED.v <-- This is the name of the file containing the coded V component
CODED.a <-- This is the name of the file containing the coded alpha component
VOL.bits <-- Name of bitstream file on disk for this VOL
start frame     <-- VOL start frame
end frame       <-- VOL end frame
start time      <-- Time (in ms) at which VOL first appears
target bit-rate <-- Target bit-rate for VOL
1.|40.          <-- String for Global RC Parameter 1 (weight or position in priority list) and 2 [dB]
alpha th        <-- Alpha coding threshold
change_CR_disable<-- change_CR_disable: 0 - enable, 1 - disable
quant type      <-- VOL quant. type select: 0 - H.263 quant, 1 - MPEG2 quant.
0	        <-- VOL load_intra_quant_mat: 0-no, 1-userdefined, 
			      2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
iqmat.dat       <-- file name for userdefined intra_quant_mat if userdefined}
3	        <-- VOL load_nonintra_quant_mat: 0-no, 1-userdefined,
					       2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
nqmat.dat       <-- file name for userdefined nonintra_quant_mat if userdefined}
0	        <-- VOL load_gray_intra_quant_mat: 0-no, 1-userdefined,
					       2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
giqmat.dat      <-- file name for userdefined gray_intra_quant_mat if userdefined}
0	        <-- VOL load_gray_nonintra_quant_mat: 0-no, 1-userdefined,
                                               2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
gnqmat.dat {file name for userdefined gray_nonintra_quant_mat if userdefined}
quant_Intra     <-- Initial value for quantizer - INTRA
quant_Inter     <-- Initial value for quantizer - P_VOPs
quant_Inter     <-- Initial value for quantizer - B_VOPs
quant_GL	<-- Quantizer for gray level alpha maps}
quant_GL_update	<-- Quantizer update flag for gray level quantization}
error-res	<-- Flag to disable error resilience mode:
			0 - enabled, 1 - disabled
data partitioning<-- Flag to enable the use of data partitioning mode: 0 - disabled
reverse_VLC		<-- Whether or not to use reversible VLCs
packet_size     <-- approximate size of resync packet in bits 
INTRA shape refresh period <-- for error resilient mode, specifies the period in frames for INTRA shape (do not set = zero). 
disable ac/dc pred <-- Flag to disable ac/dc pred in INTRA MBs: 
                        0 - enabled, 1 - disabled
SA-DCT		<-- Flag to disable SADCT coding : 0 - enabled, 1 - disabled
sr_pf		<-- search_range_per_coded_frame
scalability    	<-- Flag to indicate scalable coding: 
                                0 - base layer,1 - enhancement layer
scal_type	<-- Flag to indicate scalability types:0 - temporal, 
			1 - spatial, 2-both
ref layer Id    <-- Ref. layer Id in the case of scalability
ref layer samp direc.   <-- Ref. layer sampling direction: 
                                0 - same or lower res., 1 - higher res.
hor samp n 	<-- Hor. sampling factor - n
hor samp m 	<-- Hor. sampling factor - m
ver samp n 	<-- Ver. sampling factor - n
ver samp m 	<-- Ver. sampling factor - n
enhance_type 	<-- Enhancement type: 0 - whole frame, 1 - partial region
intra_period	<-- Period between Intra updates
GOV_period      <-- Period between Group of VOPs  updates  0-no GOV,
                    >0 -one GOV every GOV_period of VOPs 
interlaced      <-- 1=Interlaced, 0=Progressive
topfieldfirst   <-- 1 if top line is part of first field, else 0
alternatescan   <-- 1 to use vertical alternate scan for all interlaced blocks
directrad       <-- Direct mode search radius (half pels)
MVfileUsage     <-- MV file usage: 0-don't use; 1-read; 2-write
mvfile.dat      <-- Motion vector file name
sprite_usage*	<-- Reading sprite usage (0:no, 1:static, 2:dynamic, 3:GMC)
sprite_width	<-- Sprite horiz. size
sprite_height	<-- Sprite vert. size
sprite_left_edge<-- Sprite left edge
sprite_top_edge <-- Sprite top edge
n		<-- Number of Sprite Points
n	        <-- warping accuracy 0/(1/2) 1/(1/4) 2/(1/8) 3/(1/16)
n	        <-- lighting_change_in_sprite is 0/FALSE 1/TRUE 
0.50		<-- blending factor
1		<-- Write the sprite to disk, 0 - no write, 1 - write
sprite.vo0.yuv	<-- Name of sprite seq. on disk (Y-comp)
sprite.vo0.yuv	<-- Name of sprite seq. on disk (U-comp)
sprite.vo0.yuv	<-- Name of sprite seq. on disk (V-comp)
sprite.vo0.a	<-- Name of sprite seq. on disk (A-comp)
n	        <-- sprite shape 0/RECTANGULAR 1/BINARY 
bibi.dat	<-- Warping parameters file name (static only)}
sprite_width0	<-- init_sprite_width}
sprite_height0	<-- init_sprite_height}
sprite_left_edge0<--init_sprite_hor_ref}
sprite_top_edge0 <--init_sprite_ver_ref}
50.0	        <--SNR Threshold (for UPDATE pieces) 

* NOTE: in the case of scalable coding, if (sprite_usage==0)
        the parameters after "sprite_usage" should be removed from the
        configuration file!!!! 

*****************************************************************
*       ENHANCEMENT VOLs Configuration Information              *
*****************************************************************

VOL Id          <-- VOL Id  
Frame Rate      <-- VOL frame rate
.
.
.
ver samp m      <-- Ver. sampling factor - n
enhance type    <-- Enhancment type: 0 - whole frame, 1 - partial region
.
.
.




*****************************************************************
*                VTC Configuration Information                   *
*****************************************************************

A VTC configuration file for the WAVELET image coding must contain:

vtc_id		<---VTC ID 
vtc.bits	<---Output bitstream file for this VTC object   
width		<---Hor. size of the image on disk
height		<---Ver. size of the image on disk
shape_type	<---alpha channel 0-RECTANGULAR, 1-ARBITRARY
alpha_thre	<---alpha threshold
n	        <--change_CR_disable 1: diable 0: enable
original.yuv	<---The source image  file on disk (YUV)
original.seg	<---The source segmatation map file
recon.yuv	<---reconstructed image file for this VTC  
0		<---filter type (default: 0)  
5		<---wavelet decomposition levels   
n		<---quantization_type 1:single_quant, 2:multi_quant, 3: bi-level 
1		<---SNR_start_code_enable  1: enable 0:disable         
bit_rate	<--- target_bit_rate  
2		<---target_spatial_levels 
2		<---target_snr_levels         
0 0		<---de-ring: threshold,  window size     
10		<---QdcY                        
10		<---QdcUV                       
2               <---spatial_scalability_levels  
2 30 30 10 10   <---SNR_scalability_levels QY QUV .....
2 30 30 10 10   <---SNR_scalability_levels QY QUV .....




3.3 IMPORTANT THINGS TO NOTE ABOUT THE .ctl .cfg FILE

3.3.1 Gerneral notes

(a) In the case of scalable coding the BASE layer configuration 
    information MUST come first in the .cfg file. 

(b) When coding a number of VOs, ideally at least one VO should have a
    start time of 0, and the start times of the remaining VOs are selected
    relative to this, (taking into account the time increment of the
    encoder which will be the highest frame rate of all VOs).

(c) Some of the parameters and flags are dummy entries, they are
    not implemented in the code yet, e.g.:

	Shape effects


3.3.2 NOTES ON RATE CONTROL

   3.3.2.1 COMPILATION PARAMETERS FOR VM5.0 RATE CONTROL
   -------------------------------------------------------

   * A rate control debugging version can be obtained by defining 
     "-D_RC_DEBUG_".
   * The frame skipping feature to prevent buffer overflow can be disabled
     by defining "-D_RC_NO_SKIPPING_".
   * Other parameters (rc.h) for Q2 rate control algorithm (the values in the
     VM specification are not very clear. Default values are provided).
        START_MODEL_UPDATING:   Number of the first frame after whose coding 
                                the model parameters are updated.
        START_OUTLIER_REMOVING: Number of the first frame after whose coding 
                                the updating of the model paramers includes 
                                the "outlier removing" operation.
   * Through compilation with the compiler flag "-D_RC_UPM2" will be obtained
     a version with the possibility to choose of two different estimation
     models for UPM-algorithms.
     NOTE: This is only for Momusys internal use (see note in section 3.3.2.2
           point 2.2.) Selection of models.) and needs the files rc_util2.c
           and rc_upm_model2.c 

   3.3.2.2 CONFIGURATION PARAMETERS FOR RATE CONTROL
   -------------------------------------------------- 

   The encoder rate control has to be configured using the *.ctl
   and *.cfg files. 

   The configuration consists in the specification of 

    - General parameters
        - Type of control (fixed QP, VM4 type, other type).
        - Control algorithm (global or individual, different algorithms 
          in each case).
        - Statistical models for rate and distortion.
    - Parameters for global control:
        - Global bit-rate
        - Buffer size
    - Parameters for individual control 
        - Bit-rate per VO
        - Buffer size for each VO

   The general and the global control parameters are specfied in the .ctl file,
   and the individual control parameters in the .cfg files.
   They are (except the parameter for the type of RC) arranged in  
   strings (one in the .ctl file and one in each .cfg file), detached by
   a special character ("|"), from which the program extracts the respective 
   values.

   Each of these parameter strings and the containing parameters are now
   described in detail:

   ----------------------------
   Parameters in the .ctl file:
   ----------------------------

   * General parameters:

        Int    {Type of rate control: 0 - NONE, 1 - VM4, 2 - VM5+}
	Char   {Parameter string: 
	        algorithm|rate_model|dist_model|target_rate|buffer_size|mode}


     The main configuration is made by selecting the TYPE of rate
     control from various modes, the ALGORITHM and the rate- and distortion
     MODEL. These parameters depend on each other in the following manner:

     1.) Selection of type (type of rate control in .ctl file):
 
        0 - Fixed QP  for each type of VOP (I,P,B) (NO RATE CONTROL)

        1 - VM4:  Primitive version of RC, works independently for every VOP 
                  (not recommended).

        2 - VM5+: All other algorithms (for either global or independent 
                  control).


     2.) Parameter string

     2.1.) Selection of algorithm (rate control algorithm in .ctl file):

         ----------------------------
         >>   (Int)algorithm|...   <<
         ----------------------------

        In the case that mode 2 - VM5+ is selected, it is possible
        to choose from three rate control algorithms (in case of mode 0 
        and 1 these parameters have no influence):

        0 - Q2:   Rate control specified in VM, only independent control for 
                  every VOL.

        1 - UPM1: Individual or global rate control. In the global control 
                  case, distribution of the global bit-rate among the VOPs 
                  attempts to minimize the sum of weighted distortions-per-
                  pixel of the VOLs. The weights for each VO are given by the 
                  user through "Global RC Parameter 1" in the configuration 
                  file of each VOL. (More information below)

        2 - UPM2: Individual or global rate control. In the global control 
                  case, distribution of available bits among VOLs is made 
                  according to a priority list and a target PSNR for each VOL.
                  The index of each VOL in the list is given by the user 
                  through "Global RC Parameter 1" in the configuration file of
                  the VO and the target PSNR is given in "Global RC Parameter 2" 
                  in the same file. 
                  This algorithm intends to obtain a desired quality at least 
                  for the most important VO. If it is not possible because of 
                  limitations in bit-rate, it will be coded as well as 
                  possible. (More information below)


     2.2.) Selection of models (rate- and distortion model in .ctl):

         -------------------------------------------------
         >>   ...|(Int)rate_model|(Int)dist_model|...   <<
         -------------------------------------------------

        These parameters determine the models used for prediction of
        bit-rate and distortion. At the moment three models are available,
        one ONLY used by the Q2 algorithm and two for the two UPM algorithms.
        The Q2 algorithm can not use an UPM model and vice versa, but in case 
        that the Q2 algorithm is selected, the Q2 model will be used auto-
	matically, even if a wrong value was specified.        
	NOTE: The second UPM model (UPM2) is for Momusys internal use only 
              (see Note below.)

        0 - Q2:   To be choosen if in 2.1.) RC algorithm 0 - Q2 selected.

        1 - UPM1: Modified Q2 model based on least square calculation.
                  To be choosen if in 2.1.) RC algorithm 1 - UPM1 or 2 - UPM2 
                  selected.

        2 - UPM2: Modified Q2 model based on singular value decomposition
                  and a special model adaption process.
                  To be choosen if in 2.1.) RC algorithm 1 - UPM1 or 2 - UPM2 
                  selected. (for Momusys internal use only, see Note below.)

   >>>> IMPORTANT NOTE: <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
   >
   >     Some options not included in the VM specification but developed 
   >     within Momusys are not included in the donation because their 
   >     implementation includes software whose copyright does not belong 
   >     to the project.
   >
   >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
         
        >>>>> VM8 Rate Control Configurations <<<<<<<


        First of all, type of rate control in 1.) should be set to 2 (VM5+)
        Secondly, RC algorithm in 2.1.) should be set to 0. rate_mode is set 
        as follows.    
        
        1 - Macroblock-based rate control

             MB-based rate control is only valid for encoding a single 
             rectangular VOP with the coding structure I P P P P. The I-frame
             uses the initial QP given in .cfg file, but P-frames are
             MB-based controlled. This RC is even not valid for the structure
             like I P P P P ... I P P P P ...

        2  - VM Multi-VO Rate Control

	     Multi-VO RC becomes Single-VO RC only when there is a single VO
             encoded
  
        3 -  VM Multi-VO Rate Control + HVS

	     This Rate control means that the QPs for the first I-frame and 
  	     the first P-frame are obtained based on the HVS quantizer, then 
             the subsequent QPs are calculated by the RC algorithm. Note that
 	     this mode works only for the multiple video object case (in VM8). 



     2.3.) Global RC parameters: Global target bit-rate and global buffer size

         ---------------------------------------------------
	 >>   ...|(Int)target_rate|(Int)buffer_size|...   <<
         ---------------------------------------------------

        These two parameters only have effect if as second parameter
        (rate control algorithm) one of the global algorithms is choosen 
        (UPM1 or UPM2). In case of 1 - Q2, they are ignored.

        The selected values are used GLOBALLY, i.e. "target bit-rate" means 
        the desired bit-rate for ALL VOPs in a frame. The algorithms then 
        distribute this bit-rate according to the certain preferences.
        The value for "global buffer size" indirectly determines the amount 
        of bits that can be absorbed for all VOPs if suddenly unexpected peaks 
        appear.
        An appropriate size is half of the target bit-rate.


     2.4.) Mode of distortion model

         -----------------------
         >>   ...|(Int)mode   <<
         -----------------------


        It is possible to choose from two modes concerning the 
        distortion estimation:

	0 - calculates distortion per pixel

        1 - calculates total distortion (multiplication of pixel 
            distortion with number of pixels in object)

	This works independently from the algorithm, default value (if
        no or wrong value given) is 0.

   >>>>>>>>>>>>>>>>>>> Notes on string usage <<<<<<<<<<<<<<<<<<<<<<<<<
   >
   >  1.) Each of the values in the string can be replaced by a '*' or 
   >      (if it's at the end) left blank, if the default value is wanted
   >      or the parameter is not necessary for the specified algorithm.
   >
   >  2.) Wrong values force the use of the default values.
   >
   >  3.) Before or after the token separator string '|' are no blanks 
   >      allowed, because a blank means the end of the string.
   >
   >  4.) The DEFAULT SET of the string is:
   >
   >      1|1|1|256000|128000 or target_rate/2 |0
   >
   >      See also examples in 3.3.2.4.
   >
   >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

   ----------------------------
   Parameters in the .cfg file:
   ----------------------------

   The configuration files contain three rate control parameters:

        Int       {Target bit-rate for VOL}
	Char      {Glob_RC_Param_1 | Glob_RC_Param_2 | Glob_RC_Param_3}
	           (Double)          (Double)         (Double)

   * The target bit-rate in this case determines the bit-rate desired 
     individually for the here configured VOP, it could be different for 
     every VOP. (Takes only effect in case of Q2 algorithm)

   * The three parameters read from one string are only used by the 
     global control algorithms (UPM1/UPM2) and have got different meanings 
     depending on the selected algorithm:

     UPM1 uses only all three parameters. 
     UPM2 uses only the first two ones.

     Because they have different meanings in relation to the algorithms, 
     the information about appropriate values can be found below in the 
     description for each algorithm.

	DEFAULT SET:      1.|1.|1. for UPM1
			  1.|35.   for UPM2


   3.3.2.3 MORE INFORMATION ON UPM ALGORITHMS
   ------------------------------------------

   Algorithm UPM1
   --------------

   * The three global RC parameters (in .cfg files) serve to give different 
     importances in coding quality to the particular VOLs.
     They are used as weights for the distortion values, the higher the 
     value, the better will be the quality. 
     There are three of them for every VOL to give it different weights
     depending on the frame type. 
     The orden is: weight(I)|weight(P)|weight(B)
 
     Recommendation: values between 0.1 and 1.0

   The algorithm works as follows:

       Numerical minimization of the 

         SUM_i=1..n of [rate(qp) + alpha_i(frame_type) * distortion(qp)]_i

       for n VOLs
       where alpha_i is the global RC parameter.


   Algorithm UPM2
   --------------

   * The first of the global RC parameters (in .cfg files) also serves to give
     different importances in coding quality to the particular VOs (or VOLs in
     case of scalability) by specifying its position in a priority list. 
     The list is built with the values assigned to the VO starting with the 
     lowest value for the most important VO, so every VO should have
     a different value. If the same value is given to more than one VO, 
     the first VO found will be the first in the list. Here it is not possible 
     to assigne different positions according to the frame type.

     Recommendation: any value. Equal values are treated according to the
                                order of appearence.

   * The second global RC parameter (in .cfg files) represents the desired 
     coding quality for the most important VOL (which has the lowest first 
     parameter of all VOs) and has to be provided as a PSNR value in dB.
     -> This parameter is ignored for all other VOs!

     Recommendation: Reasonable targets can only be determined after some 
                     preprocessing of the sequence, as the achievable PSNR 
                     strongly depend on sequence, frame rate and global 
                     bit-rate, but in any case, the algorithm respects the 
                     order and tries to code the most important VOL best as
                     further described.

   The algorithm works as follows:

     At least the most important VOL is tried to be coded with the quality 
     given by parameter 2. Firstly, the QPs necessary for all VOs to reach 
     this target are calculated. 

     - If the resulting bit-rate with this set of QPs is too high 
       (higher than the current available rate), the QPs are decreased 
       according to the priority list starting with the last important VOL. 
       -> Here it could happen, that the desired quality is NOT reached!
          (Coder gives warning message)

     - If the resulting bit-rate is lower than the current target, 
       the QPs are increased starting with the most important VOL until
       the target is reached.


   3.3.2.4 EXAMPLES for VM5+ 
   -------------------------

     Here some typical examples are given for VM5+ rate control.
     For the global control (UPM1, UPM2), these examples correspond
     to a four object sequence (like NEWS).

     If an '*' is given instead of a value it means that this parameter
     is not used.

     I. VM5+ Rate Control - Q2:
     --------------------------

        * .ctl file:

           2       {Type of rate control: 0 - NONE, 1 - VM4, 2 - VM5+}
	   0|*|*|*|*|*  {Rate control algorithm: 0 - Q2}

           The only necessary value is 0 for the algorithm. Also possible:

           2       {Type of rate control: 0 - NONE, 1 - VM4, 2 - VM5+}
	   0       {Rate control algorithm: 0 - Q2}


        * .cfg files:

	VO 0:

           64000   {Target bit-rate for VOL}
           *|*|*   {weight I | weight P | weight B}

	VO 1:

           64000   {Target bit-rate for VOL}
           *|*|*   {weight I | weight P | weight B}

	VO 2:

           64000   {Target bit-rate for VOL}
           *|*|*   {weight I | weight P | weight B}

	VO 3:

           64000   {Target bit-rate for VOL}
           *|*|*   {weight I | weight P | weight B}


     II. VM5+ Rate Control - UPM1:
     -----------------------------

        This example assumes the following importances for 
        four VOs:
                                     param.1  
        VO 0   third important         0.5    
        VO 1   second important        0.8    
        VO 2   most important          1.0    
        VO 3   least important         0.3    

       * .ctl file:

          2       {Type of rate control: 0 - NONE, 1 - VM4, 2 - VM5+}
          1|1|1|256000|128000|0  {Parameter string}

	         with  algorithm = UPM1, rate_model = UPM, dist_model = UPM, 
                 target_rate = 256000, buffer_size = 128000, mode = 0.

          The same effect has: 

           2       {Type of rate control: 0 - NONE, 1 - VM4, 2 - VM5+}
	   1       {Parameter string}
	         which uses the default values.
       
        * .cfg files:

        VO 0:   *             {Target bit-rate for VOL}
                0.5|0.5|0.5   {weight I | weight P | weight B}

        VO 1:   *             {Target bit-rate for VOL}
                0.8|0.8|0.8   {weight I | weight P | weight B}

        VO 2:   *             {Target bit-rate for VOL}
                1.0|1.0|1.0   {weight I | weight P | weight B}

        VO 3:   *             {Target bit-rate for VOL}
                0.3|0.3|0.3   {weight I | weight P | weight B}


     III. VM5+ Rate Control - UPM2:
     ------------------------------

        This example assumes the following importances for 
        four VOs:
                                     param.1  param.2
        VO 0   third important          1
        VO 1   second important         2
        VO 2   most important           0      35.
        VO 3   least important          3


        * .ctl file:

           2       {Type of rate control: 0 - NONE, 1 - VM4, 2 - VM5+}
	   2|1|1|128000|64000|0  {Parameter string}

	   With  algorithm = UPM2, rate_model = UPM, dist_model = UPM, 
                 target_rate = 128000, buffer_size = 64000, mode = 0


        * .cfg files:

        VO 0:   *       {Target bit-rate for VOL}
                2|*     {position | max. distortion}

        VO 1:   *       {Target bit-rate for VOL}
                1|*     {position | max. distortion}

        VO 2:   *       {Target bit-rate for VOL}
                0|35.   {position | max. distortion}

        VO 3:   *       {Target bit-rate for VOL}
                3|*     {position | max. distortion}

        here it is only necessary to put the second value (the desired
        maximum distortion value for coding) for the VO 2 because it 
        is the most important one.
        


3.3.2.5 MPEG-2 Test Model 5 (TM5) Rate Control
----------------------------------------------

An implementation of TM5 is used if the rate control type entry in the .ctl
file is set to 3.  This is a full implmentation of TM5, including macroblock
adaptive quantization.  Since MPEG-4 does not allow arbitrary quantizer
variation on a macroblock-by-macroblock basis, an out-of-range quantizer
value is saturated to the allowable value closest to the TM5 quantizer.


3.3.3 NOTES ON CAE BINARY SHAPE CODING
 
  VM8 binary shape coding has been integrated.Vop level size conversion has 
  not been implemented yet. Two fields, alpha_threshold and change_CR_disable,
  are used for controlling lossless or lossy coding
 
A. Lossless Coding

0   		{alpha threshold}
1   		{change_CR_disable}

These parameters will result in a lossless code for binary shape.
CR will not be present at the MB layer and the decoder should assume
that CR=1.

B. Lossy Coding

64   		{alpha threshold}
1   		{change_CR_disable}

These parameters will result in a lossy code for binary shape. The loss
is introduced by tolerating mismatches in the motion compensation of each 
BAB. CR will not be present at the MB layer and the decoder should assume
that CR=1 for all BABs.


C. Lossy Coding

64   		{alpha threshold}
0   		{change_CR_disable}

These parameters will result in a lossy code for binary shape. The loss
is introduced by tolerating mismatches in the motion compensation of each 
BAB and by size conversion. CR will be present at the MB layer for every 
BAB. 


3.3.4 NOTES ON STATIC SPRITE

Here is an example of a configuration file used for STATIC_SPRITE;
explanations for the specific fields concerned with STATIC_SPRITE
are given thereafter. Note that these fields are located after the
"sprite_usage" field. If this field is set to zero, these fields 
will not be read by the SW.

*****************************************************************
*                BASE VOL Configuration Information             *
*****************************************************************

VOL Id          <-- VOL Id  
Frame Rate      <-- VOL frame rate
M               <-- Number of B-VOPs (M-1) between two consecutive P-VOPs
VOL dim X       <-- These are the dimensions (of Y (= Alpha)) of the VOPs
VOL dim y           to be used in encoding this VOL (before bounding 
                    rectangle extraction.
disk seq frame rate <-- This is the frame rate of the VOL sequence (all 
                        components) on disk.
alpha type  <-- Type of alpha channel to be used 0-RECTANGULAR, 1-BINARY, 
                2-GREY LEVEL, 3- BINARY SHAPE CODING ONLY 
OBMC disable <-- OBMC disable: 1-disable, 0 -enable}
shape_effects	<-- Type of shape effects to be used
VOL.y   <-- This is the name of the file containing the Y image data for the VOL
VOL.u   <-- This is the name of the file containing the U image data for the VOL
VOL.v   <-- This is the name of the file containing the V image data for the VOL
VOL.a <-- This is the name of the file containing the alpha map for the VOL
write coded     <-- Write the coded VOPs to disk, 0 - no write, 1 - write
CODED.y <-- This is the name of the file containing the coded Y component
CODED.u <-- This is the name of the file containing the coded U component
CODED.v <-- This is the name of the file containing the coded V component
CODED.a <-- This is the name of the file containing the coded alpha component
VOL.bits <-- Name of bitstream file on disk for this VOL
start frame     <-- VOL start frame
end frame       <-- VOL end frame
start time      <-- Time (in ms) at which VOL first appears
target bit-rate <-- Target bit-rate for VOL
1.|40.          <-- String for Global RC Parameter 1 (weight or position in priority list) and 2 [dB]
alpha th        <-- Alpha coding threshold
change_CR_disable<-- change_CR_disable: 0 - enable, 1 - disable
quant type      <-- VOL quant. type select: 0 - H.263 quant, 1 - MPEG2 quant.
0	        <-- VOL load_intra_quant_mat: 0-no, 1-userdefined, 
					      2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
iqmat.dat       <-- file name for userdefined intra_quant_mat if userdefined}
3	        <-- VOL load_nonintra_quant_mat: 0-no, 1-userdefined,
					       2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
nqmat.dat       <-- file name for userdefined nonintra_quant_mat if userdefined}
0	        <-- VOL load_gray_intra_quant_mat: 0-no, 1-userdefined,
					       2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
giqmat.dat      <-- file name for userdefined gray_intra_quant_mat if userdefined}
0	        <-- VOL load_gray_nonintra_quant_mat: 0-no, 1-userdefined,
                                               2-MPEG4 VM7 3- MPEG2 Default 4-MPEG2 TM5
gnqmat.dat {file name for userdefined gray_nonintra_quant_mat if userdefined}
quant_Intra     <-- Initial value for quantizer - INTRA
quant_Inter     <-- Initial value for quantizer - P_VOPs
quant_Inter     <-- Initial value for quantizer - B_VOPs
quant_GL	<-- Quantizer for gray level alpha maps}
quant_GL_update	<-- Quantizer update flag for gray level quantization}
error-res	<-- Flag to disable error resilience mode:
			0 - enabled, 1 - disabled
data partitioning<-- Flag to enable the use of data partitioning mode: 0 - disabled
reverse_VLC		<-- Whether or not to use reversible VLCs
disable ac/dc pred <-- Flag to disable ac/dc pred in INTRA MBs: 
                        0 - enabled, 1 - disabled
SA-DCT		<-- Flag to disable SADCT coding : 0 - enabled, 1 - disabled
sr_pf		<-- search_range_per_coded_frame
scalability    	<-- Flag to indicate scalable coding: 
                                0 - base layer,1 - enhancement layer
scal_type	<-- Flag to indicate scalability types:0 - temporal, 
			1 - spatial, 2-both
ref layer Id    <-- Ref. layer Id in the case of scalability
ref layer samp direc.   <-- Ref. layer sampling direction: 
                                0 - same or lower res., 1 - higher res.
hor samp n 	<-- Hor. sampling factor - n
hor samp m 	<-- Hor. sampling factor - m
ver samp n 	<-- Ver. sampling factor - n
ver samp m 	<-- Ver. sampling factor - n
enhance_type 	<-- Enhancement type: 0 - whole frame, 1 - partial region
intra_period	<-- Period between Intra updates
GOV_period      <-- Period between Group of VOPs  updates  0-no GOV,
                    >0 -one GOV every GOV_period of VOPs 
sprite_usage*	<-- Reading sprite usage (0:no, 1:static, 2:dynamic, 3:GMC)
sprite_width	<-- Sprite horiz. size
sprite_height	<-- Sprite vert. size
sprite_left_edge<-- Sprite left edge
sprite_top_edge <-- Sprite top edge
n		<-- Number of Sprite Points
n	        <-- warping accuracy 0/(1/2) 1/(1/4) 2/(1/8) 3/(1/16)
n	        <-- lighting_change_in_sprite is 0/FALSE 1/TRUE 
0.50		<-- blending factor
1		<-- Write the sprite to disk, 0 - no write, 1 - write
sprite.vo0.yuv	<-- Name of sprite seq. on disk (Y-comp)
sprite.vo0.yuv	<-- Name of sprite seq. on disk (U-comp)
sprite.vo0.yuv	<-- Name of sprite seq. on disk (V-comp)
sprite.vo0.a	<-- Name of sprite seq. on disk (A-comp)
n	        <-- sprite shape 0/RECTANGULAR 1/BINARY 
bibi.dat	<-- Warping parameters file name (static only)}
sprite_width0	<-- init_sprite_width
sprite_height0	<-- init_sprite_height
sprite_left_edge0<--init_sprite_hor_ref
sprite_top_edge0 <--init_sprite_ver_ref
50.0	        <--SNR Threshold (for UPDATE pieces) 
*****************************************************************



sprite_usage	<-- Reading sprite usage (0:no, 1:static, 2:dynamic, 3:GMC)
	The dynamic and GMC sprite mode are not part of the Software in version 1.

sprite_width	<-- Sprite horiz. size
sprite_height	<-- Sprite vert. size
	These values correspond to the size in pixels of the static sprite. 
	Note that these two fields are subject to changes, to cope with sizes 
	being an exact number of Macroblocks (i.e. can be divided by 16)
	
sprite_left_edge<-- Sprite left edge
sprite_top_edge <-- Sprite top edge
	These values define the location of the zero in the sprite image. 
	They can take both positive or negative values. If they are negative 
	for instance, the "zero" reference in the sprite is located "inside"
	the sprite. If the are positive, the zero lies "outside" the sprite.
	
n		<-- Number of Sprite Points
	n=0: zero motion
	n=1: pure tranlational motion
	n=2: zoom, scaling, rotation
	n=3: affine motion
	n=4: perspective motion 
	
n	        <-- warping accuracy 0/(1/2) 1/(1/4) 2/(1/8) 3/(1/16)
n	        <-- lighting_change_in_sprite is 0/FALSE 1/TRUE 
	The lighting change is implemented, but the way the value is introduced
	in the encoding process is not done. Therefore, this field is
	always set to 0.
	
0.50		<-- blending factor
	This field is used in the dynamic and GMC mode only, and indicates
	how the current sprite and the new incoming sprite(vop) should be
	blended, at the pixel locations concerned with the blending. 
	If this value is 0 for instance, then the current incoming
	sprite(vop) will paste completely the previous sprite. If this value
	is 1, then the new sprite will be updated only at places where
	the incoming sprite(vop) provides new inputs.
	
1		<-- Write the sprite to disk, 0 - no write, 1 - write
	This field is used for the dynamic and GCM mode only, to allow the 
	storage of the sprite under construction during the encoding process. 
	This field is put to 0 for the static case.
	
sprite.vo0.yuv	<-- Name of sprite seq. on disk (Y-comp)
sprite.vo0.yuv	<-- Name of sprite seq. on disk (U-comp)
sprite.vo0.yuv	<-- Name of sprite seq. on disk (V-comp)
sprite.vo0.a	<-- Name of sprite seq. on disk (A-comp)
	These four fields are used:
		for reading the static sprite (these fields are mandatory)
		for writing the dynamic or GMC sprite (required when the
			previous field (write/no write) is set to 1. If
			set to zero, dummy names are required anyway).
			
n	        <-- sprite shape 0/RECTANGULAR 1/BINARY 
bibi.dat	<-- Warping parameters file name (static only)
	This field is not required when the number of sprite points is zero.
	Otherwise, this field is required, but used for the static sprite 
	case only. It indicates the name of the file in which the warping 
	parameters are stored. The format of the writing of the warping 
	parameters is the following:
		given the warping as a function of 1,2,3 or 4 points, the
		relation between pixels of the sprite_vop and pixel of the
		sprite is:
			i' = (a*i+b*j+c)/(g*i+h*j+1)
			j' = (d*i+e*j+f)/(g*i+h*j+1)
		The parameters are then stored in the file as:
			a b c d e f g h
			...
		The way these parameters are read can be found in the file:
			/vm_enc/src/sprite_enc_lep_util.c
				>>> ReadWarpingParameters function.
		Since for non perspective motion, some of these parameters
		are zero, and the routine OLDRadWarpingParameters has been
		kept is the SW to deal with *simplified* input format.
		
				
sprite_width0	<-- init_sprite_width
sprite_height0	<-- init_sprite_height
	These fields determine the size of the first sprite piece that will
	be encoded in the VOL header. They are subject to changes to cope
	with:
		- zero or negative values (forbidden: minimum is 16)
		- values being not an exact number of macrocloks.
		
sprite_left_edge0<--init_sprite_hor_ref
sprite_top_edge0 <--init_sprite_ver_ref
	These fields gives the location is the sprite of the top left corner
	of the initial sprite piece that will be sent in the VOL header. 
	These fields are always reference to the top left corner of the sprite 
	itself (the sprite_left_edge and sprite_top_edge are not concerned here)

50.0	        <--SNR Threshold (for UPDATE pieces) 
	Theis value gives the threshold value that will be used for low-latency
	transmission of updated pieces. The decision is taken on a block basis.
	If this field is set to zero, no update pieces will be sent.
	
Note: low-latency sprite transmission will not be enabled if:
		- sprite_width0 is equal to sprite_width
		- sprite_height0 is equal to sprite_height
		- sprite_left_edge0 and sprite_top_edge0 are equal to zero
		- SNR threshold is set to zero.


Limitations
===========

STATIC_SPRITE has been implemented
	- in combined mode only
	- in non-resilience mode
	- GOV are not supported
	- Scalability is not supported

The vm_test module has not been updated


VM Compliancy
==============

VM8


3.3.5 NOTES ON SPATIAL SCALABILITY

The frame-based spatial scalability is supported.

At this moment, the following types of spatial scalability are supported.

a)	Enha    P  B  B  B  ...
	Base    I  P  P  P  ...
b)	Enha	P  P  P  P  ...
	Base    I  P  P  P  ...

If you want to select coding type(a or b), set config parameter 'ss enhancement
layer type' in VO config file { 0 - PBB.., 1 - PPP.. }.


3.3.6 NOTES ON TEMPORAL SCALABILITY

The frame/object-based temporal scalability is supported.

In the case that the frame rate of base layer is 5 fps and that of enhancement
layer is 5 fps, the configuration files are as follows.

===============================================================================
Base layer(example):
0	{VOL Id}
5.0	{VOL frame rate}
0 	{Type of alpha channel to be used 0-RECTANGULAR, 1-BINARY, 2-GREY LEVEL}
0	{Flag to indicate scalable coding: 0 - base layer,1 - enhancement layer}
0	{Ref. layer Id in the case of scalability}
0	{Enhancement type: 0 - whole frame of the base layer, 1 - partial region of the base layer}
-------------------------------------------------------------------------------
In the base layer,
 - (VOL frame rate) = (frame rate of the base layer)
 - Flag to indicate scalable coding is 0.
 - Ref. layer id is same as base layer's vol id. In this example, it is '0'.
 - Enhancement type is ignored( both 0 and 1 is O.K.).
-------------------------------------------------------------------------------
Enhacement layer(example):
1	{VOL Id}
10.0	{VOL frame rate}
1	{Value of M}
0 	{Type of alpha channel to be used 0-RECTANGULAR, 1-BINARY, 2-GREY LEVEL}
1	{Flag to indicate scalable coding: 0 - base layer,1 - enhancement layer}
0	{Flag to indicate scalability types:0-temporal(case0), 1-spatial, 2-both, 3-temporal(case1), 4-temporal(case2)}
0	{Ref. layer Id in the case of scalability}
0	{Enhancement type: 0 - whole frame of the base layer, 1 - partial region of the base layer}
0	{Group of VOPs PERIOD: 0-no GOV, >0 -one GOV every PERIOD}
------------------------------------------------------------------------------
In the enhacement layer,
 - (VOL frame rate) = (base frame rate + enhancement frame rate)
 - (Value of M) is always 1.
 - Flag to indicate scalable coding is 1.
 - Ref. layer id is same as base layer vol id. In this example, it is '0'.
 - Since GOV header is not supported in an enhancement layer, GOV period 0
   should set to be zero.
===============================================================================

In This TPS version, following 3 types and 3 cases are supported.

 - Type0(Whole region of the base layer is enhanced.) and rectangular VOPs.
         Base layer (rectangular VOPs) + Enhacement layer(rectangular VOPs)
         Background composition is not performed.

    In the base layer,
     - Type of alpha channel is 0.

    In the enhacement layer,
     - Type of alpha channel is 0.
     - Enhancement type is 0;

 - Type1(Partial region of the base layer is enhanced.)
         Base layer (rectangular VOPs) + Enhacement layer(arbitrary VOPs)
         Background composition is performed.

    In the base layer,
     - Type of alpha channel is 0.

    In the enhacement layer,
     - Type of alpha channel is 1 or 2.
     - Enhancement type is 1;

 - Type2(Whole region of the base layer is enhanced.) and arbitrary VOPs.
         Base layer (arbitrary VOPs) + Enhacement layer(arbitrary VOPs)
         Background composition is not performed.

    In the base layer,
     - Type of alpha channel is 1 or 2.

    In the enhacement layer,
     - Type of alpha channel is 1 or 2.
     - Enhancement type is 0;

 - Case0(I and P-VOP are encoded/decoded in base layer and enhance layer.
         B-Vop is not allowed.)

    Enhance layer    P   P   P   P   P ...
    Base layer     I   P   P   P   P ...

    In the enhacement layer,
     - (Flag to indicate scalability types) is 0.

       0	{Flag to indicate scalability types:0-temporal(case0),
		 1-spatial, 2-both, 3-temporal(case1), 4-temporal(case2)}

 - Case1(I and P-VOP are encoded/decoded in base layer. B-Vop is encoded/
         decoded in enhance layer. B-Vop is not allowed in base layer.)

    Enhance layer    B B   B B   B B ...
    Base layer     I     P     P     P ...

    In the enhacement layer,
     - (Flag to indicate scalability types) is 3.

       3	{Flag to indicate scalability types:0-temporal(case0),
		 1-spatial, 2-both, 3-temporal(case1), 4-temporal(case2)}

 - Case2(I, P and B-VOP are encoded/decoded in base layer. P and B-Vop is
         encoded/decoded in enhance layer.)

    Enhance layer    P   B   B   B   B   B ...
    Base layer     I   B   P   B   P   B   P ...

    In the enhacement layer,
     - (Flag to indicate scalability types) is 4.

       4	{Flag to indicate scalability types:0-temporal(case0),
		 1-spatial, 2-both, 3-temporal(case1), 4-temporal(case2)}

=========
Limitations 
=========
- In the current version, 
    b)error-resilience 
    c)sprite
  are not supported in the enhancement layer.

- Rate control algorithm for the enhancement layer may not work well, since the
  frame rate in the config. file is the one for (base + enhancement).

- In Type 1(enhancement type = 1), the backward shape and the forward shape in
  the enhancement layer is coded as an Binary-shape-only mode.

- About output files:
a)encoder
  The composited display image whose name is specified in the control file is
  written only when the VOP has a content.

b)decoder
 - The base layer decoder writes the reconstructed image in an output file
   every time. When the VOP doesn't have a content, a black image is written.

 - The enhancement layer decoder writes the reconstructed image in an output
   file only when the VOP has a content.

3.3.7 THE MOTION VECTOR FILE FORMAT

The encoder can read, write or ignore the motion vector file.  The purpose of
the motion vector file is to compute the full-pel motion vectors (with respect
to the original reference picture) once, then reuse this information on
subsequent encodings of the same sequence.  Use of motion vector file with
CCIR 601 size video with a typical configuration of 2 consecutive B-VOPs and
a search radius of 31 full pels per frame away from the anchor picture will
reduce the execution time by more than a factor of 15!

The only parameters which cannot be changed between calculation and use of
the motion vector information are (1) the distance between I-VOPs, (2) the
distance between anchor VOPs.  The motion estimation radius per frame away
from reference cannot be decreased between the calculation of the MV file and
its use.  The length of the sequence to be encode (frames) can be reduced,
although it must end on an anchor VOP of the MV file.

The format of the MV data is an ASCII text file with one line of data per
macroblock.  The pictures are delimited by a separate line which begins with
"Pic".  The format of the data is different for P-VOPs and B-VOPs (I-VOPs do
not appear in the MV file).  All motion vector components are in half-pel
units in frame coordinates.

For P-VOPs, there are 21 integers per macroblock line:
	 1)	Horizontal macroblock coordinate
	 2)	Vertical macroblock coordinate
	 3)	Inter flag (0 for Intra, 1 for Predicted)
	 4)	16x16 MV horiz coordinate
	 5)	16x16 MV vert coordinate
	 6)	Field MV horiz coordinate for current=top, reference=top
	 7)	Field MV vert coordinate for current=top, reference=top
	 8)	Field MV horiz coordinate for current=top, reference=bottom
	 9)	Field MV vert coordinate for current=top, reference=bottom
	10)	Field MV horiz coordinate for current=bottom, reference=top
	11)	Field MV vert coordinate for current=bottom, reference=top
	12)	Field MV horiz coordinate for current=bottom, reference=bottom
	13)	Field MV vert coordinate for current=bottom, reference=bottom
	14)	Upper left 8x8 block MV horiz coordinate
	15)	Upper left 8x8 block MV vert coordinate
	16)	Upper right 8x8 block MV horiz coordinate
	17)	Upper right 8x8 block MV vert coordinate
	18)	Lower left 8x8 block MV horiz coordinate
	19)	Lower left 8x8 block MV vert coordinate
	20)	Lower right 8x8 block MV horiz coordinate
	21)	Lower right 8x8 block MV vert coordinate

For B-VOPs, there are 20 integers per macroblock line:
	 1)	16x16 forward MV horiz coordinate
	 2)	16x16 forward MV vert coordinate
	 3)	Forward fld MV horiz coord for current=top, reference=top
	 4)	Forward fld MV vert coord for current=top, reference=top
	 5)	Forward fld MV horiz coord for current=top, reference=bottom
	 6)	Forward fld MV vert coord for current=top, reference=bottom
	 7)	Forward fld MV horiz coord for current=bottom, reference=top
	 8)	Forward fld MV vert coord for current=bottom, reference=top
	 9)	Forward fld MV horiz coord for current=bottom, reference=bottom
	10)	Forward fld MV vert coord for current=bottom, reference=bottom
	11)	16x16 backward MV horiz coordinate
	12)	16x16 backward MV vert coordinate
	13)	Backward fld MV horiz coord for current=top, reference=top
	14)	Backward fld MV vert coord for current=top, reference=top
	15)	Backward fld MV horiz coord for current=top, reference=bottom
	16)	Backward fld MV vert coord for current=top, reference=bottom
	17)	Backward fld MV horiz coord for current=bottom, reference=top
	18)	Backward fld MV vert coord for current=bottom, reference=top
	19)	Backward fld MV horiz coord for current=bottom, reference=bottom
	20)	Backward fld MV vert coord for current=bottom, reference=bottom

At present, the motion vector file is designed for interlaced video, however
there are straight forward extensions possible for rectangular progressive
and arbitrarily shaped objects.

3.3.8 INTERLACED VIDEO NOTES

The MPEG-4 version 1 CD defines interlaced video only for rectangular VOPs
and in single layer coding.  At the present time, error resilience is not
implemented.

3.4 STATISTICS FILE

As the software runs an output statistics file (default name is
'encode.dat') is generated which contains bit statistics and PSNRs for
each VOP, and the entire session.

If NLSSTATS is defined, the format of the statistics file is modified to
include more information.  The new format is designed to be both (somewhat)
human readable and to be easily processed by utilities such as 'awk' and
'perl' for statisical analysis.  An excerpt of the new format is show below.

I[  0]      : time=0.000 video_obj_id=1 layer_id=1 quant=12
I[  0] flds : Y=377908 C=31495 cbpy=3036 mcbpc=5085 ilace=1350
I[  0] mblk : inter=0 inter4v=0 intra=1350 field=0 skip=0 fldDCT=1005
I[  0] bits : shape+texture=421634 vop=54 total=421688
I[  0] PSNR : Y=34.544292 U=38.830009 V=39.400028
 
P[  3]      : time=100.000 video_obj_id=1 layer_id=1 quant=12
P[  3] flds : Y=97740 C=4235 MVs=30800 cbpy=5398 mcbpc=3169 ilace=4279
P[  3] mblk : inter=338 inter4v=81 intra=0 field=931 skip=0 fldDCT=668
P[  3] bits : shape=0 motion=0 texture=5 vop=58 total=147848
P[  3] PSNR : Y=32.436272 U=38.453773 V=38.602283
  
B[  1]      : time=33.333 video_obj_id=1 layer_id=1 quant=18
B[  1] flds : Y=25799 C=1082 MVs=17794 hdr=2667 3164 3480 744 ilace=2472 fldDCT=280
B[  1] mblk : bmt=454 214 171 120 134 95 140 nmv=839 349 140 field=369 skip=11 11 748
B[  1] bits : shape+motion+texture=57204 vop=60 total=57264
B[  1] PSNR : Y=31.953812 U=38.182400 V=38.671486

The first letter is the VOP type followed by the coded frame number in brackets.
The first line containg time, object layer and (initial) quantizer are self
explanitory.  The 'flds' line contains the number of bit of the current VOP
used for luminance DCT coefficients (Y), chrominance DCTR coefficients (C),
motion vectors (MV) and different fields in the MB header.  The 'mblk' line
gives the number of macroblocks in various categories (not all mutually
exclusive.  For example in B-VOPs, the 'bmt=' category specifies the number
of MB which are direct, 16x16 forward, 16x16 backward, 16x16 bidirectional,
field forward, field backward, and field bidirectional respectively.  The
meaning of the 'PSNR' line is obvious.


======================================================================

4. RUNNING THE DECODER SOFTWARE --------------------------------------

======================================================================

The decoder is controlled by a control file whose name has to be
passed as runtime argument. The control file contains the name(s) of
the bitstream file(s), of the output sequence files and some other
parameters. Below you will find an exemplary control file which you
should modify by your needs.


--- Exemplary control file for the decoder ---

n                               {Number of VOs to decode}
m                               {Number of layers for VO 1}
bits.VO1L1                      {Filename for bitstream of VO1 Layer 1}
...
bits.VO1Lm                      {Filename for bitstream of VO1 Layer m}
...
m                               {Number of layers for VO n}
bits.VOnL1                      {Filename for bitstream of VOn Layer 1}
...
bits.VOnLm                      {Filename for bitstream of VOn Layer m}
display.y                       {Name of output file for Y sequence}
display.u                       {Name of output file for U sequence}
display.v                       {Name of output file for V sequence}
display.a                       {Name of output file for A sequence}
fr                              {Frame rate of output file in frame/s}
width                           {Width of display frame}
height                          {Height of display frame}
n				{post-filter type: 0 - disabled, 1 - deblock, 
        			 2 - deringing, 3 - combined}
n				{Bits per pixel for display (8 for normal video)}
n	 			{random_access_start_time}

n		               {Number of VTCs to decode}
VTC_0.bits 		       {Filename of the  bitstream for VTC 0}
REC_0.yuv		       {Filename of the reconstructed for VTC 0}
width_0			       {Width of the output bounded box for shape decoding VTC 0}
height_0		       {Height of the output bounded box for shape decoding VTC 0}
bit_rate_0		       {target bitrate VTC0}
n_spa_0    		       {target_spatial_level VTC0}
n_snr_0			       {target_snr_level VTC0}
...				... 
VTC_n.bits 		       {Filename of the  bitstream for VTC n}
REC_n.yuv		       {Filename of the reconstructed for VTC n}
width_n			       {Width of the output bounded box for shape decoding VTC n}
height_n		       {Height of the output bounded box for shape decoding VTC n}
bit_rate_n		       {target bitrate VTC n}
n_spa_n    		       {target_spatial_level VTC n}
n_snr_n			       {target_snr_level VTC n}



--- End of file ---

Please note that the values m and n have to be replaced by the real
values you need. Also the dots (...) are only for generality and
should be removed.

Please note further the following remarks with respect to the decoder:

 
  - the output alpha file is no longer written; however, the name in the
    control file is still required.

  - the size of the final display frame for the output sequence
    has to be set by the user in the control file, since there
    is no session size anymore.



======================================================================

5. NOTES/KNOWN BUGS/PROBLEMS -----------------------------------------

======================================================================

Summary of Operation -----------------------------------------------

- In the case of coding with B-VOPs, frame_rates, M and start frames
  are suggested to set the same among the different VOs, otherwise the  
  compositor cannot work well.

Problems ------------------------------------------------------------   

- If operating the encoder with binary alpha maps, it is assumed that
  the two signal levels are 255 and 0. Incorrect operation will be
  caused by using binary alpha maps with levels 1 and 0.

- The software has not been tested for grayscale shape coding, and 
  will probably not work well for this mode.

- There are problems with decoding bitstreams containing VO's with
  different frame rates. This is being worked on, and a solution will 
  be made available when this problem has been solved.


======================================================================

6. USING TRACES IN THE DECODER ---------------------------------------

======================================================================

First of all, IT WORKS ONLY IN DEBUG MODE (compile with DBG=1) !

The output will be the file <bitstream_filename>.dec_log, i.e. there is
one trace output file for each decoded VOL bitstream.

You can choose the part of the code you want to trace. The trace mode is
then the same for all VOLs of the different VOs. This setting is done in 
the upper part of the file "vm_dec_main.c" (line 144 ff.), and in 
vm_common/include/vm_common_defs.h (parameter MB_trace_thres), after changing  
the settings the decoder has to be recompiled. Note that MB_trace_thres 
determines the traced number of macroblocks within a VOP, i.e.

with 

#define MB_trace_thres N

only the first N non-transparent macroblocks in the VOP  are traced

The data to be traced has been subdivided into three different levels; for
each of these levels, a further subdivision of the output data can be
chosen. Here are the levels and the respective data:

	/* Default trace level settings */

	/* Level 1: high level syntax read from bitstream */
	#define TRACE_LEVEL_1		1
	#define	TRACE_VO_HEADER		1
	#define	TRACE_VOL_HEADER	1
	#define	TRACE_VOP_HEADER	1

	/* Level 2: MB data read from bitstream */
	#define TRACE_LEVEL_2		1
	#define	TRACE_MB_HEADER		1
	#define	TRACE_MB_MOTION		1
	#define	TRACE_MB_SHAPE		1
	#define	TRACE_MB_TEXTURE        1

	/* Level 3: MB data after certain processing steps (IQ, IDCT ...) */
	#define TRACE_LEVEL_3			1
	#define	TRACE_MB_SDATA		        1
	#define	TRACE_MB_TDATA_BEFORE_IQ	1
	#define	TRACE_MB_TDATA_AFTER_IQ		1
	#define	TRACE_MB_TDATA_AFTER_IDCT	1
	#define	TRACE_MB_TDATA_PREDICTED	1
	#define	TRACE_MB_TDATA_RECONSTRUCTED	1

If the definition is set to "1", then the tracing for that data is enabled, 
otherwise it is disabled. Please note that the tracing of all the data for 
one specific level can be disabled by just setting the variable TRACE_LEVEL_N
for that level to "0". 

The so set trace values are default and are used for each VOP of all VOLs.
However, it is possible to get a "full trace" (i.e. all the above variables
set to "1") for certain VOPs. This is controlled by the following settings 
(also in "vm_dec_main.c", line 144 ff.):

	/* Control for full-trace-VOPs */
	#define FULL_TRACE_START	3
	#define FULL_TRACE_END		9
	#define FULL_TRACE_PERIOD	2

Here, a full trace is printed for each Nth VOP between FULL_TRACE_START
and FULL_TRACE_END, where N=FULL_TRACE_PERIOD. For the above given example, 
a full trace would be printed out for the VOPs 3, 5, 7 and 9. Further, if
FULL_TRACE_PERIOD<0, a full trace is given for *all* VOPs (NOTE: this can
lead to VERY BIG trace files!!!). Finally, setting FULL_TRACE_PERIOD=0 gives
no full trace at all, i.e. for all VOPs the default values are used. 

Now, some examples for the output of all the data will be given:


#define	TRACE_VO_HEADER 1 will lead to the following
************************************************************************
vo_start_code           : 0x8         :      000000000000000000000001000
vo_id                   : 0x0         :                            00000
************************************************************************


#define	TRACE_VOL_HEADER 1 will lead to the following
************************************************************************
vol_start_code          : 0x12        :     0000000000000000000000010010
vol_id                  : 0x0         :                             0000
is_object_layer_identifi: 0x0         :                                0
vol_control_parameters  : 0x0         :                                0
vol_shape               : 0x1         :                               01
time_increment_resolutio: 10          :                  000000000001010
fixed_vop_rate          : 0x0         :                                0
OBMC_disable            : 0           :                                0
vol_sprite_usage        : 0x0         :                                0
not_8_bit               : NO          :                                0
vol_quant_type          : YES         :                                1
load_intra_quant_mat    : NO          :                                0
load_nonintra_quant_mat : YES         :                                1
nonintra_quant_mat      : 16          :                         00010000
nonintra_quant_mat      : 0           :                         00000000
complexity_estimation_di: YES         :                                1
error_resilient_disable : YES         :                                1
scalability             : NO          :                                0
random_accessible_vol   : NO          :                                0
************************************************************************


#define	TRACE_VOP_HEADER 1 will lead to the following
************************************************************************
vop_start_code          : 0x1b6       : 00000000000000000000000110110110
vop_prediction_type     : 0x0         :                               00
modulo_time_base        : NO          :                                0
marker_bit              : YES         :                                1
vop_time_increment      : 0           :                             0000
marker_bit              : YES         :                                1
vop_coded               : 1           :                                1
vop_width               : 32          :                    0000000100000
marker_bit              : YES         :                                1
vop_height              : 48          :                    0000000110000
marker_bit              : YES         :                                1
vop_horizontal_mc_spatia: 0           :                    0000000000000
marker_bit              : YES         :                                1
vop_vertical_mc_spatial_: 86          :                    0000001010110
change_CR_disable       : NO          :                                0
vop_constant_alpha      : NO          :                                0
intra_dc_vlc_thr        : 0x0         :                              000
interlaced              : 0x0         :                                0
vop_quant               : 10          :                            01010
************************************************************************


#define	TRACE_MB_HEADER	1 will lead to the following
************************************************************************
>>>   Decoding Macroblock 40 ........- Combined Motion/Shape/Text
first_shape_code        : 0x1         :                                1
----------
NO DCT FLAG             : YES         :                                1

>>>   Decoding Macroblock 41 ........- Combined Motion/Shape/Text
first_shape_code        : 0x1         :                                1
----------
NO DCT FLAG             : NO          :                                0
MCBPC                   : -           :                                1
CBPY2                   : -           :                              110
----------

etc.
************************************************************************


#define	TRACE_MB_MOTION	1 will lead to the following
************************************************************************
----------
motion_code             : 0x1         :                                1
motion_code             : 0x1         :                                1
  >> mvx: 0
  >> mvy: 0
----------

etc.
************************************************************************


#define	TRACE_MB_SHAPE	1 will lead to the following
************************************************************************
ST                      : 0x1         :                                1
BAC                     : 0x1         :                                1
BAC                     : 0x0         :                                0
BAC                     : 0x0         :                                0
BAC                     : 0x1         :                                1
BAC                     : 0x1         :                                1
BAC                     : 0x0         :                                0

etc.
************************************************************************


#define	TRACE_MB_TEXTURE  1 will lead to the following
************************************************************************
----------
VLC 3D                  : 0x1bff      :                          1111111
LAST                    : -           :                                0
RUN                     : 29          :                           011101
LEVEL                   : 255         :                         11111111
VLC 3D                  : 0x10c1      :                         11000001
SIGN                    : 0x1         :                                1
  >> Run:  12 -- Level: -1  
----------

etc.
************************************************************************


#define	TRACE_MB_SDATA 1 will lead to the following
************************************************************************
MB_shape_data:
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0

  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255  255    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255    0    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255    0    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255    0    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255    0    0    0    0    0
  255  255  255  255  255  255  255  255     255  255  255    0    0    0    0    0

etc.
************************************************************************


#define	TRACE_MB_TDATA_BEFORE_IQ 1 will lead to the following
************************************************************************
MB_tdata_before_IQ:
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0

    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0   -1   -1
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0

etc.
************************************************************************


#define	TRACE_MB_TDATA_AFTER_IQ	1 will lead to the following
************************************************************************
MB_tdata_after_IQ:
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0

    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0  -29  -29
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0
    0    0    0    0    0    0    0    0       0    0    0    0    0    0    0    0

etc.
************************************************************************


#define	TRACE_MB_TDATA_AFTER_IDCT 1 will lead to the following
************************************************************************
MB_tdata_after_IDCT:
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -
    0    0    0    0    0    0    0    0       0    0    0    0    -    -    -    -

    0    0    0    0    0    0    0    0      -4   11  -12   10    -    -    -    -
    0    0    0    0    0    0    0    0      -3    9  -11    8    -    -    -    -
    0    0    0    0    0    0    0    0      -2    6   -7    5    -    -    -    -
    0    0    0    0    0    0    0    0      -1    2   -2    -    -    -    -    -
    0    0    0    0    0    0    0    0       1   -2    2    -    -    -    -    -
    0    0    0    0    0    0    0    0       2   -6    7    -    -    -    -    -
    0    0    0    0    0    0    0    0       3   -9   11    -    -    -    -    -
    0    0    0    0    0    0    0    0       4  -11   12    -    -    -    -    -

etc.
************************************************************************


#define	TRACE_MB_TDATA_PREDICTED 1 will lead to the following
************************************************************************
____MB0_____ at (0,0)
MB_tdata_predicted:
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81

   66   66   66   66   66   66   66   66      66   66   66   66   66   66   66   71
   42   42   42   42   42   42   42   42      42   42   42   42   42   42   42   47
   38   38   38   38   38   38   38   38      38   38   38   38   38   38   38   38
   46   46   46   46   46   46   46   46      46   46   46   46   46   46   46   43
   41   41   41   41   41   41   41   41      41   41   41   41   41   41   41   44
   41   41   41   41   41   41   41   41      41   41   41   41   41   41   41   43
   45   45   45   45   45   45   45   45      45   45   45   45   45   45   45   43
   41   41   41   41   41   41   41   41      41   41   41   41   41   41   41   42

etc.
************************************************************************


#define	TRACE_MB_TDATA_RECONSTRUCTED 1 will lead to the following
************************************************************************
____MB0_____ at (0,0)
MB_tdata_reconstructed:
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81
   81   81   81   81   81   81   81   81      81   81   81   81   81   81   81   81

   66   66   66   66   66   66   66   66      66   66   66   66   66   66   66   71
   42   42   42   42   42   42   42   42      42   42   42   42   42   42   42   47
   38   38   38   38   38   38   38   38      38   38   38   38   38   38   38   38
   46   46   46   46   46   46   46   46      46   46   46   46   46   46   46   43
   41   41   41   41   41   41   41   41      41   41   41   41   41   41   41   44
   41   41   41   41   41   41   41   41      41   41   41   41   41   41   41   43
   45   45   45   45   45   45   45   45      45   45   45   45   45   45   45   43
   41   41   41   41   41   41   41   41      41   41   41   41   41   41   41   42

************************************************************************


AGAIN, BE CAREFULL: FULL TRACE GENERATES HUGE FILES (~1 MByte for 3 VOPs!!!) 

======================================================================

7. USING RANDOM ACCESS         ---------------------------------------

======================================================================

We have now included the possibility to start decoding of a video session at a selectable time.
Selection of time to start decoding is done by adding a {random_access_start_time } field in the decoder control file. The value of random_access_start_time is given in milliseconds, and the decoder starts decoding and writing of frames to disk at the closest possible frame #. 
The default value of random_access_start_time is 0, meaning that decoding and display will start as normal.

The random access functionality relies on GOV information
GOV information may be different for varios VO's.
When decoding a bitstream, decoding of each VO will start at nearest proceeding GOV + I_VOP relative to random_access_start_time. Writing of frames to disk will start at nearest frame to random_access_start_time. 

Note: For random access to work properly, a GOV should always be followed by an I-VOP.

======================================================================

8. Using software for bitstream exchange   ---------------------------

======================================================================

Attention should be paid to the following points when using the MoMuSys
software for bitstream exchange. 

To produce FCD compliant bitstreams, please use the compiler detective
"_WD_MODE_".

To vary the quantization scale within a VOP, please use the compiler detective
"_PSEDUO_RATE_CONTROL_".

For the binary shape coding only, please set shape type to 3 in the config. file.

======================================================================

9. Basic flags used in Makefile

======================================================================

-D_DEBUG_		: 	Allows the debuging
-D_PSEDUO_RATE_CONTROL_	: 	Allows the assigment of a different 
				quantizer step for different blocks in a VOP
-D_RAWIO_		: 	Allows the use of raw image formats
-D_WD_MODE_		: 	Allows the compilation of the WD package
-D__STDC__		: 	needed by ANSI C and "classical" C
-DNLSSTATS              :       Alternate statistics file format
-D_RC_UPM2_             :       2. RC model for INTERNAL USE ONLY (see note
                                in chapter 3.3.2.2 point 2.2.) Selection of 
                                models)



 flags for WAVELET coding


-D_WRITE_COEFF_MAP_	 :	creates dump files for checking of lossless part of 
 				encoding/decoding. Quantized value, state, type info 
				is written out. Also, does some unnecessary type marking 
				to get maps to match.
 
-D_WRITE_ORV_MAP_	:	creates dump files which have the original wavelet coeffs
  				at encoder and reconstructed coeff at decoder.
 
-D_NEW_DC_QUANT_	: 	will use the same quantizer as used by the AC coeffs.
 				This option is not currently compatible with the MPEG-4 
				bitstream syntax.
 
-D_NEW_IQUANT_VAL_	:	will use (q-1)/2 as the inverse quant value within
 				the quantization level. The old one is q/2.
 
-D_FORCE_ALL_ZERO_	:	forces makes the AC coefficients all be zero at encoder.
 
-D_DECODER_		:	create decoder only.
 
-D_SHAPE_		:	enable shape_adaptive DWT
 


defaults settings: D_NEW_IQUANT_VAL_ and D_SHAPE_
