Enhance Photoshop IRB decode: borders, samplers

Add bounded interpretation for additional Photoshop IRB resources: BorderInformation, BackgroundColor, two-byte EffectiveBW, ColorSamplersResource/Resource2, and descriptor-header summaries for several descriptor-backed resources. Implements new decoding helpers (border, background color, effective BW, color samplers, descriptor header) and wires them into the main IRB decoder; includes unit tests exercising the new paths. Update public docs, API stability notes, metadata support, sphinx sources, CHANGES, and bump VERSION to 0.4.33 to reflect the expanded interpreted subset.

Author: ssh4net

CHANGES.md

@@ -1,5 +1,24 @@
 # OpenMeta Changes
 
+## 0.4.33 - 2026-05-25
+
+Changes compared with `0.4.32`.
+
+### Added
+
+- Added bounded Photoshop IRB interpretation for `BorderInformation`,
+  `BackgroundColor`, and two-byte `EffectiveBW` payloads.
+- Added Photoshop IRB color-sampler header and record interpretation for
+  `ColorSamplersResource` and `ColorSamplersResource2`.
+- Added descriptor-version and descriptor-byte-count summaries for descriptor
+  backed Photoshop IRB resources such as `LayerComps`, `MeasurementScale`,
+  `TimelineInfo`, `PrintInfo2`, `PrintStyle`, and `PathSelectionState`.
+
+### Changed
+
+- Public interpretation/support docs now describe the expanded Photoshop IRB
+  fixed-layout and descriptor-header subset.
+
 ## 0.4.32 - 2026-05-25
 
 Changes compared with `0.4.31`.

VERSION

@@ -1 +1 @@
-0.4.32
+0.4.33

docs/api_stability.md

