Add geometry, datetime precision, timezone, GPS

Extend cross-family concept resolution with Geometry support and richer DateTime/GPS metadata. Adds MetadataConceptKind::Geometry and new roles (Crop, ActiveArea, Border, SensorGeometry); candidate fields for origin/size/rect/margins and geometry keying; and logic to extract geometry candidates from interpretation/query records. Introduces date/time precision and timezone enums plus helpers to parse/attach precision and UTC/offset/local classification. Adds GPS altitude-reference detection (EXIF/XMP), below-sea-level state, and propagates altitude reference entries into candidates. Updates Python bindings, tests, and documentation/CHANGES to expose the new fields and behaviors.

Author: ssh4net

CHANGES.md

@@ -106,8 +106,13 @@ Changes compared with `0.4.8`.
   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.
+  keys, parsed date/time fields, timezone/precision classification, combined
+  GPS date/time candidates, GPS altitude-reference state, and same-role
+  conflict flags.
+- Extended cross-family concept resolution with geometry candidates for crop,
+  active area, border, and sensor-geometry records. Geometry candidates expose
+  canonical origin, size, rect, and margin fields when the query/interpretation
+  layer can normalize them.
 - 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.

docs/api_stability.md

@@ -26,7 +26,7 @@ different status.
 | 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. |
+| 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, date/time precision, timezone kind, normalized geometry fields, and same-role conflicts for orientation, date/time, color/profile, GPS, and geometry evidence across EXIF, XMP, IPTC, ICC, PNG text, and query-backed interpretation records where applicable. Geometry candidates cover crop, active area, border, and sensor geometry with canonical origin, size, rect, and margin fields when available. GPS date/time is combined from `GPSDateStamp` plus `GPSTimeStamp` when both entries exist, and GPS altitude candidates expose altitude-reference code plus below-sea-level state when reference metadata is present. 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

@@ -64,12 +64,13 @@ 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.
+It currently resolves orientation, date/time, color/profile, GPS, and geometry
+into candidate lists with candidate source entries, source families, preferred
+entries, normalized compare keys, parsed date/time fields, date/time precision,
+timezone kind, GPS altitude-reference state, canonical geometry
+origin/size/rect/margins, 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
 

docs/host_integration.md

@@ -50,10 +50,14 @@ 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
+color/profile, GPS, and geometry candidates with source families, preferred
+entries, and same-role conflict flags. Geometry candidates expose crop,
+active-area, border, and sensor-geometry roles with canonical origin, size,
+rect, and margin fields when available. Date/time candidates include parsed
+date/time fields when the source value is recognizable, plus precision and
+timezone-kind fields. GPS timestamps combine `GPSDateStamp` with
+`GPSTimeStamp` when both are present, and GPS altitude candidates report
+whether `GPSAltitudeRef` marked the height as below sea level. Treat this as an
 inspection and policy input rather than an automatic metadata rewrite decision.
 
 ## Adapter Classes
