* ************************************************************************ *
       Copyright (C) 2001 by the University of Maryland, College Park

		Laboratory for Language and Media Processing
		   Institute for Advanced Computer Studies
	       University of Maryland, College Park, MD  20742

   email: lamp@cfar.umd.edu               http: lamp.cfar.umd.edu
 * ************************************************************************ *

 ViPER - A Video Performance Evaluation Resource
   A tool in three parts:
     gt  - A Tool for Ground Truthing
     pe  - A Utility for Evaluation
     viz - A Set of Scripts to View the Results

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

 Installing ViPER

NOTE: You may have to configure your installation of perl. See the README
in the viz directory for more details.

1. Download the package from:
     http://lamp.cfar.umd.edu/media/research/viper/
   Untar the package. It will create a "viper" directory. Alternatively,
   check out the viper package from LAMP's CVS repository, if you have
   access. If you wish to have more detailed instructions, look in the
   viper/common/docs/ directory, which contains a set of manuals in
   Microsoft Word files.

2. From the "viper" directory that is created, run the command:
     perl config.pl
   If you wish to remake the jar files from the sources, instead run:
     make all
   The "make all" command will only be necessary if you check the code out
   from CVS, as the jar files are not stored in the repository.

3. If you are using csh or a derivative, run the command:
     source viper.config
   If you are using a Bourne shell derivative, use the command:
     . viper-cfg.sh
   This will configure your envrionment to run the program.

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

 Using ViPER

  viper-gt [truth file] [media file]
    This command starts the Ground Truth software. It requires a recent (>
1.3) version of java to be installed on the computer. This tool allows the
user  to mark up a media file with information about its content. This
information is stored in a truth file, normally with the extension .gtf.
    The truth file must (currently) be created in a text editor or be one 
of the templates included with the software. The media file must be either 
an mpeg or a .info file, which may list several images or movies.
    For more information, see the viper/gt/doc directory, or the
appropriate Word document in the viper/common/docs directory.


  viper-pe <various options>
    "viper-pe" is a command line utility which will evaluate how well a set 
of "result" media metadata against a set of "truth" metadata, presumably 
generated by viper-gt or a similar tool. It generates two forms of output:
the default, human readable format, and the perl-readable raw format.
    This command takes a large number of arguments. For information on it, 
see the viper/pe/docs directory, or the manual in the viper/common/docs
directory

  xml2gtf
  gtf2xml
    These programs convert between the older, line based truth format and 
the newer, xml based format. As not all of the tools fully support the new
format, these CLI tools may act as pipes between programs.


  makeGraph.pl [graph information file]
    Part of the viz package, makeGraph can convert a set of .raw output 
files from viper-pe into a set of colorful .gif charts.
    For more information, see the viper/viz/docs directory.

  RunEvaluation.pl
    The RunEvaluation.pl script combines the ability to compare several 
different results with different parameters using viper-pe with the 
ability to create coherent graphs using makeGraph, without having to 
know the specifics of the command lines of either tool.
    For more information, see the viper/scripts/docs directory.


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

License Issues

This software relies on several outside packages. These are the Xalan
XML parser, under the Apache Software Liscense; Java Advanced Imaging,
under a Sun license; and junit, under the IBM Public License. For more
information, see the LICENSES file in the common/lib directory. As to
ViPER's code, the code in the viper.* namespaces is licensed under the
GPL, and the code in the mpeg1.* namespaces is licensed under the LGPL.