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:

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:

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.