Add BMFF item semantics and color summaries

Introduce item type-name and semantic labeling plus bounded primary color/profile summaries for BMFF handling. Adds ColrProp and ItemSemantic (nclx/nclc/rICC/prof and profile byte counts) and classification/emission logic in src/openmeta/bmff_fields_decode.cc, emitting fields like item.type_name, item.semantic, primary.color_type, primary.nclx_*, and primary.color_profile_bytes. Updates and expands unit tests to cover nclx, rICC profiles, short/ignored colr boxes, and item semantic labeling. Documentation, CHANGES.md, and VERSION bumped to 0.4.23 to reflect the new features.

Author: ssh4net

CHANGES.md

@@ -1,5 +1,18 @@
 # OpenMeta Changes
 
+## 0.4.23 - 2026-05-21
+
+Changes compared with `0.4.22`.
+
+### Added
+
+- Added BMFF item type-name and semantic labels for image, EXIF, XMP, JUMBF,
+  C2PA, ICC profile, URI, thumbnail, derived-image, auxiliary, and
+  content-description items.
+- Added bounded primary BMFF color/property summaries for `colr` `nclx`,
+  `nclc`, `rICC`, and `prof` properties, including ICC profile byte counts and
+  nclx color fields.
+
 ## 0.4.22 - 2026-05-21
 
 Changes compared with `0.4.21`.

VERSION

@@ -1 +1 @@
-0.4.22
+0.4.23

docs/development.md

@@ -658,7 +658,53 @@ This policy surface is intentionally marked draft and may be refined.
   plus `format_icc_tag_display_value(...)` for shared CLI/Python rendering)
 - ISO-BMFF (HEIF/AVIF/CR3) container-derived fields: `src/openmeta/bmff_fields_decode.cc`
   - Emitted during `simple_meta_read(...)` as `MetaKeyKind::BmffField` entries.
