Interpret image-region geometry and XMP wrappers

- Normalize scoped IPTC rectangle, circle, and polygon boundaries with explicit pixel/relative units.
- Interpret XMP manifest/version wrapper records, expose the additions through thin Python bindings, update documentation, and bump OpenMeta to 0.4.82.

Author: ssh4net

CHANGES.md

@@ -1,5 +1,27 @@
 # OpenMeta Changes
 
+## 0.4.82 - 2026-07-21
+
+Changes compared with `0.4.81`.
+
+### Added
+
+- Added scoped IPTC Extension image-region boundary interpretation for
+  rectangle, circle, and polygon shapes with explicit pixel or relative
+  coordinate units, numeric field candidates, normalized rectangle/circle
+  values, polygon vertex records, and complete source-entry provenance.
+- Added XMP Media Management manifest-item and version records for manifest
+  link/resolution fields and version comments, modifier, modification date,
+  and identifier wrappers.
+- Added append-only C++ and thin Python enums for image-region shapes,
+  coordinate units, boundary roles, and manifest/version record kinds.
+
+### Changed
+
+- XMP Media Management version wrapper fields now query as document history;
+  image-region boundaries require a target image specification, while
+  manifest/version records remain source-bound for rendered-image transfer.
+
 ## 0.4.81 - 2026-07-20
 
 Changes compared with `0.4.80`.

VERSION

@@ -1 +1 @@
-0.4.81
+0.4.82

docs/development.md

@@ -17,7 +17,7 @@ model should stay compact:
 | Area | Purpose | Readiness |
 | --- | --- | --- |
 | 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, exposure adjustment, color/profile/source-color-transform evidence, RAW curves/linearity metadata with descriptor-backed compressed-storage applicability, lens-correction, sensor, BMFF brand/item-property associations and rollups including `avio` AVIF brands, item groups, item semantic counts, whole-scene policy hints, graph-component summaries with per-component roles, member item IDs, semantic composition, typed relation counts, bounded `grid`/`iovl`/`iden` construction semantics with recursive item-offset descriptors and graph-cycle/source validation, bounded complete `tili` configuration/reference/offset-table interpretation, `container_graph` concepts, primary item properties, primary metadata-carrier flags, primary sidecar and scene summaries, and display-transform summaries, JUMBF labels, Photoshop IRB embedded carriers plus fixed-layout, XML/text, working-path and numbered clipping-path records, byte-count, descriptor-header, scalar/class/alias/enum/reference, and bounded nested list/object summaries, EXIF 3.1 correction/noise labels, version/firmware-style value formatting for selected EXIF/Nikon/Olympus/native RAF contexts, selected Sony ILCE-7RM6 correction-offset routing, Fujifilm flash white-balance naming, Apple/FLIR/JVC/GE/Reconyx/Microsoft/Nintendo/Sanyo scalar MakerNote labels, current Canon RF/Nikon Z lens labels, an ambiguous Pentax Sigma/Samsung/Tokina lens-family label, EXIF/XMP GPS timestamp composites, EXIF `OffsetTime*`/`SubSecTime*` date composition with normalized-instant conflict checks, separate camera/destination/shown/created GPS roles with scope-aware structured-location conflicts, language-aware descriptive roles, legacy editorial duplicate reconciliation, accessibility/taxonomy/registry/image-region/document-identity/lineage/history semantics, structured creator-contact/event/person/organization/product/artwork/rights/license/release/end-user/image-creator/image-supplier/image-asset/controlled-vocabulary/registry/image-region/resource-reference/resource-event/pantry records, independent privacy/policy sensitivity, computational, thermal, stitch/panorama capture state, and vendor-private fields. | High, about 98-99%. |
