Add interpretation, concepts, and EXIF value names

Introduce structured metadata interpretation and cross-family concept resolution plus human-readable EXIF/TIFF/DNG numeric value names. New public APIs: openmeta/metadata_interpretation.h, openmeta/metadata_concepts.h, and openmeta/exif_value_names.h (with implementations and tests). Update metadata_query to add SourceProcessing match and margin support, extend vendor_raw_processing groups, and add LibRaw orientation conflict reporting in libraw_adapter. Wire new sources/tests into CMake and update docs/quick start, host integration, and stability pages to document the new helper contracts. These changes provide iterable interpretation records, bounded concept resolution for orientation/date/time/color/GPS, and stable labels for common enum-like numeric tag values to aid host UIs and transfer/inspection workflows.

Author: ssh4net

CHANGES.md

@@ -97,6 +97,24 @@ Changes compared with `0.4.8`.
   interpretation helpers for user-facing labels, clockwise rotation degrees,
   mirrored-state checks, width/height-swap checks, and rotation-only fallbacks,
   plus matching thin Python wrappers.
+- Added `openmeta/exif_value_names.h` with stable labels for common
+  EXIF/TIFF/DNG enum-like numeric values, plus matching thin Python wrappers.
+- Added `openmeta/metadata_interpretation.h` with query-backed structured
+  interpretation records for host/UI code that wants normalized semantic
+  records instead of raw query candidates.
+- Added `openmeta/metadata_concepts.h` with first bounded cross-family concept
+  resolution for orientation, date/time, color/profile, and GPS candidates
+  across EXIF, XMP, IPTC, ICC, and PNG text where applicable, including source
+  families, candidate source entries, preferred entries, normalized compare
+  keys, parsed date/time fields, combined GPS date/time candidates, and
+  same-role conflict flags.
+- Semantic crop queries now expose canonical border-margin candidates for
+  parseable border/padding XMP text, DNG masked-area candidates, and Phase
+  One/Leaf geometry margins.
+- Vendor RAW/source-processing classification now distinguishes source-private
+  preview, face-geometry, computational, thermal, and stitch/panorama buckets
+  in addition to the existing color, white-balance, geometry, storage,
+  lens-correction, raw-data, sensor, and private-table groups.
 - Added focused regression coverage for compatible-file versus rendered-image
   transfer safety: compatible mode keeps serializable source RAW/camera-specific
   metadata, while rendered mode drops source-specific metadata and uses

CMakeLists.txt

