viper.comparison
Class CompMatrix

java.lang.Object
  viper.comparison.CompMatrix

All Implemented Interfaces:

java.lang.Cloneable

public class CompMatrix

extends java.lang.Object

implements java.lang.Cloneable

A collection of Descriptor Objects that supports various operations on them, such as comparison between two DescriptorLists, collection of statistics, reading and printing from files, and various others.

Version:

%I%, %G%

Author:

Felix Sukhenko, David Mihalcik, David Doermann

Constructor Summary

CompMatrix(CompMatrix old, java.util.BitSet targetMask, java.util.BitSet candidateMask)
Creates a new comparison matrix as a subset of an existing matrix.

CompMatrix(DescriptorList targets, DescriptorList candidates, CanonicalFileDescriptor cfd, EvaluationParameters.ScopeRules scope, java.io.PrintWriter log)
Creates a new structure for the comparison of two DescriptorLists.

CompMatrix(DescriptorList targets, DescriptorList candidates, CanonicalFileDescriptor cfd, EvaluationParameters.ScopeRules scope, java.io.PrintWriter log, Revealer ticker)
Create a new descriptor comparison matrix.

Method Summary

void	addPRInfo(Descriptor currConfigDesc, viper.comparison.PrecisionRecall counts) Adds the descriptor precision and recall infromation to the running total.
boolean	bringToLevel(int type, EvaluationParameters.ScopeRules scope) Brings the comparisons up to the given level.
boolean	caresAboutCandidate(Descriptor d) Determines if the candidate should be ignored.
boolean	caresAboutTarget(Descriptor d) Determines if the target should be ignored.
java.lang.Object	clone() Creates a copy of the CompMatrix.
boolean	detect() Comparison.DETECTED (Detection) matching:
viper.comparison.Surreal	getCompleteSum() Gets the minimax sum of all distances.
EvaluationParameters.ScopeRules	getScopeRules() Gets the evaluation rule set currently associated with this set of comparisons.
boolean	initializeMatrix(EvaluationParameters.ScopeRules scope, int level, Revealer ticker) Called after setting the descriptors and various other things, this goes through the matrix of comparisons and brings them all up to the specified level of analysis.
boolean	isContinuable() If it is possible to upgrade the level of the matrix.
boolean	localize() Comparison.LOCALIZED (Localization) matching:
boolean	match() ------------------------------------------------------------------------ Comparison.MATCHED (Simple Name) matching: Adds candidates from a list of possibles to each of the Descriptor objects in the list.
void	printCandidates(java.io.PrintWriter output, java.io.PrintWriter raw, java.util.Collection target_configs) Prints out the candidates that are close to each target, if any haven't been filtered.
void	printCurrentFalse(java.io.PrintWriter output, java.io.PrintWriter raw, java.util.Collection targetConfigs) Print out the current estimate of false candidate descriptors.
void	printCurrentFM(java.io.PrintWriter output, java.io.PrintWriter raw, java.util.Collection targetConfigs) Print the most recent Descriptors to be false or missed.
void	printCurrentMissed(java.io.PrintWriter output, java.io.PrintWriter raw, java.util.Collection targetConfigs) Prints out all of the descriptors that were "missed" in the last pass.
void	printPR(java.io.PrintWriter output, java.io.PrintWriter raw, DescriptorConfigs targetConfigs) Deprecated. CompMatrices should only be accessed through CompEvaluators, which have their own printPR function.
void	printROCInfo(java.io.PrintWriter output, java.io.PrintWriter raw, DescriptorConfigs target_configs) Prints out ROC information.
void	removeDuplicates(int match) Comparison.COMPLETE matching: Removes the duplicates in the same rows by finding the minimum distance and promoting those targets to the next level.
void	removeOld() Remove the detritus comparisons (the ones that aren't still active).
boolean	statistical(double tolerance) Comparison.STATISTICED (Statistical) matching: Match subject to constraints on overall attribute match A given candidate will only be considered if its average, minimum or median of the frame distance computations is above a given tolearnce.

Methods inherited from class java.lang.Object

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

Constructor Detail

CompMatrix

public CompMatrix(DescriptorList targets,
                  DescriptorList candidates,
                  CanonicalFileDescriptor cfd,
                  EvaluationParameters.ScopeRules scope,
                  java.io.PrintWriter log)

Creates a new structure for the comparison of two DescriptorLists. The CompMatrix is simply a two dimensional array of Comparison objects. Each entry in the array corresponds to a Target/Candidate pair. At this point, a Comparison object is constructed for each entry in the matrix. As the Comparison constructor specifies, those that are in the same category start with level set to Comparison.STARTED, and those that are not in the same category have level set to Comparison.UNCOMPARABLE.

Parameters:

targets - the vector containing the target descriptors

candidates - the vector containing the candidate descriptors

cfd - the file descriptor describing te media file; needed for some metrics, e.g. pixel metrics

scope - attribute scope and equivalency rules

log - the logger to accept error messages

CompMatrix

public CompMatrix(DescriptorList targets,
                  DescriptorList candidates,
                  CanonicalFileDescriptor cfd,
                  EvaluationParameters.ScopeRules scope,
                  java.io.PrintWriter log,
                  Revealer ticker)

Create a new descriptor comparison matrix.

Parameters:

targets - the target data set. This is the truth data.

candidates - the candidate data set

cfd - basic file metadata

scope - rules about evaluation

log - error log

ticker - ui for indicating how long things are taking

CompMatrix

public CompMatrix(CompMatrix old,
                  java.util.BitSet targetMask,
                  java.util.BitSet candidateMask)

Creates a new comparison matrix as a subset of an existing matrix.

Parameters:

old - the matrix to subset

targetMask - the target descriptors to use. If the kth bit is set, the kth target descriptor will be used in the new matrix.

candidateMask - the candidate descriptors to use. If the kth bit is set, the kth candidate descriptor will be used in the new matrix.

Method Detail

getScopeRules

public EvaluationParameters.ScopeRules getScopeRules()

Gets the evaluation rule set currently associated with this set of comparisons.

Returns:

the scope rules for this set of comparisons

caresAboutTarget

public boolean caresAboutTarget(Descriptor d)

Determines if the target should be ignored.

Parameters:

d - the target descriptor

Returns:

true if the target is not worth the time

caresAboutCandidate

public boolean caresAboutCandidate(Descriptor d)

Determines if the candidate should be ignored.

Parameters:

d - the candidate descriptor

Returns:

true if the candidate is not worth the time

initializeMatrix

public boolean initializeMatrix(EvaluationParameters.ScopeRules scope,
                                int level,
                                Revealer ticker)

Called after setting the descriptors and various other things, this goes through the matrix of comparisons and brings them all up to the specified level of analysis.

Parameters:

scope - The scope rules to use during analysis.

level - What evaluation level to use.

ticker - Ticker to tick off time marks on.

Returns:

true if some element of the CompMatrix qualifies as a match at the specified level.

clone

public java.lang.Object clone()

Creates a copy of the CompMatrix.

Returns:

a deep copy of the matrix

bringToLevel

public boolean bringToLevel(int type,
                            EvaluationParameters.ScopeRules scope)

Brings the comparisons up to the given level.

Parameters:

type - the level to go to

scope - the scoping rules

Returns:

if a comparison or more survived

match

public boolean match()

------------------------------------------------------------------------ Comparison.MATCHED (Simple Name) matching: Adds candidates from a list of possibles to each of the Descriptor objects in the list. Initially, we do a simple match that produces a list of correspondences. Here we are processing only level Comparison.STARTED

Returns:

if there are any remaining edges in the comparison graph after the basic matching

See Also:

Comparison.match(EvaluationParameters.ScopeRules)

detect

public boolean detect()

Comparison.DETECTED (Detection) matching:

Returns:

if there are any remaining edges in the comparison graph after the detection matching

See Also:

Comparison.detect(CanonicalFileDescriptor, EvaluationParameters.ScopeRules)

localize

public boolean localize()

Comparison.LOCALIZED (Localization) matching:

Returns:

if there are any remaining edges in the comparison graph after the localization

See Also:

Comparison.localize(CanonicalFileDescriptor, EvaluationParameters.ScopeRules)

statistical

public boolean statistical(double tolerance)

Comparison.STATISTICED (Statistical) matching: Match subject to constraints on overall attribute match A given candidate will only be considered if its average, minimum or median of the frame distance computations is above a given tolearnce. What this means, is that for any pair which meets the Comparison.MATCHED level criteria, we compute the average, minimum and median distances across all matching frames. If that average, minimum or median meeting the tolerance, then it is considered a match. In some sence, this should be performed in place of level II, instead of after it.

Parameters:

tolerance - the threshold to allow the candidate to still be considered viable. Currently ignored.

Returns:

if there are any remaining edges in the comparison graph after the statistical matching

See Also:

Comparison.statistical(EvaluationParameters.ScopeRules)

isContinuable

public boolean isContinuable()

If it is possible to upgrade the level of the matrix.

Returns:

getCompleteSum

public viper.comparison.Surreal getCompleteSum()

Gets the minimax sum of all distances.

Returns:

the sum of all distances

removeDuplicates

public void removeDuplicates(int match)

Comparison.COMPLETE matching: Removes the duplicates in the same rows by finding the minimum distance and promoting those targets to the next level.

Parameters:

match - the method for removing duplicates

removeOld

public void removeOld()

Remove the detritus comparisons (the ones that aren't still active).

printCurrentFM

public void printCurrentFM(java.io.PrintWriter output,
                           java.io.PrintWriter raw,
                           java.util.Collection targetConfigs)

Print the most recent Descriptors to be false or missed. This goes through and checks each Target and Candidate pair. If there exists a comparison, then each its Target and its Candidate still count as a detection. If a Candidate or Target has no matching surviving Comparison objects, then it is false or missed, respectively. This function only prints the false and missed that were discovered in the most recent level. ie, if this has been Statisticed, then it will only display those who where still considered detctions by Localization.

Parameters:

output - the human readable, verbose stream

raw - the machine readable, terse stream

targetConfigs - the configs to print out

printCurrentFalse

public void printCurrentFalse(java.io.PrintWriter output,
                              java.io.PrintWriter raw,
                              java.util.Collection targetConfigs)

Print out the current estimate of false candidate descriptors.

Parameters:

output - the human-readable output

raw - the raw formatted output

targetConfigs - the target descriptors to print out

printCurrentMissed

public void printCurrentMissed(java.io.PrintWriter output,
                               java.io.PrintWriter raw,
                               java.util.Collection targetConfigs)

Prints out all of the descriptors that were "missed" in the last pass. This basically means invoking goodComp on all of the Comparison s in the matrix and outputing the targets that are not in any good comparison, are not longDeadComp, and are visible.

Parameters:

output - the human readable, verbose stream

raw - the machine readable, terse stream

targetConfigs - the configs to print out

printCandidates

public void printCandidates(java.io.PrintWriter output,
                            java.io.PrintWriter raw,
                            java.util.Collection target_configs)

Prints out the candidates that are close to each target, if any haven't been filtered. At first, all candidates match all target objects in the same class, and fewer and fewer are matched, until only one, or a sequence, matches. It also checks against the output filters, and doesn't print out any descriptors that don't pass through.

Parameters:

output - the PrintWriter for outputting the information, eg System.out. May be set to NULL if no raw output requested.

raw - the PrintWriter for outputting the information in raw format for postprocessing. May be set to NULL if no raw output requested.

target_configs -

printROCInfo

public void printROCInfo(java.io.PrintWriter output,
                         java.io.PrintWriter raw,
                         DescriptorConfigs target_configs)

Prints out ROC information. This currently doesn't work.

Parameters:

output - the human-readable output

raw - the raw formatted output

target_configs - the target descriptors to print out

addPRInfo

public void addPRInfo(Descriptor currConfigDesc,
                      viper.comparison.PrecisionRecall counts)

Adds the descriptor precision and recall infromation to the running total.

Parameters:

currConfigDesc - the descriptor type to add

counts - the running total

printPR

public void printPR(java.io.PrintWriter output,
                    java.io.PrintWriter raw,
                    DescriptorConfigs targetConfigs)

Deprecated. CompMatrices should only be accessed through CompEvaluators, which have their own printPR function.

Print out precision and recall.

Parameters:

output - the PrintWriter for outputting the information, eg System.out. May be set to NULL if no raw output requested.

raw - the PrintWriter for outputting the information in raw format for postprocessing. May be set to NULL if no raw output requested.

targetConfigs - the target descriptor configs for the comparisons to print