sourceafis.simple
Class AfisEngine

java.lang.Object
  extended by sourceafis.simple.AfisEngine

public class AfisEngine
extends Object

Methods and settings of SourceAFIS fingerprint matching engine. This class is an entry point to core SourceAFIS functionality. After setting relevant properties (notably threshold), application can call one of the three main methods (extract, verify, identify) to perform template extraction and fingerprint matching.

AfisEngine objects are thread-safe, i.e. synchronized. AfisEngine is a lightweight object, but application is encouraged to keep only one global AfisEngine instance anyway. Every AfisEngine method utilizes multiple cores automatically. Applications that wish to execute several methods of AfisEngine in parallel should create multiple AfisEngine objects, perhaps one per thread.


Constructor Summary
AfisEngine()
          Create new SourceAFIS engine.
 
Method Summary
 void extract(Person person)
          Extracts fingerprint template(s) to be used during matching (not implemented in java).
 int getDpi()
          Gets DPI of images submitted for template extraction.
 int getMinMatches()
          Gets minimum number of fingerprints that must match in order for a whole person to match.
 float getThreshold()
          Gets similarity score threshold for making match/non-match decisions.
 Iterable<Person> identify(Person probe, Iterable<Person> candidates)
          Compares probe Person to all candidate Persons and returns the most similar candidates.
 void setDpi(int value)
          Sets DPI of images submitted for template extraction.
 void setMinMatches(int value)
          Sets minimum number of fingerprints that must match in order for a whole person to match.
 void setThreshold(float value)
          Sets similarity score threshold for making match/non-match decisions.
 float verify(Person probe, Person candidate)
          Computes similarity score between two Persons.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AfisEngine

public AfisEngine()
Create new SourceAFIS engine.

Method Detail

getDpi

public int getDpi()
Gets DPI of images submitted for template extraction. See setDpi for explanation of DPI setting. This method just returns current DPI setting.

Returns:
current setting of DPI assumed for all images
See Also:
setDpi, extract

setDpi

public void setDpi(int value)
Sets DPI of images submitted for template extraction. Default is 500.

DPI of common optical fingerprint readers is 500. For other types of readers as well as for high-resolution readers, you might need to change this property to reflect capabilities of your reader. This value is used only during template extraction. Matching is not affected, because extraction process rescales all templates to 500dpi internally.

Setting DPI causes extractor to adjust its parameters to the DPI. It therefore helps with accuracy. Correct DPI also allows matching of fingerprints coming from different readers. When matching children's fingerprints, it is sometimes useful to fool the extractor with lower DPI setting to deal with the tiny ridges on fingers of children.

Parameters:
value - new DPI assumed to apply to all processed fingerprint images
See Also:
getDpi, extract

getThreshold

public float getThreshold()
Gets similarity score threshold for making match/non-match decisions. See setThreshold for explanation of similarity threshold. This method just returns current threshold value.

Returns:
current similarity threshold value
See Also:
setThreshold, verify, identify

setThreshold

public void setThreshold(float value)
Sets similarity score threshold for making match/non-match decisions. Default value is rather arbitrarily set to 25.

Matching algorithm produces similarity score which is a measure of similarity between two fingerprints. Applications however need clear match/non-match decisions. Threshold is used to turn similarity score into match/non-match decision. Similarity score at or above the threshold is considered match. Lower score is considered non-match. This property is used by verify and identify methods to make match decisions.

Appropriate threshold level is application-specific. Application developer must adjust this property to reflect differences in fingerprint readers, population, and application requirements. Start with default threshold. If there are too many false accepts (SourceAFIS reports match for fingerprints from two different people), increase the threshold. If there are too many false rejects (SourceAFIS reports non-match for two fingerprints of the same person), decrease the threshold. Every application eventually arrives at some reasonable balance between FAR (false accept ratio) and FRR (false reject ratio).

Parameters:
value - new value of the similarity threshold
See Also:
getThreshold, verify, identify