@@ -24,7 +24,7 @@ different status.
 | `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. |
 | 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. |
-| Photoshop IRB decode: `decode_photoshop_irb(...)`, `measure_photoshop_irb(...)` | `openmeta/photoshop_irb_decode.h` | Experimental | Bounded resource traversal with stable raw resource preservation behavior, but the interpreted subset can still grow. Current interpretation includes fixed-layout resource fields, display/grid/thumbnail headers, embedded ICC/EXIF/EXIF2/XMP byte-count fields, and optional embedded IPTC-IIM, XMP, and ICC payload decode. |
+| Photoshop IRB decode: `decode_photoshop_irb(...)`, `measure_photoshop_irb(...)` | `openmeta/photoshop_irb_decode.h` | Experimental | Bounded resource traversal with stable raw resource preservation behavior, but the interpreted subset can still grow. Current interpretation includes fixed-layout resource fields, display/grid/thumbnail/color-sampler headers, descriptor-header summaries, embedded ICC/EXIF/EXIF2/XMP byte-count fields, and optional embedded IPTC-IIM, XMP, and ICC payload decode. |
 | 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/profile/source-color-transform, lens correction, orientation, descriptive EXIF/IPTC/XMP fields, and RAW/source-processing metadata across standard tags, selected DNG tags, EXIF color-space evidence, ICC header/tag entries, XMP ICC/profile/color-space fields, XMP camera RAW profile/look/tone-curve fields, PNG profile text carriers, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Nikon Capture crop bounds, Sony panorama crop margins, selected decoded vendor/MakerNote exposure names, 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, source-processing buckets, and per-family vendor MakerNote/RAW white-balance, source-color-transform, raw-storage, sensor, computational, thermal, stitch/panorama, and source-processing groups. Matrix/vector/table groups are promoted only when the available numeric payloads meet conservative minimum shapes, so malformed color matrices, white-balance vectors, and lens-correction records remain per-entry inspection data instead of becoming normalized groups. Long-tail source color/style aliases such as camera-to-XYZ/RGB matrices, creative/picture style, film simulation, dynamic-range, optical-correction, and raw-development terms are classified for query and transfer-policy inspection; camera RAW profiles, looks, tone curves, and vendor source color tables use the explicit `source_color_transform` semantic, while computational, thermal, and stitch/panorama fields use explicit source-processing subroles. 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 including Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns, exposure/gain, color/white-balance/profile/source-color-transform records, lens-correction, RAW/source-processing records including computational, thermal, and stitch/panorama subroles, and grouped vendor-family table/vector records where classification supports them. 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, full normalized value vectors, transfer hints, normalized date/time fields, date/time precision, timezone kind, normalized geometry fields, normalized exposure values, and same-role conflicts for orientation, date/time, exposure/gain, color/profile/source-color-transform, GPS, geometry, lens-correction, and RAW-processing evidence across EXIF, XMP, IPTC, ICC, PNG text, and query-backed interpretation records where applicable. Exposure candidates cover exposure time, aperture, ISO sensitivity, exposure bias, exposure program, gain, and raw exposure-adjustment roles across standard EXIF/DNG/XMP evidence and selected decoded vendor/MakerNote exposure names; standard EXIF exposure program and gain-control values include human-readable labels; capture exposure facts are safe, while raw/DNG exposure adjustments stay rendered-unsafe. Geometry candidates cover crop, active area, border, and sensor geometry with canonical origin, size, rect, and margin fields when available, including normalized DNG, Phase One/Leaf, Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns. Candidate transfer hints distinguish `safe`, `source_bound`, `rendered_unsafe`, and `requires_target_image_spec` evidence, with compatible-file and rendered-image safety booleans. Color/white-balance, source-color-transform, lens-correction, and RAW-processing concepts preserve grouped matrix/vector/table values for host inspection; source-bound color transforms are marked rendered-unsafe and computational, thermal, and stitch/panorama RAW-processing roles are marked source-bound. 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; `metadata_concept_gps_altitude_reference_name(...)` provides a stable display token for the reference code. 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. |

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, lens-correction, sensor, BMFF item-property associations and primary item properties, JUMBF labels, Photoshop IRB embedded carriers and fixed-layout headers, computational, thermal, stitch/panorama capture state, and vendor-private fields. | Medium-high, about 90%. |
+| 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, lens-correction, sensor, BMFF item-property associations and primary item properties, JUMBF labels, Photoshop IRB embedded carriers plus fixed-layout and descriptor-header summaries, computational, thermal, stitch/panorama capture state, and vendor-private fields. | Medium-high, about 90%. |
 | 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, and conflict flags for crop/border/active-area, exposure/gain, color/WB/profile/source-color-transform, orientation, date/time, GPS, lens-correction, computational/thermal/stitch, and RAW/source-processing fields across standard and vendor metadata. | Medium-high, about 77-83%. |
 | 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%. |
@@ -899,20 +899,24 @@ Internal helper conventions (used by vendor decoders):
   `Entry` provenance and resolve it only on explicit display surfaces through
   `exif_entry_name(..., ExifTagNamePolicy::ExifToolCompat)`.
 - Photoshop IRB stays lossless at the raw-resource layer (`PhotoshopIrb`).
-  Add interpreted IRB fields only for fixed-layout resources and emit them as
-  separate `PhotoshopIrbField` entries instead of weakening the raw payload
-  surface. The current bounded interpreted subset includes `ResolutionInfo`,
-  `AlphaChannelsNames`, `DisplayInfo`, `PStringCaption`, `VersionInfo`,
-  `PrintFlags`, `EffectiveBW`, `QuickMaskInfo`, `TargetLayerID`,
-  `LayersGroupInfo`, `JPEG_Quality`, `GridGuidesInfo`, `CopyrightFlag`,
-  `URL`, `GlobalAngle`, `Watermark`, `ICC_Untagged`, `EffectsVisible`,
-  `IDsBaseValue`, `UnicodeAlphaNames`,
+  Add interpreted IRB fields only for fixed-layout resources or bounded
+  descriptor-header summaries and emit them as separate `PhotoshopIrbField`
+  entries instead of weakening the raw payload surface. The current bounded
+  interpreted subset includes `ResolutionInfo`,
+  `AlphaChannelsNames`, `DisplayInfo`, `PStringCaption`, `BorderInformation`,
+  `BackgroundColor`, `VersionInfo`, `PrintFlags`, `EffectiveBW`,
+  `QuickMaskInfo`, `TargetLayerID`, `LayersGroupInfo`, `JPEG_Quality`,
+  `GridGuidesInfo`, `CopyrightFlag`, `URL`, `GlobalAngle`,
+  `ColorSamplersResource`, `ColorSamplersResource2`, `Watermark`,
+  `ICC_Untagged`, `EffectsVisible`, `IDsBaseValue`, `UnicodeAlphaNames`,
   `IndexedColorTableCount`, `TransparentIndex`, `GlobalAltitude`,
   `SliceInfo`, `WorkflowURL`, `AlphaIdentifiers`, `URL_List`, `IPTCDigest`,
-  `PrintScaleInfo`, `PixelInfo`, `PhotoshopBGRThumbnail`,
-  `PhotoshopThumbnail`, `LayerSelectionIDs`,
-  `LayerGroupsEnabledID`, `ChannelOptions`, `PrintFlagsInfo`, and
-  `ClippingPathName`.
+  `PrintScaleInfo`, `PixelInfo`, descriptor-header summaries for
+  `LayerComps`, `MeasurementScale`, `TimelineInfo`, `SheetDisclosure`,
+  `OnionSkins`, `CountInfo`, `PrintInfo2`, `PrintStyle`,
+  `PathSelectionState`, and `OriginPathInfo`, `PhotoshopBGRThumbnail`,
+  `PhotoshopThumbnail`, `LayerSelectionIDs`, `LayerGroupsEnabledID`,
+  `ChannelOptions`, `PrintFlagsInfo`, and `ClippingPathName`.
 - Legacy 8-bit Photoshop text stays opt-in and explicit. The IRB decoder
   exposes a bounded `PhotoshopIrbStringCharset` policy and currently uses it
   only for `AlphaChannelsNames`, `PStringCaption`, and `ClippingPathName`,

docs/interpretation_status.md

@@ -40,7 +40,7 @@ explicit outcome:
 | 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, raw-development, computational, thermal, and stitch/panorama aliases, per-family vendor raw-storage/sensor/computational/thermal/stitch/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 83-90%. | 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, and computational/thermal/stitch source-processing roles stay distinct for host policy. | Medium-high, about 84-91%. | 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, item type/semantic labels for common metadata carriers, bounded `ipma` item-property association rows, bounded relations, primary-linked roles, aux semantics, primary color/profile property summaries, primary pixel aspect ratio, primary pixel component bit depth, clean-aperture rationals, JUMBF box labels, and draft C2PA/JUMBF structural fields are exposed. | Medium, about 69-79%. | 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, display info, grid/guide info, alpha names/identifiers, captions, QuickMask info, URL/list data, thumbnail headers, channel options, clipping-path names, embedded ICC/XMP/EXIF resource byte counts, and embedded IPTC/XMP/ICC payload decode where enabled. | Medium, about 70-79%. | Broader resource-specific interpretation. |
+| Photoshop IRB | Raw resources are preserved and a bounded interpreted subset is decoded for fixed-layout resources, including resolution/version/print data, border/background/effective-BW data, display info, grid/guide info, color sampler headers/records, descriptor-header summaries, alpha names/identifiers, captions, QuickMask info, URL/list data, thumbnail headers, channel options, clipping-path names, embedded ICC/XMP/EXIF resource byte counts, and embedded IPTC/XMP/ICC payload decode where enabled. | Medium, about 72-81%. | Broader resource-specific descriptor parsing and long-tail resource 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, explicit color-profile records for EXIF/ICC/XMP/PNG profile carriers, explicit source-color-transform records for camera RAW profiles, looks, tone curves, and vendor source color tables, explicit computational/thermal/stitch source-processing records, 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 82-88%. | 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. |