Algorithm transparency in SourceAFIS

Algorithm transparency in SourceAFIS is an API that lets applications capture all intermediate data structures that are created during feature extraction and matching, including images in various stages of filtering, extracted minutiae and ridges, pairing tree constructed by matcher, and score breakdown. Learning basics of how the algorithm works is recommended before using transparency API.

Why?

The simple API exposed by SourceAFIS is generally an advantage, because the job of SourceAFIS is to abstract away details of fingerprint matching. There are however occasions when seeing what the algorithm is doing is beneficial. Specifically, algorithm transparency can be used to:

• explain how the algorithm reached its decision,
• create rich visualizations of fingerprints and their matches,
• check quality of captured fingerprints,
• use fingerprint features creatively for something other than matching,
• support fingerprint experts in manual matching,
• reconstruct damaged fingerprints in forensics,
• diagnose issues with sensors, outlier populations, and algorithm itself, and
• export data for use in another biometric system.

Transparency data is also used internally to ensure consistency of language ports of SourceAFIS and to perform basic sanity checks in unit tests.

Algorithm transparency is rare in commercial matchers, because it weakens intellectual property protection. SourceAFIS, being fully opensource, doesn't need to hide anything from you. Algorithm transparency is its unique advantage.

Standard API data

Transparency data does not include data that is available in some other way. Specifically, it excludes the original fingerprint image, source byte array during deserialization, the resulting template (which is documented elsewhere), and the final score.

Full log

The simplest way to obtain transparency data is to ask SourceAFIS for a transparency ZIP file. The following example logs data from feature extraction, matcher initialization, and a single match.

FingerprintTemplate candidate = ...;
byte[] probeImage = ...;

try (
    OutputStream stream = new FileOutputStream("transparency.zip");
    FingerprintTransparency transparency = FingerprintTransparency.zip(stream)
) {
    FingerprintTemplate probe = new FingerprintTemplate(
        new FingerprintImage()
            .dpi(500)
            .create(probeImage));
    new FingerprintMatcher()
        .index(probe)
        .match(candidate);
}

See: FingerprintTransparency.zip() (Java)

This will create file transparency.zip populated by numerous CBOR and binary data files. You can customize what gets logged by adding or removing method calls inside the try block.

Zip contents

List of files in the generated transparency.zip is shown below. Files named pairing and score appear multiple times, each containing different minutia pairing. Some of these repeats have been omitted from the list. Click on any file group to learn about its format.

Selective logging

ZIP file might be easy to generate and examine by hand, but most use cases for transparency API require programmatic access to data. While you could save the ZIP file and then load parts of it, it is easier and more performant to define your own FingerprintTransparency implementation like in this example.

// extend class FingerprintTransparency and define take() method
class TransparencyContents extends FingerprintTransparency {
    @Override public void take(String key, String mime, byte[] data) {
        System.out.printf("%,9d B  %-17s %s\n", data.length, mime, key);
    }
}

FingerprintTemplate candidate = ...;
byte[] probeImage = ...;

// use the newly defined logging class to capture data
try (TransparencyContents transparency = new TransparencyContents()) {
    FingerprintTemplate probe = new FingerprintTemplate(
        new FingerprintImage()
            .dpi(500)
            .create(probeImage));
    new FingerprintMatcher()
        .index(probe)
        .match(candidate);
}

See: FingerprintTransparency.take(String,String,byte[]) (Java)

This should result in the following output. You can see the data is more structured. Data is passed to the logger in the same order in which file entries appear in the ZIP file above.

        6 B  text/plain        version
1,306,040 B  application/cbor  decoded-image
1,306,040 B  application/cbor  scaled-image
      371 B  application/cbor  blocks
  167,088 B  application/cbor  histogram
  181,067 B  application/cbor  smoothed-histogram
    5,878 B  application/cbor  contrast
        .           .             .
        .           .             .
        .           .             .
    6,532 B  application/cbor  pairing
      503 B  application/cbor  score
       43 B  application/cbor  pairing
      496 B  application/cbor  score
    8,494 B  application/cbor  pairing
      505 B  application/cbor  score
        1 B  text/plain        best-match

You can also override FingerprintTransparency.accepts(String) to control what information is logged. This lets you access algorithm transparency data with minimal overhead, picking only data you actually need.