Diagnostic Instrumentation for Dirac
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Chris Bowley (chris.bowley@rd.bbc.co.uk) 18-08-04


1. Overview
   ~~~~~~~~

This tool provides pictorial output of motion estimation and mode decisions. 
The U and V layers of each frame are used to display information overlaid over the
original Y layer. The following information may be viewed:

        - motion vectors
        - SAD block values
        - macroblock splitting mode
        - prediction mode

Where appropriate, the reference frame can be chosen.

Each overlay includes frame number and reference number display along with a colour
legend (which can be turned off). It is also possible to select to view information over
a grey background.

Further documentation on this tool and examples can be found at:

        http://www.bbc.co.uk/rd/projects/dirac/documentation.shtml


2. Command-line syntax and options
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The diagnostic utility can be found in util/instrumentation and executed using the following 
command:

        dirac_instrumentation [input_file] [output_file] ... -<flag> -<flag val> ...

The following flags select the overlay:

        -motion_colour (default)        motion vectors represented using a colour wheel
        -motion_arrows                  motion vectors represented using arrows
        -motion_colour_arrows           motion vectors represented using arrows and colour size
        -sad                            sum of absolute difference
        -split_mode                     macroblock splitting mode
        -pred_mode                      prediction mode

The following options are available:

        -ref n                          Select which reference frame is used
        -start n                        First frame to be included in output
        -stop n                         Last frame to be included in output
        -no_bg                          Use mid-grey background
        -no_legend                      Do not display colour legend
        -clip                           Value at which output is clipped (motion vectors
                                        and sad overlays only)
        -buffer n                       Size of internal buffer for motion data
        -verbose                        Output during process

Example: For colour motion vector arrows with a clip value of 50, using reference 2 guides:

        util/instrumentation/dirac_instrumentation ~/pictures/in ~/pictures/out -motion_colour_arrows -clip 50 -ref 2


3. Operation
   ~~~~~~~~~

   3.1 Motion Data Transfer
       ~~~~~~~~~~~~~~~~~~~~

This diagnostic tool requires input of instrumentation data in the form of a text file.
Currently, only motion data is written out by the encoder to a text file, in the following format:

        [frame:n}>mo_comp

        no. of refs  ref1  <ref2>  mv block width  mv block height  mv array width
         mv array height  mb array width  mb array height

        Splitting mode
        Common reference mode
        Macroblock costs
        Prediction mode
        Intra costs
        Bi-prediction costs
        Component DC values

        Ref 1 motion vectors
        Ref 1 sad

        <Ref 2 motion vectors>
        <Ref 2 sad>

        <Ref 3 motion vectors>
        .
        .

Intra coded frames have no associated motion data and are identified by the header:

        [frame:n]>intra

Note: not all data is currently available as instrumentation.

Data is output by the encoder to a file at the same location as the output file:

        [output_file].imt


   3.2 Internal Motion Data Buffer
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~

Output of motion data is in encoded frame order. The diagnostic tool therefore requires
a buffer in order to minimise time spent searching the input file. The input file is read
once and no reverse movement through the file is made, the buffer must therefore be
large enough to hold frame motion data before being overwritten. The default size is 50
frames which should be sufficient for most picture sequences. In order to reduce the
memory footprint, the buffer size may be reduced.

Buffer failure (overwriting frame data before it is used) results in the user being
advised and the program exiting.

Another way in which the memory footprint may be reduced is to select a particular section
of the sequence for viewing using the -start and -stop parameters.