-  - Current fields: `ftyp.*`, primary item properties (`meta.primary_item_id`, `primary.width`, `primary.height`, `primary.rotation_degrees`, `primary.mirror` from `pitm` + `iprp/ipco ispe/irot/imir` + `ipma`), item-info rows from `iinf/infe` (`item.info_count`, `item.id`, `item.type`, `item.name`, `item.content_type`, `item.content_encoding`, `item.uri_type`; emitted even when `meta` has no `pitm`, plus `primary.item_type`, `primary.item_name`, `primary.content_type`, `primary.content_encoding`, `primary.uri_type` aliases when `pitm` is present), bounded `iref.*` relation fields (`ref_type`, `ref_type_name`, `from_item_id`, `to_item_id`, `edge_count`), typed derived relation rows (`iref.auxl.*`, `iref.dimg.*`, `iref.thmb.*`, `iref.cdsc.*`, and other safe ASCII FourCC relation families), per-type relation counters (`iref.<type>.edge_count`) and per-type unique source/target counters (`iref.<type>.from_item_unique_count`, `iref.<type>.to_item_unique_count`), per-type graph-summary aliases (`iref.graph.<type>.edge_count`, `iref.graph.<type>.from_item_unique_count`, `iref.graph.<type>.to_item_unique_count`), typed relation item summaries (`iref.<type>.item_count`, `iref.<type>.item_id`, `iref.<type>.item_out_edge_count`, `iref.<type>.item_in_edge_count`), relation-graph summaries (`iref.item_count`, `iref.from_item_unique_count`, `iref.to_item_unique_count`, row-wise `iref.item_id` + `iref.item_out_edge_count` + `iref.item_in_edge_count`), bounded primary-linked image-role rows (`primary.linked_item_role_count`, row-wise `primary.linked_item_id` + `primary.linked_item_type` + `primary.linked_item_name` + `primary.linked_item_role` when `iinf/infe` data exists), and `auxC`-based aux semantics (`aux.item_count`, `aux.item_id`, `aux.semantic`, `aux.type`, `aux.subtype_hex`, `aux.subtype_kind`, `aux.subtype_text`, `aux.subtype_uuid`, `aux.subtype_u32`, `aux.subtype_u64`, `aux.alpha_count`, `aux.depth_count`, `aux.disparity_count`, `aux.matte_count`, `primary.auxl_count`, `primary.auxl_semantic`, `primary.depth_count`, `primary.depth_item_id`, `primary.alpha_count`, `primary.alpha_item_id`, `primary.disparity_count`, `primary.disparity_item_id`, `primary.matte_count`, `primary.matte_item_id`, `primary.dimg_count`, `primary.dimg_item_id`, `primary.thmb_count`, `primary.thmb_item_id`, `primary.cdsc_count`, `primary.cdsc_item_id`, ...). Full multi-image scene modeling beyond that primary-linked role surface is still follow-up work.
+  - Current fields: `ftyp.*`, primary item properties
+    (`meta.primary_item_id`, `primary.width`, `primary.height`,
+    `primary.rotation_degrees`, `primary.mirror` from `pitm` + `iprp/ipco
+    ispe/irot/imir` + `ipma`), primary `colr` summaries
+    (`primary.color_type`, `primary.color_type_name`,
+    `primary.nclx_colour_primaries`,
+    `primary.nclx_transfer_characteristics`,
+    `primary.nclx_matrix_coefficients`, `primary.nclx_full_range_flag`, and
+    `primary.color_profile_bytes` for bounded ICC profile carriers), item-info
+    rows from `iinf/infe` (`item.info_count`, `item.id`, `item.type`,
+    `item.type_name`, `item.semantic`, `item.name`, `item.content_type`,
+    `item.content_encoding`, `item.uri_type`; emitted even when `meta` has no
+    `pitm`, plus `primary.item_type`, `primary.item_type_name`,
+    `primary.item_semantic`, `primary.item_name`, `primary.content_type`,
+    `primary.content_encoding`, `primary.uri_type` aliases when `pitm` is
+    present), bounded `iref.*` relation fields (`ref_type`, `ref_type_name`,
+    `from_item_id`, `to_item_id`, `edge_count`), typed derived relation rows
+    (`iref.auxl.*`, `iref.dimg.*`, `iref.thmb.*`, `iref.cdsc.*`, and other safe
+    ASCII FourCC relation families), per-type relation counters
+    (`iref.<type>.edge_count`) and per-type unique source/target counters
+    (`iref.<type>.from_item_unique_count`,
+    `iref.<type>.to_item_unique_count`), per-type graph-summary aliases
+    (`iref.graph.<type>.edge_count`,
+    `iref.graph.<type>.from_item_unique_count`,
+    `iref.graph.<type>.to_item_unique_count`), typed relation item summaries
+    (`iref.<type>.item_count`, `iref.<type>.item_id`,
+    `iref.<type>.item_out_edge_count`, `iref.<type>.item_in_edge_count`),
+    relation-graph summaries (`iref.item_count`,
+    `iref.from_item_unique_count`, `iref.to_item_unique_count`, row-wise
+    `iref.item_id` + `iref.item_out_edge_count` +
+    `iref.item_in_edge_count`), bounded primary-linked image-role rows
+    (`primary.linked_item_role_count`, row-wise `primary.linked_item_id` +
+    `primary.linked_item_type` + `primary.linked_item_type_name` +
+    `primary.linked_item_name` + `primary.linked_item_semantic` +
+    `primary.linked_item_role` when `iinf/infe` data exists), and
+    `auxC`-based aux semantics (`aux.item_count`, `aux.item_id`,
+    `aux.semantic`, `aux.type`, `aux.subtype_hex`, `aux.subtype_kind`,
+    `aux.subtype_text`, `aux.subtype_uuid`, `aux.subtype_u32`,
+    `aux.subtype_u64`, `aux.alpha_count`, `aux.depth_count`,
+    `aux.disparity_count`, `aux.matte_count`, `primary.auxl_count`,
+    `primary.auxl_semantic`, `primary.depth_count`, `primary.depth_item_id`,
+    `primary.alpha_count`, `primary.alpha_item_id`,
+    `primary.disparity_count`, `primary.disparity_item_id`,
+    `primary.matte_count`, `primary.matte_item_id`, `primary.dimg_count`,
+    `primary.dimg_item_id`, `primary.thmb_count`, `primary.thmb_item_id`,
+    `primary.cdsc_count`, `primary.cdsc_item_id`, ...). Full multi-image scene
+    modeling beyond that primary-linked role surface is still follow-up work.
   - `auxC` subtype interpretation now includes `ascii_z` and `u64be` kinds in addition to earlier numeric/FourCC/UUID/ASCII forms.
   - Parsing is intentionally bounded (depth/box count caps) and ignores unknown properties.
 - JUMBF/C2PA decode (draft phase-3): `src/openmeta/jumbf_decode.cc`

docs/interpretation_status.md

