Native template format

SourceAFIS » Algorithm » Template

This page describes the format of serialized fingerprint templates produced by SourceAFIS. SourceAFIS has its own native template format described below. SourceAFIS also supports several foreign template formats as implemented in FingerprintIO library, but their use is discouraged.

Why templates?

When SourceAFIS compares fingerprints, it really compares their high-level biometric features, specifically minutiae (ridge endings and bifurcations). Every minutia is characterized by its position, type (ending or bifurcation), and direction.

Feature extraction is the process of deriving biometric features from fingerprint image. Feature extraction produces fingerprint template, essentially a data structure encoding biometric features. Template is then fed to SourceAFIS matcher that performs actual fingerprint matching. The reason for this separation is that feature extraction is several orders of magnitude costlier than matching a single pair of templates. Applications should cache the templates whenever they are likely to be used more than once in order to avoid repeating the expensive feature extraction.


Templates are an in-memory data structure. In order to encourage more effective caching, especially when searching large databases of fingerprints, fingerprint template can be serialized and stored persistently. Reloading the template from persistent storage is usually much faster than reconstructing it from fingerprint image.

Template serialization API is part of the core library and it is described in respective tutorial:

Libraries that parse algorithm transparency data can also parse the template:


Although SourceAFIS template format is fairly stable, it does change occasionally. SourceAFIS currently does not try to make templates interchangeable between different SourceAFIS versions.

For that reason, SourceAFIS templates can be used only with the particular version of SourceAFIS that generated them. Attempting to use older templates in newer SourceAFIS may result in exceptions during deserialization or in loss of accuracy during matching.

It is however safe to exchange templates between latest versions of different language ports of SourceAFIS, because they all use the same template format.

Applications should always store and transmit original fingerprint images. Serialized templates should be used only as a local cache and only with SourceAFIS library pinned to a particular version. When SourceAFIS needs to be upgraded, all templates should be re-extracted from fingerprint images.

SourceAFIS supports some foreign template formats, which can be used instead of native SourceAFIS templates, but this is discouraged. For compatibility and long-term storage, fingerprint images are better than any template format. For temporary template caches, native templates provide best performance and accuracy.


The following visualization can be created from data stored in the serialized template. Original fingerprint image is in the background of the visualization, but it is not part of the template.

Endings are shown in blue, bifurcations in green. Line markers indicate minutia direction.

Visualization library allows you to create images like the one above:


SourceAFIS template is serialized as a CBOR-encoded data structure:


  "version": "3.18.1-java",
  "width": 388,
  "height": 374,
  "positionsX": [
    "... skipped 42 items in range 78 to 304 ...",
  "positionsY": [
    "... skipped 42 items in range 16 to 352 ...",
  "directions": [
    "... skipped 42 items in range 0.844 to 6.18 ...",