viper.comparison
Class Comparison

java.lang.Object
  viper.comparison.Comparison

All Implemented Interfaces:

java.lang.Cloneable

public class Comparison

extends java.lang.Object

implements java.lang.Cloneable

This class represents the differences between two Descriptors.

Field Summary

static int	COMPLETE Indicates that the match is finished, meaning, it has made it through the matching.
static int	DETECTED Indicates that the frame ranges overlap within the desired tolerances.
static int	LOCALIZED Indicates that the measured attributes are similar enough on enough frames.
static int	MATCHED Indicates that there exists some compatability, if only in frame range, between the descriptors.
static int	STARTED Indicates that the two descriptors are compatable, but that no testing has been performed.
static int	STATISTICED Indicates that the desired distance statistics, when computed on the shared frames, are within requested tolerances.
static int	UNCOMPARABLE Indicates that the two descriptors are of incompatable type.

Constructor Summary

Comparison()
Creates a new empty comparison.

Comparison(Descriptor target, Descriptor candidate, Equivalencies map)
This constructor takes in the type of Descriptor to cr DSD - Initial value is -2, if the are not the same category, -1 if they are.

Method Summary

java.lang.Object	clone() Creates a copy of the Comparison, but not of the Descriptors.
double	compareTo(java.lang.Object o) Sorts comparisons in order of quality.
boolean	detect(CanonicalFileDescriptor cfd, EvaluationParameters.ScopeRules epf) Compares the framespans of the target and candidate descriptors.
double	getDistance() Returns the distance metric calculated in the match() function during level 0 testing.
double	getDistanceFor(java.lang.String name) Returns the distance measure of the specified attribute name.
java.lang.String	getDistances(EvaluationParameters.ScopeRules epf) Gets a formatted string indicating how far apart the target and candidate are in terms of frame span and each measured attribute.
int	getFilterLevel() Determine if the comparison is still active, or at what level it was removed from the pool of possible matches.
int	getLevel() Get the level of the comparison, e.g.
static java.lang.String	levelTitle(int levelType) Gets a formatted string corresponding to the given comparison level
boolean	localize(CanonicalFileDescriptor cfd, EvaluationParameters.ScopeRules epf) This performs localization.
boolean	match(EvaluationParameters.ScopeRules epf) Moves the comparison from STARTED to MATCHED, if possible.
java.lang.String	matchingPercentage() Returns a String containing the percentage.
void	printCandidate(java.io.PrintWriter output, java.lang.String padding, EvaluationParameters.ScopeRules epf) Prints, in verbose format, information about the candidate and how close it matches the target.
void	reset(Descriptor target, Descriptor candidate, Equivalencies map) Resets the comparison between two descriptors to UNCOMPARABLE or STARTED.
void	setFilterLevel(int i) Sets the level the comparison was marked as invalid.
protected void	setLevel(int new_level) Allows to set the level to whatever is passed in.
protected void	setPointers(Descriptor target, Descriptor candidate) Sets the Descriptor pointers.
boolean	statistical(EvaluationParameters.ScopeRules epf) Performs Statistical, or Level 3, of the object evaluation type.
static boolean	takeComparisonToThisLevel(Comparison C, int level, CanonicalFileDescriptor cfd, EvaluationParameters.ScopeRules epf) This takes a new comparison to the specified level.
java.lang.String	toString() Returns a String representation of the Descriptor.

Methods inherited from class java.lang.Object

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

Field Detail

UNCOMPARABLE

public static final int UNCOMPARABLE

Indicates that the two descriptors are of incompatable type.

See Also:

Constant Field Values

STARTED

public static final int STARTED

Indicates that the two descriptors are compatable, but that no testing has been performed.

See Also:

Constant Field Values

MATCHED

public static final int MATCHED

Indicates that there exists some compatability, if only in frame range, between the descriptors.

See Also:

Constant Field Values

DETECTED

public static final int DETECTED

Indicates that the frame ranges overlap within the desired tolerances.

See Also:

Constant Field Values

LOCALIZED

public static final int LOCALIZED

Indicates that the measured attributes are similar enough on enough frames.

See Also:

Constant Field Values

STATISTICED

public static final int STATISTICED

Indicates that the desired distance statistics, when computed on the shared frames, are within requested tolerances.

See Also:

Constant Field Values

COMPLETE

public static final int COMPLETE

Indicates that the match is finished, meaning, it has made it through the matching.

See Also:

Constant Field Values

Constructor Detail

Comparison

public Comparison(Descriptor target,
                  Descriptor candidate,
                  Equivalencies map)

This constructor takes in the type of Descriptor to cr DSD - Initial value is -2, if the are not the same category, -1 if they are.

Parameters:

target - The target, or ground truth, descriptor.

candidate - The candidate, or results file, descriptor.

map - the name equivalencies

Comparison

public Comparison()

Creates a new empty comparison. Call reset to get it going.

Method Detail

getLevel

public int getLevel()

Get the level of the comparison, e.g. LOCALIZED.

Returns:

the level the comparison has made it to

getFilterLevel

public int getFilterLevel()

Determine if the comparison is still active, or at what level it was removed from the pool of possible matches.

Returns:

the level it was removed.

setFilterLevel

public void setFilterLevel(int i)

Sets the level the comparison was marked as invalid.

Parameters:

i - the new removal level

levelTitle

public static java.lang.String levelTitle(int levelType)

Gets a formatted string corresponding to the given comparison level

Parameters:

levelType - the comparison level, e.g. MATCHED

Returns:

a right-justified level title

reset

public void reset(Descriptor target,
                  Descriptor candidate,
                  Equivalencies map)

Resets the comparison between two descriptors to UNCOMPARABLE or STARTED.

Parameters:

target - the target descriptor

candidate - the candidate descriptor

map - the ontology mapping

clone

public java.lang.Object clone()

Creates a copy of the Comparison, but not of the Descriptors. If you are going to alter the Descriptors, make certain to copy them and call setPointers to change them.

Returns:

a copy of the comparison object

setPointers

protected void setPointers(Descriptor target,
                           Descriptor candidate)

Sets the Descriptor pointers. Necessary for cloning, unfortunately.

Parameters:

target - the target for the comparison

candidate - the candidate for the comparison

compareTo

public double compareTo(java.lang.Object o)
                 throws BadDataException

Sorts comparisons in order of quality. That is, better matches are sorted higher than poor matches. FIXME: This is currently only partialy implemented.

Parameters:

o - - the Comparison to compare this with

Returns:

0 if the distances are equal. Less than o or greater gives - and +, respectively. For example, a LOCALIZED comparison is greater than a DETECTED comparison, and a LOCALIZED comparison with 18 valid frames is greater than a LOCALIZED comparison with 17 valid frames.

Throws:

java.lang.ClassCastException

BadDataException

takeComparisonToThisLevel

public static boolean takeComparisonToThisLevel(Comparison C,
                                                int level,
                                                CanonicalFileDescriptor cfd,
                                                EvaluationParameters.ScopeRules epf)

This takes a new comparison to the specified level.

Parameters:

C - the comparison to promote

level - the level to take it to, e.g. LOCALIZED

cfd - the source media descriptor

epf - the scoping rules

Returns:

true if the comparison made it to the level

toString

public java.lang.String toString()

Returns a String representation of the Descriptor. Contains EOL characters.

Returns:

a String containing the category, name, ID number, span, and all scoped Attributes

matchingPercentage

public java.lang.String matchingPercentage()

Returns a String containing the percentage.

Returns:

" Match is xx%\n" or null if the percentage has not been calculated

match

public boolean match(EvaluationParameters.ScopeRules epf)

Moves the comparison from STARTED to MATCHED, if possible.

Parameters:

epf - the rules and metrics for evaluation

Returns:

if the comparison counts as a match

detect

public boolean detect(CanonicalFileDescriptor cfd,
                      EvaluationParameters.ScopeRules epf)
               throws java.lang.IllegalStateException

Compares the framespans of the target and candidate descriptors.

Parameters:

cfd - required information about the enclosing file, like its frame span or frame rate

epf - rules and metrics for performing the comparison

Returns:

true if the comparison counts as a detection

Throws:

java.lang.IllegalStateException - if this comparison isn't at the level MATCHED

localize

public boolean localize(CanonicalFileDescriptor cfd,
                        EvaluationParameters.ScopeRules epf)

This performs localization. Level 2 - match frame by frame attributes. After, distance is set to the dice coefficient between the target frames and all the candidate frames that survive localization.

Parameters:

cfd - the containing media

epf - the scoping rules

Returns:

true if the comparison is localized

Throws:

java.lang.IllegalStateException - if trying to localize a comparison that is not marked as DETECTED

statistical

public boolean statistical(EvaluationParameters.ScopeRules epf)

Performs Statistical, or Level 3, of the object evaluation type. "statistics" vector 0: Average 1: Minimum 2: Median 3: Maximum This routine needs to be modified to threshold based on the average or maximum of each attribute according to level3_metric Scores is one per attribute byFrame is one per frame

Parameters:

epf - the scoping rules

Returns:

true if the comparison has made it to the level successfully

Throws:

java.lang.IllegalStateException - if the comparison isn't localized

getDistances

public java.lang.String getDistances(EvaluationParameters.ScopeRules epf)

Gets a formatted string indicating how far apart the target and candidate are in terms of frame span and each measured attribute.

Parameters:

epf - the rules for evaluation

Returns:

a raw-formatted sequence of distances

printCandidate

public void printCandidate(java.io.PrintWriter output,
                           java.lang.String padding,
                           EvaluationParameters.ScopeRules epf)

Prints, in verbose format, information about the candidate and how close it matches the target.

Parameters:

output - The stream to accept the text.

padding - A prefix to put before each line (useful for formatting)

epf - the scoping rules

getDistance

public double getDistance()

Returns the distance metric calculated in the match() function during level 0 testing. This will primarily used for level 3 and level 4.

Returns:

the distance measurement (how far from original this is). 1 = bad, 0 = good

setLevel

protected void setLevel(int new_level)

Allows to set the level to whatever is passed in. Mostly used only for Level 3 comparissons since all the calculations are done in the CompMatrix class.

Parameters:

new_level - the int value of the level to which you want to set this level to.

getDistanceFor

public double getDistanceFor(java.lang.String name)

Returns the distance measure of the specified attribute name.

Parameters:

name - the Attribute name that you requesting a distance measure for

Returns:

the double value that is the distance. Returns 0.0 as default.