+| Interpretation | Normalize names and values, group entries by meaning, and classify source-bound data such as RAW crop, exposure adjustment, color/profile/source-color-transform evidence, RAW curves/linearity metadata with descriptor-backed compressed-storage applicability, lens-correction, sensor, BMFF brand/item-property associations and rollups including `avio` AVIF brands, item groups, item semantic counts, whole-scene policy hints, graph-component summaries with per-component roles, member item IDs, semantic composition, typed relation counts, bounded `grid`/`iovl`/`iden` construction semantics with recursive item-offset descriptors and graph-cycle/source validation, bounded complete `tili` configuration/reference/offset-table interpretation, `container_graph` concepts, primary item properties, primary metadata-carrier flags, primary sidecar and scene summaries, and display-transform summaries, JUMBF labels, Photoshop IRB embedded carriers plus fixed-layout, XML/text, working-path and numbered clipping-path records, byte-count, descriptor-header, scalar/class/alias/enum/reference, and bounded nested list/object summaries, EXIF 3.1 correction/noise labels, version/firmware-style value formatting for selected EXIF/Nikon/Olympus/native RAF contexts, selected Sony ILCE-7RM6 correction-offset routing, Fujifilm flash white-balance naming, Apple/FLIR/JVC/GE/Reconyx/Microsoft/Nintendo/Sanyo scalar MakerNote labels, current Canon RF/Nikon Z lens labels, an ambiguous Pentax Sigma/Samsung/Tokina lens-family label, EXIF/XMP GPS timestamp composites, EXIF `OffsetTime*`/`SubSecTime*` date composition with normalized-instant conflict checks, separate camera/destination/shown/created GPS roles with scope-aware structured-location conflicts, language-aware descriptive roles, legacy editorial duplicate reconciliation, accessibility/taxonomy/registry/image-region/document-identity/lineage/history semantics, structured creator-contact/event/person/organization/product/artwork/rights/license/release/end-user/image-creator/image-supplier/image-asset/controlled-vocabulary/registry/image-region/image-region-boundary/resource-reference/resource-event/manifest-item/version/pantry records, explicit image-region shape and coordinate-unit contracts, independent privacy/policy sensitivity, computational, thermal, stitch/panorama capture state, and vendor-private fields. | High, about 98-99%. |
 | Query | Find entries by name, fuzzy term, or semantic group, then expose normalized query candidates, structured interpretation records, bounded cross-family concept resolutions, transfer hints, sensitivity, and conflict flags for crop/border/active-area, exposure/gain, color/WB/profile/source-color-transform, orientation, date/time, GPS, descriptive fields including contact/event/person/organization/product/artwork/rights/license/release, editorial, accessibility, taxonomy, registry, image-region, document-identity, document-lineage, and document-history semantics, lens-correction, computational/thermal/stitch, RAW/source-processing fields, and BMFF derived-image construction and tiled-image configuration evidence across standard and vendor metadata. | High, about 98-99%. |
 | 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%. |

docs/host_integration.md

@@ -95,12 +95,22 @@ additive collections retain distinct values. Structured
 members carry both a `record_kind` and `record_scope`, such as `person` plus
 `Person[1]`, so hosts can keep associated names, identifiers, descriptions,
 contacts, constraints, and release records together.
+IPTC image boundaries use the `image_region_boundary` record kind. A complete
+boundary adds a `region_boundary` candidate with explicit
+`image_region_shape` and `image_region_coordinate_unit` fields. Rectangle
+values use `rect` as x, y, width, height; circles use a three-value x, y,
+radius vector; polygons use a flattened x, y `vector_set` plus scoped `vec2`
+vertex candidates. OpenMeta does not synthesize geometry when the shape, unit,
+or required coordinates are incomplete, but valid individual numeric fields
+remain queryable. Pixel and relative coordinates are not interchangeable:
+hosts must use source and target image specifications to transform or validate
+them before transfer.
 Treat this as an inspection and policy input rather than an automatic metadata
 rewrite decision; source-bound color, lens, and RAW-processing values still need
 rendered-transfer safety filtering. Document identity, registry, XMP Media
-Management lineage/history, and pantry identity are source-bound; image-region
-records require target image specifications because their meaning is tied to
-the source image. Each candidate also carries a transfer
+Management manifest/version/lineage/history records, and pantry identity are
+source-bound; image-region records require target image specifications because
+their meaning is tied to the source image. Each candidate also carries a transfer
 hint: `safe`, `source_bound`, `rendered_unsafe`, or
 `requires_target_image_spec`, plus `compatible_file_safe` and
 `rendered_image_safe` booleans for host UI and preflight policy. For transfer

docs/interpretation_status.md

