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.