viper.comparison
Class ViperPE

java.lang.Object
  viper.comparison.ViperPE

public class ViperPE

extends java.lang.Object

This class offers a function to compare two Descriptor data files.

Running the software

java viper.comparison.ViperPE -options
Options include:

• -pr properties file : set the properties file. This specifies defaults that can be overriden in the command line. (See below)
• -b file name root : the default name to check for all file types
• -g truth file : the name of the ground truth file
• -r results file: the name of the results file
• -epf evaluation parameters file : the name of the file with equivalencies, evaluations, and filters
• -gc ground truth configuration file : if the truth config is in a separate file, then set this to that file
• -rc results data configuration file : if the results config is in a seperate file, then set this to that file
• -o verbose output file : set this to '-' to direct to System.out
• -raw raw data output file : where to output the raw format data
• -L# level of matching : change the level specified in the properties file, eg L1, L2, etc.
• -Pproperty value : override a specific property-value pair from the properties file

Properties File Format

• File Configuration section
  • gtconfig_file: where the truth config is stored. Not necessary if the same as gt_file
  • gt_file: where the truth data (Target set) is stored.
  • resultsconfig_file: where the results config info is stored. Not necessary if the same as results_file.
  • results_file: where the results data (Candidate set) is stored.
  • epf_file: name of the Evaluation Parameters file. It contains which attributes to evaluate, typewise metrics and tolerances, and equivalencies between the result and truth naming conventions.
  • output_file: where to print the verbose output. Defaults to System out.
  • raw_file: Where to print the raw output. Defaults to no raw output.
  • base: the base file name, same as -b option
• Formatting
  • verbose: true or false - prints out distance coefficients
  • attrib_width: the width of the data to print in the output file
• Descriptor-wide Metric Configuration
  • level: what level to take the comparison.
    • 1 = Detection: the objects overlap temporally better than some threshold see range_tol, rmetric_default
    • 2 = Localization performs detection using only the frames whose attributes meet necessary thresholds
    • 3 = Statistical Comparison the average/median/max/min, depending on which was selected, meets a certain threshold
  • target_match: How to crop the set of possibles at the end - object evaluation only.
    • ALL, DEFAULT = No cropping
    • SINGLE-GREEDY = Only allow one Candidate for each Target
    • SINGLE-BEST = Allow only one Candidate for each Target and vice-versa
    • MULTI-BEST = Allow multiple Candidates to be mapped to a single Target using composition
  • range_metric: the distance metric to use for the frame overlap test
    • dice = 1- Dice coefficient (2 & intersection / sum of candidate and target)
    • overlap = 1 - amount of candidate on target / size of target
    • E = equality (0 if equal, 1 if not)
  • range_tol: comparisons that indicate the distance between two descriptor's frame span is greater than this will be dropped.
  • level3_metric: the statistic to use for statistical comparison. either minimum, maximum, median, or average
  • level3_tol: the tolerance to use on the generated distance statistic Anything less than or equal to this will still count as a valid comparison.
• Attribute Metric and Tolerance Configuration
  • svalue_metric: The default metric for comparison of svalues.
    • L = Levenshtein (edit) distance
    • H = Hamming (Strings of different length are counted as failures)
    • E = equality (either 0 or 1)
  • bvalue_tol: tolerance for bvalue attributes
  • dvalue_tol: tolerance for dvalue attributes
  • fvalue_tol: tolerance for fvalue attributes
  • svalue_tol: tolerance for svalue attributes
  • point_tol: tolerance for point attributes
  • circle_tol: tolerance for circle attributes
  • bbox_tol: tolerance for bbox attributes
  • obox_tol: tolerance for obox attributes
  • lvalue_tol: tolerance for lvalue attributes

Author:

David Doermann, David Mihalcik, Felix Suhenko

Constructor Summary

ViperPE()
Processes a properties file into ViperPE internal state variables.

Method Summary

static com.jrefinery.chart.JFreeChart	createChart(java.lang.String name, com.jrefinery.data.Dataset data) Creates a new chart for the given data set
static java.util.Map	getOptions(java.lang.String[] args) Parses the options into a hashmap.
static void	main(java.lang.String[] args) The main program block of the command line version of the Ground Truth File Comparison software.
static java.io.PrintWriter	openFileForWriting(java.lang.String fileName) Opens the file with the specified name for writing.
static DescriptorConfigs	parseDescriptorConfig(java.lang.String configFileName, java.lang.String dataFileName) Reads in config information from a gtf file.
static DescriptorData	parseDescriptorData(DescriptorConfigs cfgs, java.lang.String dataFileName, EvaluationParameters epf, java.io.PrintWriter log) Reads in data information from a gtf file.
static void	printChartPng(java.lang.String fileName, com.jrefinery.chart.JFreeChart chart, int width, int height) Saves the given chart a PNG file.
static void	printChartSvg(java.lang.String fileName, com.jrefinery.chart.JFreeChart chart, int width, int height) Prints out the results as an svg chart.
static void	printGraphs(java.util.Map data, java.lang.String prefix, java.lang.String suffix) Prints out all the graphs for the given set of data.
static void	printUsage() Print usage.
static void	printUsage(int error, java.lang.Throwable trace) Prints out some of the basic flags.
static void	printVersion() Prints out version information.
void	run() Runs the application.
void	setProperties(java.util.Properties props) Sets the properties associated with this run of the performance evaluator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ViperPE