@@ -39,7 +39,7 @@ explicit outcome:
 | Color, white balance, and matrices | DNG color/calibration/reduction/forward matrix groups, white-balance vector groups, ICC metadata, RAW color/source-processing safety buckets, transfer hints, per-family grouped vendor color/WB candidates, long-tail camera-to-XYZ/RGB, style/color, and white-balance gain aliases, and cross-family concept candidates with full grouped value vectors are identified. Matrix/vector groups require numeric payloads with conservative minimum shapes before promotion. | Medium-high, about 82-90%. | Deeper camera/vendor color science interpretation is intentionally conservative, especially for rendered-image transfer. |
 | Lens correction and RAW processing | Lens-correction groups, black/white levels, linearization, CFA/sensor layout, raw-storage identifiers, vendor RAW/source-processing buckets, creative/picture style, film simulation, dynamic-range, optical correction, and raw-development aliases, per-family vendor raw-storage/sensor/source-processing table candidates, transfer hints, transfer diagnostics, and concept candidates with grouped table/vector values are classified for query and transfer safety. Lens-correction grouped tables require numeric payloads before promotion. | Medium-high, about 82-89%. | Long-tail per-model correction tables and richer numeric normalization. |
 | 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, stitch/panorama, pixel-shift, multi-shot, composite, auto-lighting, RAW crop/active-area, source color-transform, source style/rendering aliases, lens-correction, raw-level processing data, and Phase One/Leaf RAW-processing fields handled by direct classification plus dedicated normalized helpers. Classified multi-field vendor groups now surface as grouped query/interpretation candidates where safe to expose structurally. | Medium-high, about 83-90%. | 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. |
+| BMFF item graph, HEIF/AVIF/CR3, JUMBF, and C2PA | BMFF derived fields, item-info rows, item type/semantic labels for common metadata carriers, bounded relations, primary-linked roles, aux semantics, primary color/profile property summaries, and draft C2PA/JUMBF structural fields are exposed. | Medium, about 63-73%. | 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, including resolution/version/print data, alpha names/identifiers, captions, QuickMask info, URL/list data, channel options, and clipping-path names. | Medium, about 62-72%. | 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, Fujifilm RAF raw crop/zoom rectangles, Canon/Nikon/Sony crop and border patterns, border margins, exposure/gain roles, selected vendor/MakerNote exposure-name aliases, per-family grouped vendor records, descriptive EXIF/IPTC/XMP concepts, expanded source color/style/lens/source-processing aliases, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and bounded cross-family concept resolution for orientation, date/time, exposure/gain, color/profile, GPS, geometry, lens-correction, and RAW-processing with parsed date/time fields, timezone/precision classification, combined GPS timestamps, GPS altitude-reference state and display token, canonical geometry origin/size/rect/margins, normalized exposure values, shape-checked grouped value vectors, transfer hints, rendered/compatible safety booleans, and tolerance-aware GPS/exposure/color/geometry conflicts. | Medium-high, about 79-85%. | More long-tail per-model concept aliases and richer localized policy wording. |
 | 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, with concept-level diagnostics that report keep/drop/requires-target-image-spec actions, severity, and role-specific default message text before prepare. | High, about 89-93%. | More per-family policy tests and optional host localization hooks. |

docs/metadata_support.md

@@ -140,10 +140,14 @@ OpenMeta now has a bounded semantic model on top of raw item discovery:
 - `ftyp.*`
 - primary item properties
 - `iinf/infe` item-info rows
+- item type-name and semantic labels for EXIF, XMP, JUMBF, C2PA, ICC profile,
+  image, URI, auxiliary, thumbnail, derived-image, and content-description items
 - typed `iref.<type>.*` rows
 - graph summaries
 - `auxC`-typed auxiliary semantics
 - bounded primary-linked image-role fields
+- primary `colr` summaries for `nclx`/`nclc` color fields and ICC profile-size
+  carriers
 
 This is intentionally smaller than a full QuickTime/BMFF semantic model.
 

docs/sphinx/interpretation_status.rst

@@ -154,9 +154,11 @@ Coverage matrix
      - 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%.
+     - BMFF derived fields, item-info rows, item type/semantic labels for
+       common metadata carriers, bounded relations, primary-linked roles, aux
+       semantics, primary color/profile property summaries, and draft
+       C2PA/JUMBF structural fields are exposed.
+     - Medium, about 63-73%.
      - Full BMFF scene modeling and full C2PA manifest/policy semantics.
    * - Photoshop IRB
      - Raw resources are preserved and a bounded interpreted subset is decoded