@@ -79,7 +83,7 @@ OpenMeta splits host integration surfaces deliberately:
   `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
+  GPS, and geometry conflict inspection
 
 ## 1. Read Into `MetaStore`
 

docs/interpretation_status.md

@@ -40,7 +40,7 @@ explicit outcome:
 | Vendor MakerNotes | Broad MakerNote naming and source-processing classification exists for common vendors and several live computational/thermal vendors. Unknown entries remain lossless and source-private subgroups distinguish preview, face geometry, computational, thermal, and stitch/panorama data. | Medium-high, about 75-85%. | ExifTool-style long-tail print conversions, encrypted/custom settings, and per-model private tables. |
 | BMFF item graph, HEIF/AVIF/CR3, JUMBF, and C2PA | BMFF derived fields, item-info rows, bounded relations, primary-linked roles, aux semantics, and draft C2PA/JUMBF structural fields are exposed. | Medium, about 60-70%. | Full BMFF scene modeling and full C2PA manifest/policy semantics. |
 | Photoshop IRB | Raw resources are preserved and a bounded interpreted subset is decoded for fixed-layout resources. | Medium, about 60-70%. | Broader resource-specific interpretation. |
-| Semantic query/search and records | Query helpers expose raw matches, confidence, provenance, value shapes, normalized candidates, canonical crop/active-area rectangles, border margins, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and first bounded cross-family concept resolution for orientation, date/time, color/profile, and GPS with parsed date/time fields and combined GPS timestamps. | Medium, about 52-60%. | More canonical shapes, deeper GPS/date normalization, and richer per-record host policy hints. |
+| Semantic query/search and records | Query helpers expose raw matches, confidence, provenance, value shapes, normalized candidates, canonical crop/active-area rectangles, border margins, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and first bounded cross-family concept resolution for orientation, date/time, color/profile, GPS, and geometry with parsed date/time fields, timezone/precision classification, combined GPS timestamps, GPS altitude-reference state, and canonical geometry origin/size/rect/margins. | Medium, about 58-65%. | More canonical shapes for color/lens/RAW-processing records, richer GPS coordinate/reference policy, and richer per-record host policy hints. |
 | Transfer-safety classification | Compatible-file versus rendered-image safety policies classify source-specific image geometry, color/profile, RAW-processing, MakerNote, JUMBF/C2PA, and vendor-private data. | High, about 85-90%. | More user-facing diagnostics and additional per-family policy tests. |
 
 ## Competitor Position
@@ -58,10 +58,11 @@ outputs.
 ## Next Interpretation Priorities
 
 1. Expand cross-family concept resolution beyond the current orientation,
-   date/time, color/profile, and GPS pass, especially richer timezone, GPS
-   altitude/reference, and host policy hints.
-2. Add more canonical record shapes for vendor geometry, color, lens
-   correction, and RAW-processing groups.
+   date/time, color/profile, GPS, and geometry pass, especially richer GPS
+   coordinate validation, altitude unit/reference policy, and host policy
+   hints.
+2. Add more canonical record shapes for vendor color, lens correction, and
+   RAW-processing groups.
 3. Expand MakerNote meaning depth in vendor order: Nikon, Canon, Sony,
    Fujifilm, Phase One/Leaf, then remaining active vendors.
 4. Deepen BMFF/CR3/HEIF/AVIF item graph semantics only where hosts can use the

docs/quick_start.md

@@ -163,10 +163,11 @@ rect/margin/value arrays where available.
 
 For duplicated concepts that may appear in multiple metadata families, use
 `openmeta/metadata_concepts.h`. The first experimental resolver covers
-orientation, date/time, color/profile, and GPS. It returns candidate source
-entries, source families, preferred entries, normalized date/time fields where
-available, and same-role conflict flags so host UI can show ambiguity instead
-of guessing silently.
+orientation, date/time, color/profile, GPS, and geometry. It returns candidate
+source entries, source families, preferred entries, normalized date/time fields
+where available, date/time precision, timezone kind, GPS altitude-reference
+state, canonical geometry origin/size/rect/margins, and same-role conflict
+flags so host UI can show ambiguity instead of guessing silently.
 
 For user-facing orientation display, use `openmeta/orientation.h` instead of
 showing only the numeric EXIF/TIFF index. `interpret_exif_orientation(...)`

docs/sphinx/api_stability.rst

@@ -129,13 +129,19 @@ Host-facing API map
      - 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.
+       fields, date/time precision, timezone kind, normalized geometry fields,
+       and same-role conflicts for orientation, date/time, color/profile, GPS,
+       and geometry evidence across EXIF, XMP, IPTC, ICC, PNG text, and
+       query-backed interpretation records where applicable. Geometry
+       candidates cover crop, active area, border, and sensor geometry with
+       canonical origin, size, rect, and margin fields when available. GPS
+       date/time is combined from ``GPSDateStamp`` plus ``GPSTimeStamp`` when
+       both entries exist, and GPS altitude candidates expose
+       altitude-reference code plus below-sea-level state when reference
+       metadata is present. 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(...)``

docs/sphinx/development.rst

@@ -106,12 +106,13 @@ 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.
+It currently resolves orientation, date/time, color/profile, GPS, and geometry
+into candidate lists with candidate source entries, source families, preferred
+entries, normalized compare keys, parsed date/time fields, date/time precision,
+timezone kind, GPS altitude-reference state, canonical geometry
+origin/size/rect/margins, 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.
 
 Read-path coverage snapshot
 ---------------------------

docs/sphinx/host_integration.rst

@@ -56,11 +56,16 @@ 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.
+color/profile, GPS, and geometry candidates with source families, preferred
+entries, and same-role conflict flags. Geometry candidates expose crop,
+active-area, border, and sensor-geometry roles with canonical origin, size,
+rect, and margin fields when available. Date/time candidates include parsed
+date/time fields when the source value is recognizable, plus precision and
+timezone-kind fields. GPS timestamps combine ``GPSDateStamp`` with
+``GPSTimeStamp`` when both are present, and GPS altitude candidates report
+whether ``GPSAltitudeRef`` marked the height as below sea level. Treat this as
+an inspection and policy input rather than an automatic metadata rewrite
+decision.
 
 Adapter classes
 ---------------
@@ -87,7 +92,7 @@ OpenMeta splits host integration surfaces deliberately:
   ``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
+  color/profile, GPS, and geometry conflict inspection
 
 Read and query
 --------------