getMinMatches

public int getMinMatches()
Gets minimum number of fingerprints that must match in order for a whole person to match. See setMinMatches for explanation. This method just returns current minimum number of matching fingerprints.

Returns:
current minimum number of matching fingerprints
See Also:
setMinMatches, verify, identify

setMinMatches

public void setMinMatches(int value)
Sets minimum number of fingerprints that must match in order for a whole person to match. Default value is 1 (person matches if any of its fingerprints matches).

When there are multiple Fingerprints per Person, SourceAFIS compares every probe Fingerprint to every candidate Fingerprint and takes the best match, the one with highest similarity score. This behavior improves FRR (false reject rate), because low similarity scores caused by damaged fingerprints are ignored. This happens when MinMatches is 1 (default).

When MinMatches is 2 or higher, SourceAFIS compares every probe Fingerprint to every candidate Fingerprint and records score for every comparison. It then sorts collected partial scores in descending order and picks score that is on position specified by MinMatches property, e.g. 2nd score if MinMatches is 2, 3rd score if MinMatches is 3, etc. When combined with threshold, this property essentially specifies how many partial scores must be above threshold in order for the whole Person to match. As a special case, when there are too few partial scores (less than value of MinMatches), SourceAFIS picks the lowest score.

MinMatches is useful in some rare cases where there is significant risk that some fingerprint might match randomly with high score due to a broken template or due to some rarely occuring matcher flaw. In these cases, MinMatches might improve FAR. This is discouraged practice though. Application developers seeking ways to improve FAR would do much better to increase threshold. Threshold can be safely raised to levels where FAR is essentially zero as far as fingerprints are of good quality.

Parameters:
value - new minimum number of matching fingerprints
See Also:
getMinMatches, verify, identify

extract

public void extract(Person person)
Extracts fingerprint template(s) to be used during matching (not implemented in java).

The extract method takes Fingerprint.image from every Fingerprint in Person parameter and constructs fingerprint template that it stores in template property of the respective Fingerprint. This step must be performed before the Person is used in verify or identify method, because matching is done on fingerprint templates, not on fingerprint images.

Fingerprint image can be discarded after extraction, but it is recommended to keep it in case the template needs to be regenerated due to SourceAFIS upgrade or other reason.

Parameters:
person - Person object to use for template extraction
See Also:
setDpi

verify

public float verify(Person probe,
                    Person candidate)
Computes similarity score between two Persons. The verify method compares two Persons, Fingerprint by Fingerprint, and returns floating-point similarity score that indicates degree of similarity between the two Persons. If this score falls below threshold, verify method returns zero.

Persons passed to this method must have valid template for every Fingerprint, i.e. they must have passed through extract method.

Parameters:
probe - first of the two persons to compare
candidate - second of the two persons to compare
Returns:
similarity score indicating similarity between the two persons or 0 if there is no match
See Also:
setThreshold, identify

identify

public Iterable<Person> identify(Person probe,
                                 Iterable<Person> candidates)
Compares probe Person to all candidate Persons and returns the most similar candidates. Calling identify is conceptually identical to calling verify in a loop except that identify is significantly faster than loop of verify calls. If there is no candidate with score at or above threshold, identify returns empty collection.

Most applications need only the best match, which can be obtained by calling Iterables.getFirst method from Guava library. Pass the returned collection as its first parameter and null as its second parameter. Matching score for every returned Person can be obtained by calling verify on probe Person and the matching Person.

Persons passed to this method must have valid template for every Fingerprint, i.e. they must have passed through extract method.

Parameters:
probe - person to look up in the collection
candidates - collection of persons that will be searched
Returns:
All matching Person objects in the collection or an empty collection if there is no match. Results are sorted by score in descending order. If you need only one best match, call Iterables.getFirst method from Guava library. Pass the returned collection as its first parameter and null as its second parameter.
See Also:
setThreshold, verify