Template format

This page describes the format of serialized fingerprint templates produced by SourceAFIS. You probably don't need to know this unless you want to access data stored in the template.

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 by the direction of the corresponding ending or bifurcation.

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 matcher for the actual 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 expensive templates whenever they are likely to be used more than once.

Serialization

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. This page describes the format of serialized templates below.

Compatibility

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 matching or in loss of accuracy during matching.

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 must be re-extracted from fingerprint images.

SourceAFIS has very basic support for importing ISO 19794-2 templates, but use of ISO 19794-2 is discouraged, because ISO is hostile to opensource projects. There is no export functionality for ISO 19794-2 templates, so ISO 19794-2 cannot be used for persistent template caching anyway.

Visualization

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. Sticks attached to minutiae point in the direction of that minutia. Image size corresponds to size stored in JSON.

Format

Serialized SourceAFIS template is a JSON-encoded data structure. Fields width and height describe the size of the input image after it was rescaled to 500dpi. The rest of JSON data is a list of minutiae. Every minutia is described by the following fields:

{
  "width": 388,
  "height": 374,
  "minutiae": [
    {
      "x": 74,
      "y": 136,
      "direction": 1.9513027039072617,
      "type": "ending"
    },
    {
      "x": 80,
      "y": 156,
      "direction": 1.9936502529278375,
      "type": "ending"
    },
    {
      "x": 174,
      "y": 16,
      "direction": 6.134295359570089,
      "type": "bifurcation"
    },
    {
      "x": 142,
      "y": 304,
      "direction": 5.780342096251726,
      "type": "ending"
    },
    {
      "x": 168,
      "y": 196,
      "direction": 4.90978454023457,
      "type": "bifurcation"
    },
    {
      "x": 192,
      "y": 212,
      "direction": 5.092895357497055,
      "type": "ending"
    },
    {
      "x": 208,
      "y": 348,
      "direction": 0.0,
      "type": "ending"
    },
    {
      "x": 224,
      "y": 324,
      "direction": 6.085789747329706,
      "type": "bifurcation"
    },
    {
      "x": 288,
      "y": 124,
      "direction": 1.1479424006619559,
      "type": "bifurcation"
    },
    {
      "x": 304,
      "y": 188,
      "direction": 4.4674103172578254,
      "type": "ending"
    },
    {
      "x": 192,
      "y": 103,
      "direction": 2.4149503129080676,
      "type": "bifurcation"
    },
    {
      "x": 189,
      "y": 125,
      "direction": 1.8157749899217608,
      "type": "bifurcation"
    },
    {
      "x": 237,
      "y": 301,
      "direction": 5.780342096251726,
      "type": "ending"
    },
    {
      "x": 126,
      "y": 198,
      "direction": 5.0490637997714165,
      "type": "ending"
    },
    {
      "x": 216,
      "y": 178,
      "direction": 1.8157749899217608,
      "type": "bifurcation"
    },
    {
      "x": 310,
      "y": 166,
      "direction": 4.607512041654456,
      "type": "bifurcation"
    },
    {
      "x": 201,
      "y": 331,
      "direction": 6.085789747329706,
      "type": "ending"
    },
    {
      "x": 112,
      "y": 288,
      "direction": 5.497787143782138,
      "type": "ending"
    },
    {
      "x": 136,
      "y": 168,
      "direction": 1.9074711461816238,
      "type": "ending"
    },
    {
      "x": 134,
      "y": 284,
      "direction": 5.523422552303815,
      "type": "ending"
    },
    {
      "x": 246,
      "y": 196,
      "direction": 1.7681918866447774,
      "type": "bifurcation"
    },
    {
      "x": 239,
      "y": 234,
      "direction": 5.0490637997714165,
      "type": "ending"
    },
    {
      "x": 254,
      "y": 164,
      "direction": 1.5208379310729538,
      "type": "ending"
    },
    {
      "x": 248,
      "y": 264,
      "direction": 5.21523219131255,
      "type": "bifurcation"
    },
    {
      "x": 245,
      "y": 286,
      "direction": 5.497787143782138,
      "type": "bifurcation"
    },
    {
      "x": 282,
      "y": 244,
      "direction": 1.8622531212727638,
      "type": "bifurcation"
    },
    {
      "x": 177,
      "y": 153,
      "direction": 1.8157749899217608,
      "type": "bifurcation"
    },
    {
      "x": 197,
      "y": 121,
      "direction": 1.5707963267948966,
      "type": "bifurcation"
    },
    {
      "x": 279,
      "y": 69,
      "direction": 0.960070362405688,
      "type": "ending"
    },
    {
      "x": 78,
      "y": 242,
      "direction": 5.275705241876658,
      "type": "ending"
    },
    {
      "x": 140,
      "y": 86,
      "direction": 5.252808480655274,
      "type": "bifurcation"
    },
    {
      "x": 160,
      "y": 174,
      "direction": 1.8157749899217608,
      "type": "bifurcation"
    },
    {
      "x": 168,
      "y": 294,
      "direction": 5.523422552303815,
      "type": "ending"
    },
    {
      "x": 214,
      "y": 74,
      "direction": 0.844153986113171,
      "type": "bifurcation"
    },
    {
      "x": 204,
      "y": 134,
      "direction": 1.5208379310729538,
      "type": "bifurcation"
    },
    {
      "x": 178,
      "y": 314,
      "direction": 5.81953769817878,
      "type": "ending"
    },
    {
      "x": 204,
      "y": 294,
      "direction": 5.639684198386302,
      "type": "ending"
    },
    {
      "x": 238,
      "y": 178,
      "direction": 1.719686274404394,
      "type": "bifurcation"
    },
    {
      "x": 238,
      "y": 202,
      "direction": 4.8120576328758515,
      "type": "ending"
    },
    {
      "x": 248,
      "y": 246,
      "direction": 2.1112158270654806,
      "type": "ending"
    },
    {
      "x": 284,
      "y": 198,
      "direction": 1.4219063791853994,
      "type": "bifurcation"
    },
    {
      "x": 300,
      "y": 134,
      "direction": 4.209545769456828,
      "type": "bifurcation"
    },
    {
      "x": 278,
      "y": 282,
      "direction": 5.412281850103933,
      "type": "ending"
    },
    {
      "x": 302,
      "y": 242,
      "direction": 5.244113047643495,
      "type": "ending"
    },
    {
      "x": 201,
      "y": 23,
      "direction": 3.0419240010986313,
      "type": "ending"
    },
    {
      "x": 194,
      "y": 93,
      "direction": 0.6000502134017536,
      "type": "ending"
    },
    {
      "x": 265,
      "y": 207,
      "direction": 1.6704649792860586,
      "type": "bifurcation"
    }
  ]
}