@@ -33,7 +33,7 @@ explicit outcome:
 | --- | --- | --- | --- |
 | Standard EXIF/TIFF/DNG tag names and typed values | Standard tag names, common scalar/vector values, DNG crop/color/exposure/RAW-processing fields, GeoTIFF key names, EXIF 3.1 learning/development/correction/noise tag names, and common EXIF/TIFF/DNG numeric value-name helpers are available. Exposure time, aperture, ISO sensitivity, exposure bias, exposure program/mode, gain, correction/noise status values, and raw exposure-adjustment records now flow into concept candidates or stable display helpers where appropriate. | High, about 93-96%. | More enum-style human-readable values and richer conflict handling between duplicated families. |
 | ICC profiles | ICC header/tag table decode plus interpreted `desc`, text, signatures, XYZ, curves, named-color, measurement, viewing-condition, MFT/MAB/MBA, numeric array, and malformed/limit handling. | High, about 90-95%. | Full color-management policy remains host-owned; OpenMeta interprets profile metadata, not rendered color transforms. |
-| IPTC-IIM and portable XMP | IPTC datasets and XMP properties decode into typed entries, bounded EXIF/IPTC-to-XMP projection exists for transfer/writeback, and common descriptive EXIF/IPTC/XMP concepts such as title/headline, description/caption, creator/author, keywords/subject, rights/license, credit/source, IPTC created date/time, and IPTC digital-creation date/time are queryable with source-entry provenance. The `Descriptive` concept also reconciles legacy IPTC/Photoshop urgency, category, supplemental-category, instructions, creator-title, transmission-reference, and caption-writer pairs; interprets IPTC Core accessibility/taxonomy fields, IPTC Extension controlled-vocabulary, registry, and image-region entity records, XMP document identity, and XMP Media Management resource-reference, ingredient, history, manifest-reference, and bounded pantry records; and groups structured creator contacts, events, people, organizations, products, artwork/objects, encoded rights expressions, PLUS parties/assets/license policy, and model/property releases with record kind, record scope, language, transfer hint, and independent sensitivity. | High, about 98-99%. | Non-equivalent legacy workflow fields, image-region boundary normalization, arbitrary pantry payloads, and remaining version/manifest wrapper fields remain bounded. |
+| IPTC-IIM and portable XMP | IPTC datasets and XMP properties decode into typed entries, bounded EXIF/IPTC-to-XMP projection exists for transfer/writeback, and common descriptive EXIF/IPTC/XMP concepts such as title/headline, description/caption, creator/author, keywords/subject, rights/license, credit/source, IPTC created date/time, and IPTC digital-creation date/time are queryable with source-entry provenance. The `Descriptive` concept also reconciles legacy IPTC/Photoshop urgency, category, supplemental-category, instructions, creator-title, transmission-reference, and caption-writer pairs; interprets IPTC Core accessibility/taxonomy fields, IPTC Extension controlled-vocabulary, registry, image-region entity records, and rectangle/circle/polygon boundary geometry with explicit pixel/relative units, XMP document identity, and XMP Media Management resource-reference, ingredient, history, manifest-item/reference, version/event, and bounded pantry records; and groups structured creator contacts, events, people, organizations, products, artwork/objects, encoded rights expressions, PLUS parties/assets/license policy, and model/property releases with record kind, record scope, language, transfer hint, and independent sensitivity. | High, about 98-99%. | Non-equivalent legacy workflow fields and deliberately unmodeled arbitrary pantry payloads remain bounded. |
 | Orientation | EXIF/TIFF orientation query, LibRaw flip mapping, generic orientation helpers for index, rotation degrees, mirrored state, dimension swap, rotation-only fallback, human-readable labels, and EXIF-vs-XMP conflict reporting in the LibRaw bridge. | High, about 90-95%. | Higher-level policy for resolving container and host pixel-orientation state remains host-specific. |
 | Geometry, crop, active area, and borders | DNG crop/active-area/masked-area tags, Phase One/Leaf geometry, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Nikon Capture crop bounds, Sony panorama crop margins, canonical border margins, vendor RAW-processing geometry buckets, and fuzzy crop/border-style paths are queryable. | High, about 88-92%. | More vendor-specific normalized rectangles and stronger output contracts for ambiguous multi-tag geometry. |
 | Exposure and gain | Standard EXIF exposure time, f-number, exposure program/mode, photographic sensitivity, exposure bias, exposure index, gain control, selected DNG baseline/raw-preview gain fields, matching XMP paths, and selected decoded vendor/MakerNote exposure names are queryable and promoted into cross-family exposure roles. Standard EXIF exposure program/mode and gain-control values plus selected Canon/Nikon/Sony/Fujifilm/Pentax/Olympus/Panasonic/Phase One/Kodak/Minolta/Sigma/Samsung/Ricoh MakerNote values carry human-readable labels where stable. Capture exposure facts are marked safe, while raw/DNG exposure adjustments are marked unsafe for rendered-image transfer. | Medium-high, about 91-94%. | More vendor MakerNote exposure print conversions and richer per-vendor exposure/gain labels. |
