DEV Community

Julio Chinchilla
Julio Chinchilla

Posted on

TemplateScorer

#java #biometrics #security #fingerprint

SCORERS

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

Table of Contents

Description

The overall scoring pipeline is:

  1. Read minutiae
  2. Weighting based on quality
  3. Compute robust centroid (geometric median)
  4. Spatial normalization and PCA alignment
  5. Compute Mahalanobis distances
  6. Trimmed mean of distances
  7. 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);
    }
}
Enter fullscreen mode Exit fullscreen mode

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:

  1. Extracts minutiae, weights, angles, and coordinates.
  2. Computes robust centroid (geometric median) with geometricMedian1.
  3. Validates and normalizes resolution (validateResolution).
  4. Centers and normalizes points with scale factor (normalizePoints).
  5. Aligns with PCA (computePCAAlignment)23.
  6. Rotates points by PCA angle (rotatePoints).
  7. Computes Mahalanobis distances (calculateMahalanobisDistances)4.
  8. Gets trimmed mean of distances (calculateTrimmedMean)5.
  9. Computes quadrantScore (spatial distribution).
  10. Computes orientationEntropy (angle entropy) (calculateOrientationEntropy)6.

  11. 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 sum1.

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 matrix23:

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

rotatePoints

Rotates each point (x,y) by angle:

x' = x·cos – y·sin;  y' = x·sin + y·cos
Enter fullscreen mode Exit fullscreen mode

geometricMedian

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

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

covariance

Weighted covariance matrix:

c00 = Σ w·dx² / Σw;  c01 = Σ w·dx·dy / Σw;  c11 = Σ w·dy² / Σw;
Enter fullscreen mode Exit fullscreen mode

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)5.

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 entropy6: –Σ₁ᵇ pᵢ·log₂(pᵢ)
  • Normalizes by log₂(HIST_BINS) to obtain [0,1].

References

  1. Weiszfeld, E. (1937). Sur le point pour lequel la somme des distances de n points donnés est minimum.  ↩

  2. Pearson, K. (1901). On lines and planes of closest fit to systems of points in space.  ↩

  3. Hotelling, H. (1933). Analysis of a complex of statistical variables into principal components.  ↩

  4. Mahalanobis, P.C. (1936). On the generalized distance in statistics.  ↩

  5. Huber, P.J. (1981). Robust Statistics.  ↩

  6. Shannon, C.E. (1948). A Mathematical Theory of Communication.  ↩

Top comments (0)