Measurement quality evidence (RC9)
GRIME3 records two separate descriptive scores,
image_quality and linefind_quality, on a 0.0
to 1.0 scale. They assist evaluation and filtering. They are not
probabilities, accuracy estimates, or acceptance criteria. They
do not change the selected deterministic pass, calibrated water level,
octagon acceptance, line acceptance, or failure status.
JSON contract
Every per-image measurement payload and measurement-summary record
contains the scalar image_quality and
linefind_quality fields and a quality block.
An error-record excerpt is:
{
"image_quality": null,
"linefind_quality": null,
"quality": {
"schema_version": 1,
"image_quality": {
"score": null,
"status": "unavailable",
"method": "native_roi_evidence",
"method_version": 1,
"reason_codes": ["image_decode_failed"],
"components": {},
"diagnostics": {}
},
"linefind_quality": {
"score": null,
"status": "unavailable",
"method": "waterline_search_evidence",
"method_version": 1,
"reason_codes": ["image_decode_failed"],
"components": {},
"diagnostics": {}
},
"selected_pass": "none"
}
}Actual pass_quality always contains separate
raw and preprocessed records using the same
evidence format. The top-level linefind score uses the pass already
selected by the deterministic measurement algorithm. Its supporting
selected points and raw/preprocessed diagnostics remain in the
exhaustive JSON regardless of CSV selection.
available means the method's evidence was evaluated.
partial means an image ROI or cross-pass comparison was
unavailable; inspect the reasons and components before comparing that
score with complete records. unavailable uses JSON
null, never a fabricated zero. no_line_found
uses a score of 0 when swath search evidence exists but no line was
selected. A low score does not imply that measurement failed; a high
score does not prove correctness.
Quality is computed per image, including errors. Decoding or compatibility failure produces unavailable scores. If ROI resolution fails after decoding, image evidence from the configured ROIs remains available. Successful ROI resolution replaces waterline image evidence with the resolved ROI. In-memory browser results use the same contract without forcing a persistent file.
Image method:
native_roi_evidence, version 1
The method inspects the original grayscale image at native pixel resolution before either deterministic pass applies preprocessing. It evaluates the configured octagon search rectangle and the resolved waterline quadrilateral, falling back to configured waterline coordinates when resolution fails. Invalid or out-of-bounds polygons are explicitly unavailable, not silently clipped. A region needs at least 25 included pixels and 9 interior pixels.
Each region retains its coordinates, pixel count, grayscale
5th/50th/95th percentiles, fractions at or below 2 and at or above 253,
and native-pixel Laplacian variance. The Laplacian uses
CV_64F, ksize=1, and interior ROI pixels.
Sampling uses the established 8-bit grayscale processing
representation.
The three region components are:
- Contrast:
min(1, ((P95 - P05) / 255) / 0.10). - Detail:
Laplacian_variance / (Laplacian_variance + 1.0). - Exposure:
max(0, 1 - dark_fraction - bright_fraction).
The region score is the geometric mean of these three components. The
image score is the minimum available region score, with all region
scores retained. Missing regions make the aggregate
partial; no available region makes it
unavailable. The constants are explicit heuristic scales,
not thresholds learned from a population of field images.
Reason codes include low_contrast below the contrast
full-score scale, low_detail_or_blur below Laplacian
variance 1.0, and dark_clipping or
bright_clipping when the corresponding fraction exceeds
0.05. These describe measured evidence. They do not identify fog, haze,
ice, obstruction, or another physical cause. Such effects may lower
contrast/detail, but a validated classifier or independent evidence is
needed to label their cause.
Detail depends on scene texture, scale, ROI placement, noise, and camera processing. Noise can increase Laplacian variance. This method does not claim a universal blur detector or a noise-corrected sharpness estimate. Compare scores with consistent site, representation, resolution, and ROI policy; inspect components rather than treating the aggregate as ground truth.
Line method:
waterline_search_evidence, version 1
The method uses the actual selected line and point set from each existing deterministic pass. Support is counted from unique selected swath identities; fit residuals are recomputed against the final line from the selected points. The original reported residual evidence remains in the existing result JSON.
The composite is the product of these bounded components:
- Support: selected swaths / requested swaths.
- Coverage: selected ordinal swath span / full ordinal swath span.
- Continuity:
1 - longest_missing_swath_run / requested_swaths; missing runs include leading and trailing gaps. - Residual:
1 / (1 + RMS_perpendicular_residual_px / 2.0). - Edge response:
mean_response / (mean_response + 5.0), where the response is in 8-bit grayscale units per profile sample. The coherent line provides its selected mean response; a rank-1 MAD fit uses the absolute strongest first-derivative responses of its accepted swaths. - Cross-pass stability, when both line models exist:
1 / (1 + RMS_line_separation_px / 2.0). Separation is evaluated at the selected points' x coordinates in perpendicular selected-line pixel units.
Unavailable cross-pass geometry omits the stability component and
marks the record partial; the omission is explicit in
diagnostics. Missing mandatory point, swath, final-model, or response
evidence makes the score unavailable. Residual or cross-pass RMS above 2
pixels, response below 5, incomplete support, coverage below 0.8, and
missing swath gaps produce corresponding reason codes. Rejected lines
that retain complete geometry can still have a descriptive score, with
line_rejected_by_measurement explicitly recorded.
Stability here compares raw and preprocessed results for the same image; it is not temporal stability or an independent truth measurement. Blur can improve fit residuals while weakening the edge, so residual alone is not used as the quality score. Mild blur can improve geometric agreement enough to raise linefind quality while image quality declines; the two metrics measure different evidence. All constants and units are retained in diagnostics. Changes to these calculations or scales require a new method version.
Browser and CSV selection
The browser result panel shows both scores with availability status. Open CSV Columns and select Image quality, Linefind quality, or both. Selections use the existing browser preference persistence. Quality fields are optional and initially unselected; all required CSV fields remain present. The field catalog now offers 22 choices, while each emitted CSV remains limited to 20 selected columns. Deselect other optional fields if that limit is reached.
For grime3 measure image, folder, or
folders, use either or both flags:
--csv-image-quality --csv-linefind-quality
These flags augment default columns unless an explicit
--csv-column selection is supplied; with an explicit
selection they augment that selection. The existing
--csv-column image_quality --csv-column linefind_quality
form also works. Missing scalar values are blank in CSV and
null in JSON. The CSV checkpoint interval remains 10
images.
Reserved PNG metadata names
For future PNG result output, reserve
grime3.image_quality and
grime3.linefind_quality for the corresponding JSON number
or literal null, and grime3.quality for the
complete serialized quality block. This release does not add PNG output
or modify image files.