public ViperPE()

Processes a properties file into ViperPE internal state variables.

Method Detail

printUsage

public static void printUsage()

Print usage.

printUsage

public static void printUsage(int error,
                              java.lang.Throwable trace)

Prints out some of the basic flags. For more, see the javadoc or the README.

Parameters:

error - the error type

trace - the throwable associated with the error

printVersion

public static void printVersion()

Prints out version information. It does not include any RCS variables.

getOptions

public static java.util.Map getOptions(java.lang.String[] args)

Parses the options into a hashmap.

Parameters:

args - the command line arguments

Returns:

the argument map, or null if the arguments are malformed. (It also prints out usage in the latter case.)

main

public static void main(java.lang.String[] args)

The main program block of the command line version of the Ground Truth File Comparison software.

Parameters:

args - The command line arguments are specified at the top. For the properties, see the package listing.

setProperties

public void setProperties(java.util.Properties props)
                   throws BadDataException,
                          ImproperMetricException

Sets the properties associated with this run of the performance evaluator.

Parameters:

props - the properties

Throws:

BadDataException - if some of the properties contain errors in syntax of viper data

ImproperMetricException - if some of the properties contain references to unknowm metrics, or if they initialize the metrics incorrectly

openFileForWriting

public static java.io.PrintWriter openFileForWriting(java.lang.String fileName)

Opens the file with the specified name for writing. Overwrites the file if it exists. Silently fails if there is an I/O exception by setting to null. If filename is null, an empty string, or an invalid file, this returns null. If the string is a dash, "-", it returns System.out.

Parameters:

fileName - The file to open for writing.

Returns:

A new PrintWriter or null

parseDescriptorConfig

public static DescriptorConfigs parseDescriptorConfig(java.lang.String configFileName,
                                                      java.lang.String dataFileName)
                                               throws java.io.IOException,
                                                      BadDataException

Reads in config information from a gtf file.

Parameters:

configFileName - File name of the config file - only applicable to old file format, which can take multiple files and glue them together

dataFileName - The data file. If old format, will use config file if is not null, and this otherwise. If xml format, only uses data file.

Returns:

the parsed configuration information

Throws:

BadDataException - if the parseConfig or addDesConfig method throws it, or if an xml file is given two file names.

java.io.IOException - if there is an io exception while parsing

parseDescriptorData

public static DescriptorData parseDescriptorData(DescriptorConfigs cfgs,
                                                 java.lang.String dataFileName,
                                                 EvaluationParameters epf,
                                                 java.io.PrintWriter log)
                                          throws BadDataException,
                                                 java.io.IOException

Reads in data information from a gtf file.

Parameters:

cfgs - Configs, presumably from parseDescriptorConfig

dataFileName - The data file to parse.

epf - used to run the input filter

log - recipient of the various error and notification messsages

Returns:

the data taken from the given file that meets the filters

Throws:

BadDataException - if the parseConfig or addDesConfig method throws it, or if an xml file is given two file names.

java.io.IOException - if there is an io exception while parsing

run

public void run()

Runs the application.

printGraphs

public static void printGraphs(java.util.Map data,
                               java.lang.String prefix,
                               java.lang.String suffix)

Prints out all the graphs for the given set of data.

Parameters:

data - the data sets

prefix - the prefix for each chart filename

suffix - the suffix for each chart filename

printChartSvg

public static void printChartSvg(java.lang.String fileName,
                                 com.jrefinery.chart.JFreeChart chart,
                                 int width,
                                 int height)
                          throws java.io.IOException

Prints out the results as an svg chart.

Parameters:

fileName - the file to save the results

chart - the chart

width - the width to give the output file

height - the height for the output file

Throws:

java.io.IOException

printChartPng

public static void printChartPng(java.lang.String fileName,
                                 com.jrefinery.chart.JFreeChart chart,
                                 int width,
                                 int height)
                          throws java.io.IOException

Saves the given chart a PNG file.

Parameters:

fileName - the file to save to

chart - the chart to save

width - the width of the chart

height - the height of the chart

Throws:

java.io.IOException

createChart

public static com.jrefinery.chart.JFreeChart createChart(java.lang.String name,
                                                         com.jrefinery.data.Dataset data)

Creates a new chart for the given data set

Parameters:

name - the name of the chart

data - the data set

Returns:

the new chart