Image compatibility in RC9

New Site Configurations store a version-1 source_image.signature alongside the existing source dimensions and checksum. Site Configuration schema version 2 remains current. The signature contains width and height, channel count, single-channel/interleaved organization, decoded color model (GRAY, BGR, or BGRA), NumPy dtype, effective bit depth, and EXIF orientation.

GRIME3 inspects an unchanged decode before its normal color conversion. Width and height describe the EXIF-oriented coordinates used by the production color decoder. Effective bit depth means bits per sample in the unchanged decoded array (for example uint8 = 8 and uint16 = 16). It is not inferred from the brightest pixel, sensor specifications, or compressed file size. A packed 1-bit image expanded to uint8 by the decoder has an effective decoded depth of 8. The recorded color model likewise describes the unchanged decoded representation, not the camera's sensor mosaic or an embedded ICC profile.

Calibration creation, CLI calibration using a template, current-image projection, and single-image/folder/tree measurement share the same gate. A signature-bearing configuration requires an exact signature match before its ROIs, geometry, or processing settings are applied. A grayscale image does not match a BGR configuration, and alpha-bearing BGRA does not match BGR. File extension, compression format, and image checksum may differ across measurement frames when the signature matches. This gate does not establish that camera pose or optics have remained fixed.

The existing scientific pipeline supports 8-bit grayscale, BGR, and BGRA inputs. After acceptance it uses the established 8-bit BGR color decoder. Higher-bit-depth and floating-point inputs are rejected rather than silently truncated. Supporting those inputs scientifically requires a separate, explicit conversion policy and a new calibration.

Older configurations

Schema-version-1 and version-2 configurations without a signature still load. Their saved width and height must match, and the image must have a supported 8-bit representation. If the current image's checksum matches the original calibration source, the decision is legacy_source_verified; otherwise it is legacy_dimensions_only, with an explicit warning that original photometry cannot be verified. A size mismatch is legacy_dimension_mismatch and is rejected. Loading, processing, and ordinary Save/Save As never invent a signature or silently rewrite the original file.

Recalibration creates a fully signed configuration. Alternatively, explicitly migrate using the exact original source image, verified by its saved SHA-256:

grime3 migrate-image-signature --site-config "/path/to/legacy.json" --source-image "/path/to/original.jpg" --output "/path/to/signed.json" --operator "Operator Name"

Use quoted Windows paths on Windows. Migration preserves existing identities, calibration/ROI geometry, settings, and component creation/save audit history; it updates file-save provenance. Version-1 configurations receive their normal generated identities on loading, which become persistent when saved as version 2. Existing destinations require --overwrite. If the original image is unavailable or its bytes have changed, migration refuses; recalibrate instead.

Result provenance

Projection responses and exhaustive per-image/measurement JSON contain an image_compatibility object with accepted, status, message, expected_signature, and observed_signature. Matching signed configurations report signature_match; mismatches report signature_mismatch. Unsupported inputs report unsupported_image_format. Decode failures have no observed signature and report image_decode_failed. A later detection or measurement failure retains the successful compatibility decision.

Rejected images produce no scientific stage value. Persistent per-image JSON also records rejection when enabled; in-memory workflows retain the same information without forcing a per-image file. Mixed accepted/rejected folder runs can continue and serialize their diagnostic summaries. The curated public measurement CSV columns and their existing meanings remain unchanged.