PupilMetrics runs **two independent analysis pipelines** on every image and then fuses their outputs into a single confidence score.
**Classical CV (pixel-based)**
The classical computer vision pipeline uses circle detection, radial sampling, and boundary-point analysis on the full-resolution image. It produces pixel-accurate iris and pupil boundaries.
**ML Model (ONNX)**
The machine learning model (`cnri_model.onnx`) is a neural network trained on iris images, resized to a normalized 224×224 crop centered on the detected iris. It outputs four regression values: PI ratio, decentration, ellipseness, and decentration angle.
**Hybrid Confidence Formula**
The four components are weighted and combined:
| Component | Weight | What it measures |
|———–|——–|—————–|
| Capture quality | 20% | Image sharpness, brightness, contrast from the quality gate |
| Classical CV confidence | 35% | Circle detection score from the Hough-like iris finder |
| ML plausibility | 20% | Whether the ML outputs fall within anatomically reasonable ranges |
| Cross-model agreement | 25% | How closely the two pipelines agree on PI ratio (80%), ellipseness (10%), and decentration (10%) |
The fused confidence is displayed as a percentage and maps to the familiar grade:
| Fused confidence | Grade |
|—————–|——-|
| > 75% | **A** |
| 60–75% | **B** |
| 45–60% | **C** |
| < 45% | **D** |
**Safety caps**
If classical CV confidence falls below 25%, or if capture quality falls below 30%, the fused score is capped at 40% or 50% respectively, regardless of other components. This ensures a poor underlying image always produces a conservative grade.
**When the two pipelines disagree**
When the classical and ML results differ significantly on PI ratio (> 10% tolerance), the agreement component reduces the hybrid score. The individual classical and ML values are still shown in the results for reference when “Show ML Comparison” is enabled in settings.