@@ -339,6 +339,7 @@ set(OPENMETA_SOURCES
   src/openmeta/exif_makernote_samsung.cc
   src/openmeta/exif_makernote_sony.cc
   src/openmeta/exif_makernote_tag_names.cc
+  src/openmeta/exif_value_names.cc
   src/openmeta/exr_adapter.cc
   src/openmeta/exr_decode.cc
   src/openmeta/exif_tag_names.cc
@@ -355,6 +356,8 @@ set(OPENMETA_SOURCES
   src/openmeta/libraw_adapter.cc
   src/openmeta/meta_key.cc
   src/openmeta/metadata_capabilities.cc
+  src/openmeta/metadata_concepts.cc
+  src/openmeta/metadata_interpretation.cc
   src/openmeta/metadata_query.cc
   src/openmeta/metadata_transfer.cc
   src/openmeta/meta_store.cc
@@ -762,12 +765,15 @@ if(OPENMETA_BUILD_TESTS)
     tests/exr_adapter_test.cc
     tests/exr_decode_test.cc
     tests/exif_tiff_decode_test.cc
+    tests/exif_value_names_test.cc
     tests/geotiff_decode_test.cc
     tests/iptc_iim_decode_test.cc
     tests/interop_export_test.cc
     tests/dji_app4_decode_test.cc
     tests/makernote_decode_test.cc
     tests/metadata_capabilities_test.cc
+    tests/metadata_concepts_test.cc
+    tests/metadata_interpretation_test.cc
     tests/metadata_query_test.cc
     tests/metadata_transfer_api_test.cc
     tests/flir_fff_decode_test.cc

docs/api_stability.md

@@ -23,7 +23,10 @@ different status.
 | `ExportNameStyle::Canonical` and `ExportNameStyle::XmpPortable` | `openmeta/interop_export.h` | Stable | Stable naming modes for key-space-aware and portable exports. |
 | `ExportNameStyle::FlatHost` | `openmeta/interop_export.h` | Stable | Stable v1 flat host naming contract. See [flat_host_mapping.md](flat_host_mapping.md). |
 | EXIF/TIFF orientation helpers: `interpret_exif_orientation(...)`, `exif_orientation_name(...)`, `exif_orientation_rotation_degrees_cw(...)`, `exif_orientation_rotation_only(...)` | `openmeta/orientation.h` | Stable | Small utility contract for user-facing orientation labels, clockwise rotation degrees, mirrored-state detection, dimension-swap detection, and rotation-only fallbacks. Python exposes the same helpers through thin scalar/dictionary wrappers. |
-| Semantic metadata query: `query_metadata(...)`, `query_crop_metadata(...)`, focused query helpers, and `metadata_query_fuzzy_search_available()` | `openmeta/metadata_query.h` | Experimental | Query contract for inspection matches plus normalized candidates. Current coverage includes crop/active-area, exposure/gain, white balance, color, lens correction, orientation, and RAW-processing metadata across standard tags, selected DNG tags, fuzzy XMP paths, and vendor RAW-processing classification. Matches report `exact_match`, `fuzzy_match`, and `fuzzy_score` so tools can label exact results separately from RapidFuzz near-miss hits. `OPENMETA_ENABLE_RAPIDFUZZ=ON` adds optional near-miss XMP/property-path scoring. Grouped candidates include `matrix_set`, `vector_set`, and `table` shapes for related non-crop metadata, including RAW black/white levels, linearization, CFA/sensor layout, source geometry, and raw-storage identifiers. Python `Document` and `TransferSourceSnapshot` mirror this as thin dictionary-returning wrappers. |
+| EXIF/TIFF/DNG numeric value names: `exif_tag_numeric_value_name(...)` and focused helpers | `openmeta/exif_value_names.h` | Stable | Small helper contract for common enum-like TIFF/EXIF/DNG numeric values such as compression, photometric interpretation, planar configuration, exposure program, metering mode, light source, flash, color space, white balance, scene capture type, gain control, CFA layout, and DNG calibration illuminants. Unknown values return an empty string and remain lossless numeric metadata. |
+| Semantic metadata query: `query_metadata(...)`, `query_crop_metadata(...)`, focused query helpers, and `metadata_query_fuzzy_search_available()` | `openmeta/metadata_query.h` | Experimental | Query contract for inspection matches plus normalized candidates. Current coverage includes crop/active-area/border margins, exposure/gain, white balance, color, lens correction, orientation, and RAW/source-processing metadata across standard tags, selected DNG tags, fuzzy XMP paths, and vendor RAW-processing classification. Matches report `exact_match`, `fuzzy_match`, and `fuzzy_score` so tools can label exact results separately from RapidFuzz near-miss hits. `OPENMETA_ENABLE_RAPIDFUZZ=ON` adds optional near-miss XMP/property-path scoring. Grouped candidates include `matrix_set`, `vector_set`, and `table` shapes for related non-crop metadata, including RAW black/white levels, linearization, CFA/sensor layout, source geometry, raw-storage identifiers, and source-processing buckets. Python `Document` and `TransferSourceSnapshot` mirror this as thin dictionary-returning wrappers. |
+| Structured metadata interpretation records: `interpret_metadata(...)`, `interpret_metadata_query(...)` | `openmeta/metadata_interpretation.h` | Experimental | Thin structured projection over semantic query candidates. Records carry query class, semantic kind, normalized shape, confidence, source entry ids, and normalized origin/size/rect/margins/value arrays where available. Current scope covers orientation, geometry/crop/border, exposure/gain, color/white-balance, lens-correction, and RAW/source-processing records. Python `Document` and `TransferSourceSnapshot` expose matching dictionary wrappers. |
+| Cross-family concept resolution: `resolve_metadata_concepts(...)`, `resolve_metadata_concept(...)` | `openmeta/metadata_concepts.h` | Experimental | First bounded resolver for duplicated host-facing concepts. Current scope reports candidates, candidate source entries, source families, preferred entries, normalized numeric/text keys, normalized date/time fields, and same-role conflicts for orientation, date/time, color/profile, and GPS evidence across EXIF, XMP, IPTC, ICC, and PNG text where applicable. GPS date/time is combined from `GPSDateStamp` plus `GPSTimeStamp` when both entries exist. It is intended for inspection UI and host policy decisions; it does not rewrite metadata or hide ambiguity. Python `Document` and `TransferSourceSnapshot` expose matching dictionary wrappers. |
 | Vendor RAW-processing summaries: `vendor_raw_processing_from_store(...)`, `classify_vendor_raw_processing_field(...)` | `openmeta/vendor_raw_processing.h` | Experimental | Conservative grouped source-RAW/source-processing field summaries for decoded Sony, Canon, Nikon, Fujifilm, Pentax, Panasonic, Olympus, Kodak, Minolta, Sigma, Samsung, Ricoh, Apple, DJI, Google, FLIR, Casio, Sanyo, KyoceraRaw, Reconyx, HP, JVC, GE, Motorola, Nintendo, and Microsoft MakerNotes, including vendor-private, computational, thermal, preview, face-geometry, stitch/panorama, Apple computational capture/HDR/motion, DJI pose/thermal, Google HDR+/shot-log, and FLIR radiometric/raw-value buckets. Intended for audit/UI and rendered-transfer safety decisions, not for writing vendor RAW/source-processing values into rendered targets. |
 | Transfer safety audit: `transfer_safety_audit_from_store(...)` | `openmeta/metadata_transfer.h` | Experimental | Preflight summary of source entries and entries filtered or invalidated by `TransferSafetyMode`, including Sony/Canon/Nikon/Fujifilm/Pentax/Panasonic/Olympus/Kodak/Minolta/Sigma/Samsung/Ricoh/Apple/DJI/Google/FLIR/Casio/Sanyo/KyoceraRaw/Reconyx/HP/JVC/GE/Motorola/Nintendo/Microsoft RAW/source-processing buckets. Intended for diagnostics and host UI before preparing rendered-image transfers. |
 | Raw-carrier passthrough audit: `raw_carrier_passthrough_audit_from_snapshot(...)` | `openmeta/metadata_transfer.h` | Experimental | Diagnostic preflight for opt-in raw carriers. Reports candidate carriers and primary block reasons such as missing payload, target incompatibility, safety filtering, content-bound C2PA, explicit profile policy, missing decoded-entry links, or unsupported carrier kind. Hosts can call it directly before enabling snapshot passthrough. |

docs/development.md

@@ -18,7 +18,7 @@ model should stay compact:
 | --- | --- | --- |
 | Decoding | Find metadata carriers and decode EXIF, XMP, IPTC, ICC, Photoshop IRB, JUMBF/C2PA, EXR, and related blocks into `MetaStore` entries. | High, about 98-100% for the current target scope. |
 | Interpretation | Normalize names and values, group entries by meaning, and classify source-bound data such as RAW crop, color, lens-correction, sensor, and vendor-private fields. | Medium-high, about 80%. |
-| Query | Find entries by name, fuzzy term, or semantic group, for example crop/border/active-area, exposure/gain, color/WB, orientation, lens-correction, and RAW-processing fields across standard and vendor metadata. | Low, about 25-30%. |
+| Query | Find entries by name, fuzzy term, or semantic group, then expose normalized query candidates, structured interpretation records, and bounded cross-family concept resolutions for crop/border/active-area, exposure/gain, color/WB, orientation, date/time, GPS, lens-correction, and RAW/source-processing fields across standard and vendor metadata. | Medium, about 50-60%. |
 | Creation | Build fresh metadata entries from host-provided values. | Medium, about 55-65%. |
 | Editing | Modify existing logical metadata entries while preserving valid surrounding structure. | Medium, about 60-70%. |
 | Transfer | Move metadata between files using explicit compatible-file or rendered-image safety policies. | Medium-high, about 80-85%. |
@@ -41,13 +41,15 @@ RAW-processing queries.
 Crop queries include DNG crop tags, `ActiveArea`, Phase One/Leaf raw geometry,
 and fuzzy crop/border-style XMP property paths. The non-crop queries expose
 per-entry value candidates and reuse standard tag names, selected DNG tags,
-fuzzy XMP paths, and vendor RAW-processing classification where applicable.
+fuzzy XMP paths, canonical border-margin parsing, and vendor RAW-processing
+classification where applicable.
 They also append grouped candidates for related DNG color matrix/calibration/
 reduction/forward matrix tags, DNG white-balance vector tags, and
 lens-correction table groups. RAW-processing queries add conservative groups
 for black/white levels, linearization tables, CFA/sensor layout, source
-geometry, and raw-storage identifiers. Grouped candidates use `matrix_set`,
-`vector_set`, and `table` value shapes. When
+geometry, raw-storage identifiers, and source-private processing buckets.
+Grouped candidates use `matrix_set`, `vector_set`, and `table` value shapes.
+When
 `OPENMETA_ENABLE_RAPIDFUZZ=ON`, the same query helpers also use RapidFuzz to
 score near-miss XMP/property paths; default builds keep the deterministic
 substring/tag matcher only. Each raw match reports `exact_match`,
@@ -56,6 +58,19 @@ matches from near-miss search hits.
 Python `Document` and `TransferSourceSnapshot` mirror this as thin wrappers
 returning the same match/candidate dictionary shape.
 
+For code that wants an iterable semantic record stream instead of raw query
+matches, use `openmeta/metadata_interpretation.h`. It projects query candidates
+into records with query class, semantic kind, normalized shape, confidence,
+source entries, and normalized geometry/value arrays where available.
+
+For cross-family duplicated concepts, use `openmeta/metadata_concepts.h`.
+It currently resolves orientation, date/time, color/profile, and GPS into
+candidate lists with candidate source entries, source families, preferred
+entries, normalized compare keys, parsed date/time fields, and same-role
+conflict flags. This is deliberately an inspection/policy surface; host code
+still decides whether a conflict should be shown, ignored, or corrected during
+editing/transfer.
+
 ## Build Prerequisites
 
 - CMake `>= 3.20`

docs/host_integration.md

@@ -31,7 +31,10 @@ Use the narrowest public API that matches your host:
 | EXR writer | `build_exr_attribute_batch_from_file(...)` |
 | Host-owned metadata object model | `visit_metadata(...)` |
 | Host metadata inspection/search UI | `openmeta/metadata_query.h` focused query helpers |
+| Structured interpreted metadata records | `openmeta/metadata_interpretation.h` |
+| Cross-family concept conflicts | `openmeta/metadata_concepts.h` |
 | User-facing orientation display | `openmeta/orientation.h` |
+| Common EXIF/TIFF/DNG value labels | `openmeta/exif_value_names.h` |
 | JPEG/JXL/WebP/PNG/JP2/BMFF encoder path | `prepare_metadata_for_target_file(...)` + adapter view or backend emitter |
 | Adobe DNG SDK objects/files | `dng_sdk_adapter.h` |
 
@@ -40,6 +43,19 @@ building a separate fuzzy layer. They report source entries, confidence, value
 shape, exact/fuzzy match provenance, and normalized candidates while preserving
 ambiguity.
 
+For host code that wants a simpler iterable result, use
+`metadata_interpretation.h`. It keeps the same semantic vocabulary as query but
+returns structured records with query class, normalized shape, source entries,
+confidence, and normalized geometry/value arrays.
+
+For host code that needs to reconcile duplicated concepts across metadata
+families, use `metadata_concepts.h`. It reports orientation, date/time,
+color/profile, and GPS candidates with source families, preferred entries, and
+same-role conflict flags. Date/time candidates include parsed date/time fields
+when the source value is recognizable, and GPS timestamps combine
+`GPSDateStamp` with `GPSTimeStamp` when both are present. Treat this as an
+inspection and policy input rather than an automatic metadata rewrite decision.
+
 ## Adapter Classes
 
 OpenMeta splits host integration surfaces deliberately:
@@ -57,6 +73,13 @@ OpenMeta splits host integration surfaces deliberately:
 - orientation utility:
   `orientation.h` for EXIF/TIFF labels, rotation degrees, mirrored-state
   checks, and width/height-swap checks
+- value-name utility:
+  `exif_value_names.h` for common EXIF/TIFF/DNG enum-style numeric labels
+- structured interpretation utility:
+  `metadata_interpretation.h` for query-backed semantic records
+- concept-resolution utility:
+  `metadata_concepts.h` for cross-family orientation, date/time, color/profile,
+  and GPS conflict inspection
 
 ## 1. Read Into `MetaStore`