@@ -63,9 +63,8 @@ outputs.
    independently authored conformance files as they become available.
 2. Broaden transfer diagnostic policy coverage now that stable message tokens
    and localizable argument tokens are available for GUI workflows.
-3. Interpret remaining non-equivalent legacy workflow fields, image-region
-   boundary geometry, and bounded XMP Media Management version/manifest
-   wrapper fields without guessing at arbitrary pantry payloads.
+3. Interpret remaining non-equivalent legacy workflow fields and add pantry
+   payload semantics only where a validated, bounded schema exists.
 4. Expand the remaining unambiguous MakerNote long tail: encrypted/custom
    settings, per-model firmware formulas outside currently supported
    formatter contexts, remaining live-vendor scalar/string-coded fields, and

docs/sphinx/development.rst

@@ -67,8 +67,9 @@ model should stay compact:
        document-identity/lineage/history semantics,
        structured creator-contact/event/person/organization/product/artwork/
        rights/license/release/end-user/image-creator/image-supplier/image-asset/
-       controlled-vocabulary/registry/image-region/resource-reference/
-       resource-event/pantry records,
+       controlled-vocabulary/registry/image-region/image-region-boundary/
+       resource-reference/resource-event/manifest-item/version/pantry records,
+       explicit image-region shape and coordinate-unit contracts,
        and independent privacy/policy sensitivity,
        computational, thermal, stitch/panorama capture state, and
        vendor-private fields.

docs/sphinx/host_integration.rst

@@ -100,14 +100,24 @@ delivered-image fields. Scalar
 conflicts are isolated by normalized language and structured location scope;
 additive collections retain distinct values. Structured
 members carry both a ``record_kind`` and ``record_scope``, such as ``person``
-plus ``Person[1]``, so hosts can keep associated values together. Treat this as
-an inspection and policy input
+plus ``Person[1]``, so hosts can keep associated values together. IPTC image
+boundaries use the ``image_region_boundary`` record kind. A complete boundary
+adds a ``region_boundary`` candidate with explicit ``image_region_shape`` and
+``image_region_coordinate_unit`` fields. Rectangle values use ``rect`` as x,
+y, width, height; circles use a three-value x, y, radius vector; polygons use
+a flattened x, y ``vector_set`` plus scoped ``vec2`` vertex candidates.
+OpenMeta does not synthesize geometry when the shape, unit, or required
+coordinates are incomplete, but valid individual numeric fields remain
+queryable. Pixel and relative coordinates are not interchangeable: hosts must
+use source and target image specifications to transform or validate them
+before transfer. Treat this as an inspection and policy input
 rather than an automatic
 metadata rewrite decision; source-bound color, lens, and RAW-processing values
 still need rendered-transfer safety filtering. Document identity, registry,
-XMP Media Management lineage/history, and pantry identity are source-bound;
-image-region records require target image specifications because their meaning
-is tied to the source image. Each candidate also carries a
+XMP Media Management manifest/version/lineage/history records, and pantry
+identity are source-bound; image-region records require target image
+specifications because their meaning is tied to the source image. Each
+candidate also carries a
 transfer hint: ``safe``, ``source_bound``, ``rendered_unsafe``, or
 ``requires_target_image_spec``, plus ``compatible_file_safe`` and
 ``rendered_image_safe`` booleans for host UI and preflight policy. For transfer