Forem: Julio Chinchilla

TemplateScorer

Julio Chinchilla — Tue, 16 Sep 2025 04:35:06 +0000

TemplateScorer is a Java algorithm that calculates a quality score for fingerprint templates in ISO/IEC 19794 format.

It combines robust statistics, multivariate analysis, and spatial metrics to produce a single value that reflects the geometric and directional consistency of the minutiae.

Project Repository

You can find the full project here: GitHub - TemplateScorer

Description
Dependencies
Usage
Implementation Details
- Constants
- scoreTemplate(ReadISO19794 template)
- calculateWeights(List raw)
- extractAngles & extractPoints
- calculateRobustCentroid
- validateResolution
- normalizePoints & calculateScaleFactor
- computePCAAlignment
- rotatePoints
- geometricMedian
- covariance
- calculateMahalanobisDistances
- calculateTrimmedMean
- calculateQuadrantScore
- calculateOrientationEntropy

Description

The overall scoring pipeline is:

Read minutiae
Weighting based on quality
Compute robust centroid (geometric median)
Spatial normalization and PCA alignment
Compute Mahalanobis distances
Trimmed mean of distances
Weighting by orientation entropy and spatial distribution (quadrants)

Dependencies

Java 8+
com.gd.bioutils.read.ReadISO19794 (read ISO 19794 templates)
com.gd.bioutils.entity.Minutiae

Usage

import com.gd.bioutils.read.ReadISO19794;
import com.gd.bioutils.scoring.TemplateScorer;

public class Main {
    public static void main(String[] args) {
        ReadISO19794 tpl = ReadISO19794.fromFile("fingerprint.iso19794");
        double score = TemplateScorer.scoreTemplate(tpl);
        System.out.println("Template score: " + score);
    }
}

Implementation Details

Constants

Constant	Description
`DEFAULT_RESOLUTION = 500.0`	Default resolution (ppi) if `xRes` or `yRes` are out of bounds.
`MIN_RESOLUTION_THRESHOLD`	Minimum valid resolution value (100 ppi).
`MAX_RESOLUTION_THRESHOLD`	Maximum valid resolution value (10000 ppi).
`MIN_QUALITY_WEIGHT = 0.01`	Minimum weight for a minutia (if `quality/100` is lower).
`TRIM_RATIO = 0.1`	Fraction of data trimmed when computing mean (10%).
`HIST_BINS = 12`	Number of bins for the angle histogram.
`BETA = 0.5`	Weight factor for orientation entropy.
`MAX_MEDIAN_ITER = 10`	Maximum iterations for geometric median algorithm.
`MEDIAN_TOL = 1e-6`	Convergence tolerance for geometric median.

`scoreTemplate(ReadISO19794 template)`

Processes a complete template:

Extracts minutiae, weights, angles, and coordinates.
Computes robust centroid (geometric median) with geometricMedian¹.
Validates and normalizes resolution (validateResolution).
Centers and normalizes points with scale factor (normalizePoints).
Aligns with PCA (computePCAAlignment)²³.
Rotates points by PCA angle (rotatePoints).
Computes Mahalanobis distances (calculateMahalanobisDistances)⁴.
Gets trimmed mean of distances (calculateTrimmedMean)⁵.
Computes quadrantScore (spatial distribution).
Computes orientationEntropy (angle entropy) (calculateOrientationEntropy)⁶.

Final combination:

score = globalScore * (1 + BETA * orientationEntropy) * quadrantScore

`calculateWeights(List<Minutiae> raw)`

Converts each minutia quality (0–100) into a weight within [MIN_QUALITY_WEIGHT, 1].

`extractAngles` & `extractPoints`

Reads angle and coordinates (x,y) of each minutia.

`calculateRobustCentroid`

Calls geometricMedian(points, weights) to find the point minimizing weighted distance sum¹.

`validateResolution`

Ensures xRes and yRes are within [MIN_RESOLUTION_THRESHOLD, MAX_RESOLUTION_THRESHOLD].

`normalizePoints` & `calculateScaleFactor`

Computes a robust scale factor based on distances to centroid and weights.
Shifts and divides by resolution and scale to standardize.

`computePCAAlignment`

Computes first principal component from covariance matrix²³:

covXX = Σ x² / n; covXY = Σ x·y / n; covYY = Σ y² / n;
angle = 0.5 * atan2(2·covXY, covXX - covYY);

`rotatePoints`

Rotates each point (x,y) by angle:

x' = x·cos – y·sin;  y' = x·sin + y·cos

`geometricMedian`

Implements Weiszfeld’s algorithm (weighted geometric median)¹:

for iter up to MAX_MEDIAN_ITER:
  inv = (d < MEDIAN_TOL) ? 1 : weight / d;
  next = Σ (p·inv) / Σ inv;
  if ‖next–median‖ < MEDIAN_TOL ⇒ break;

`covariance`

Weighted covariance matrix:

c00 = Σ w·dx² / Σw;  c01 = Σ w·dx·dy / Σw;  c11 = Σ w·dy² / Σw;

`calculateMahalanobisDistances`

Inverts covariance matrix and computes d² = [x y]·Cov⁻¹·[x; y]
Distance = √max(d², 0)
Sorts ascendingly.

`calculateTrimmedMean`

Sorts distances
Removes ⌊n·TRIM_RATIO⌋ from both ends
Returns mean of remaining values (robust statistic)⁵.

`calculateQuadrantScore`

Splits bounding box into k×k sub-quadrants (k=3), computes trimmed mean of distances to origin per block, and returns geometric root of their product.

`calculateOrientationEntropy`

Counts angle frequencies into HIST_BINS bins
Computes Shannon entropy⁶: –Σ₁ᵇ pᵢ·log₂(pᵢ)
Normalizes by log₂(HIST_BINS) to obtain [0,1].

References

Weiszfeld, E. (1937). Sur le point pour lequel la somme des distances de n points donnés est minimum. ↩
Pearson, K. (1901). On lines and planes of closest fit to systems of points in space. ↩
Hotelling, H. (1933). Analysis of a complex of statistical variables into principal components. ↩
Mahalanobis, P.C. (1936). On the generalized distance in statistics. ↩
Huber, P.J. (1981). Robust Statistics. ↩
Shannon, C.E. (1948). A Mathematical Theory of Communication. ↩

Biometric fingerprint authentication on SmartCard Chips

Julio Chinchilla — Tue, 16 Sep 2025 04:09:23 +0000

SEP7US MatchOnCard Auxiliary

During the years 2013 to 2018, in my early programming journey, I worked on projects related to smart cards based on ISO/IEC 7816-4 smart card chips. Below, I present SEP7US, a library I implemented that was used for biometric match-on-card verification, following NIST’s MINEX guidelines.

Author

Julio Chinchilla

Project Repository

You can find the full project here: GitHub - SEP7US

I consider it very important to briefly explain how this library works, since there is very little public documentation available about biometric standards.

Disclaimer

SEP7US Match on Card 0x7E3

Any modification made without proper supervision or consent is at your own risk. Changing the code will drastically alter verification results on any PIV Smart Card application.

Languages and Tools

C++
Java Native Interface (JNI)

Purpose

SEP7US provides an auxiliary library for converting biometric minutiae templates:

ISO/IEC 19794-2:2005
ANSI INCITS 378-2004

into the ISOCC format required for biometric match-on-card verification of chips based on ISO/IEC 7816-4 standards.

Internal Process

Minutiae Counting
Spatial Requantization
Angular Requantization
Minutiae Sorting

Template Identification

It is important to define the starting position of minutiae data depending on the template type:

ISO/IEC 19794-2:2005

posDataTemplate = 0x12; // DEC=18

ANSI INCITS 378-2004

posDataTemplate = 0x14; // DEC=20

Minutiae Counting

short numMinutiae = (short) fTemplate[posDataTemplate+9] & 0xFF;

The array size for the ISOCC template will be determined by:

// numMinutiae
short sizeISOCC = numMinutiae * 3;  // (X, Y, T|A)

Spatial Requantization

This process expresses minutiae coordinates in terms of 0.1mm.

Base Formula:

CoordMM      = 10 * Coord / RES
CoordUNITS   = CoordMM / 0.1
CoordCC      = 0.5 + CoordUNITS

Template Resolution Calculation:

short xres = (short) (fTemplate[posDataTemplate+0] << 8 | fTemplate[posDataTemplate+1]) & 0xFF;
short yres = (short) (fTemplate[posDataTemplate+2] << 8 | fTemplate[posDataTemplate+3]) & 0xFF;

X Coordinate:

*pcoordmmX    = 10.0 * (double) *ptmpx / xres;
*pcoordunitsX = *pcoordmmX / 0.1;
*pcoordccX    = (short)(.5 + *pcoordunitsX);

Y Coordinate:

*pcoordmmY    = 10.0 * (double) *ptmpy / yres;
*pcoordunitsY = *pcoordmmY / 0.1;
*pcoordccY    = (short)(.5 + *pcoordunitsY);

Angular Requantization

The angular requantization represents minutiae angles in 6 bits (0–63), considering that the maximum value is 360°.

ISOCC angle resolution:

360/64 = 5.625°

float ISOCC_ANGLE_RESOLUTION = 5.625f;

For ISO/IEC 19794-2:2005:

360/256 = 1.40625°

ANGLE_RESOLUTION = 1.40625f;

For ANSI INCITS 378-2004:

360/180 = 2°

ANGLE_RESOLUTION = 2;

Final Computation:

tmpCAngle = ANGLE_RESOLUTION * (*ptmpa);
tmpFAngle = tmpCAngle / ISOCC_ANGLE_RESOLUTION;
short t   = (*ptmpt | tmpFAngle) & 0xFF;

Minutiae Sorting

Although some smart cards do not require sorting, SEP7US provides four main sorting functions:

void XYAsc(unsigned char *a, short n);  // X ascending
void XYDsc(unsigned char *a, short n);  // X descending
void YXAsc(unsigned char *a, short n);  // Y ascending
void YXDsc(unsigned char *a, short n);  // Y descending

External Methods

ISOCC

Generates an ISO Compact Card template.

__declspec(dllexport) unsigned char *ISOCC(
    unsigned char templateFormat,
    unsigned char *fTemplate,
    unsigned char sorting
);

Parameters:

templateFormat: 0xFF for ISO/IEC 19794-2:2005, 0x7F for ANSI INCITS 378-2004
fTemplate: Pointer to the original template
sorting: Sorting option (0x00, 0x0F, 0x10, 0x1F)

Verify

Generates an ISOCC template with ISO/IEC 7816-4 APDU headers for PIV verification.

__declspec(dllexport) unsigned char *Verify(
    unsigned char CLA,
    unsigned char INS,
    unsigned char P1,
    unsigned char P2,
    unsigned char templateFormat,
    unsigned char *fTemplate,
    unsigned char sorting
);

Default APDU Command: 0x00 0x21

Headers added:

7F2E : "Biometric Data Template"

License

MIT

Forem: Julio Chinchilla

TemplateScorer

Project Repository

Table of Contents

Description

Dependencies

Usage

Implementation Details

Constants

scoreTemplate(ReadISO19794 template)

calculateWeights(List<Minutiae> raw)

extractAngles & extractPoints

calculateRobustCentroid

validateResolution

normalizePoints & calculateScaleFactor

computePCAAlignment

rotatePoints

geometricMedian

covariance

calculateMahalanobisDistances

calculateTrimmedMean

calculateQuadrantScore

calculateOrientationEntropy

References

Biometric fingerprint authentication on SmartCard Chips

SEP7US MatchOnCard Auxiliary

Author

Project Repository

Disclaimer

Languages and Tools

Purpose

Internal Process

Template Identification

ISO/IEC 19794-2:2005

ANSI INCITS 378-2004

Minutiae Counting

Spatial Requantization

Angular Requantization

Minutiae Sorting

External Methods

ISOCC

Verify

License

`scoreTemplate(ReadISO19794 template)`

`calculateWeights(List<Minutiae> raw)`

`extractAngles` & `extractPoints`

`calculateRobustCentroid`

`validateResolution`

`normalizePoints` & `calculateScaleFactor`

`computePCAAlignment`

`rotatePoints`

`geometricMedian`

`covariance`

`calculateMahalanobisDistances`

`calculateTrimmedMean`

`calculateQuadrantScore`

`calculateOrientationEntropy`