API Reference¶

This page is generated from the public C++ headers via Doxygen (XML) + Breathe.

struct AppendPreparedJpegJumbfOptions¶

#include <metadata_transfer.h>

Options for explicit raw JUMBF append into a prepared JPEG bundle.

Public Members

bool replace_existing = false¶: If true, remove existing prepared jpeg:app11-jumbf blocks first.

struct ApplyDngSdkMetadataFileOptions¶

#include <dng_sdk_adapter.h>

File-helper options for DNG SDK adapter entry points.

Public Members

PrepareTransferFileOptions prepare¶

DngSdkAdapterOptions adapter¶

struct ApplyDngSdkMetadataFileResult¶

#include <dng_sdk_adapter.h>

File-helper result for DNG SDK adapter entry points.

Public Members

PrepareTransferFileResult prepared¶

DngSdkAdapterResult adapter¶

struct ApplyTimePatchOptions¶

#include <metadata_transfer.h>

Options for apply_time_patches.

Public Members

bool strict_width = true¶: If true, update value size must match slot width exactly.

bool require_slot = false¶: If true, each requested field must have at least one slot.

struct ApplyTimePatchResult¶

#include <metadata_transfer.h>

Result for apply_time_patches.

Public Members

TransferStatus status = TransferStatus::Ok ¶

uint32_t patched_slots = 0¶

uint32_t skipped_slots = 0¶

uint32_t errors = 0¶

std::string message¶

struct BlockInfo¶

#include <meta_store.h>

Container-block identity used to associate Entry::origin with a source block.

Public Members

uint32_t format = 0¶

uint32_t container = 0¶

uint32_t id = 0¶

struct BlockSpan¶

#include <meta_store.h>

Public Members

uint32_t start = 0¶

uint32_t count = 0¶

struct BmffField¶

#include <meta_key.h>

Public Members

ByteSpan field¶

struct BmffField¶

#include <meta_key.h>

Public Members

std::string_view field¶

class BmffTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for ISO-BMFF metadata item emission.

Public Functions

virtual ~BmffTransferEmitter() = default¶

virtual TransferStatus add_item(uint32_t item_type, std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus add_mime_xmp_item(std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus add_property(uint32_t property_type, std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus close_items() noexcept = 0¶

struct BuildExrAttributeBatchFileOptions¶

#include <exr_adapter.h>

File-helper options for build_exr_attribute_batch_from_file.

Public Members

PrepareTransferFileOptions prepare¶

ExrAdapterOptions adapter¶

struct BuildExrAttributeBatchFileResult¶

#include <exr_adapter.h>

File-helper result for build_exr_attribute_batch_from_file.

Public Members

PrepareTransferFileResult prepared¶

ExrAdapterResult adapter¶

struct BuildInfo¶

#include <build_info.h>

OpenMeta build information.

Values are compiled into the binary at build time.

Public Members

std::string_view version¶: OpenMeta version string (e.g. “0.4.0”).

std::string_view build_timestamp_utc¶: Build timestamp in UTC (ISO-8601), or empty if not recorded.

std::string_view build_type¶: Build type string (e.g. “Release”, “Debug”, “multi-config”).

std::string_view cmake_generator¶: CMake generator used to configure the build (e.g. “Ninja”).

std::string_view system_name¶: Target platform (e.g. “Linux”, “Darwin”, “Windows”).

std::string_view system_processor¶: Target CPU architecture (e.g. “x86_64”, “arm64”).

std::string_view cxx_compiler_id¶: Compiler ID (e.g. “Clang”, “GNU”, “MSVC”).

std::string_view cxx_compiler_version¶: Compiler version string.

std::string_view cxx_compiler¶: Compiler executable path, if available.

bool linkage_static = false¶: True if this binary was built from the static library target.

bool linkage_shared = false¶: True if this binary was built from the shared library target.

bool option_with_zlib = false¶: Whether zlib decompression was enabled at configure time.

bool option_with_brotli = false¶: Whether brotli decompression was enabled at configure time.

bool option_with_expat = false¶: Whether Expat-based XMP parsing was enabled at configure time.

bool option_enable_rapidfuzz = false¶: Whether RapidFuzz-backed metadata query matching was enabled at configure time.

bool has_zlib = false¶: Whether zlib support is compiled in (linked).

bool has_brotli = false¶: Whether brotli support is compiled in (linked).

bool has_expat = false¶: Whether Expat support is compiled in (linked).

bool has_rapidfuzz = false¶: Whether RapidFuzz-backed metadata query matching is compiled in.

struct BuildPreparedC2paBindingResult¶

#include <metadata_transfer.h>

Result for materializing the exact content-binding byte stream.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint64_t written = 0¶

uint32_t errors = 0¶

std::string message¶

class ByteArena¶

#include <byte_arena.h>

Append-only storage for bytes and strings.

Note

ByteSpan values remain meaningful as long as the arena content is not cleared. However, any pointer/span returned by span() may be invalidated by subsequent arena growth (vector reallocation). Do not retain the returned span across arena mutations.

Public Functions

ByteArena() = default¶

void clear() noexcept¶: Discards all stored bytes.

void reserve(size_t size_bytes)¶: Reserves at least size_bytes capacity (may allocate).

ByteSpan append(std::span<const std::byte> bytes)¶: Appends raw bytes and returns a ByteSpan to the stored copy. Returns an empty span if the payload would exceed ByteSpan limits. Source bytes may alias the current arena buffer.

ByteSpan append_string(std::string_view text)¶: Appends the raw bytes of text (no terminator) and returns a span. Returns an empty span if the payload would exceed ByteSpan limits.

ByteSpan allocate(uint32_t size_bytes, uint32_t alignment)¶: Allocates size_bytes with alignment and returns the written span. Returns an empty span if the allocation cannot be represented.

std::span<const std::byte> bytes() const noexcept¶: Returns a view of the full buffer.

std::span<std::byte> bytes_mut() noexcept¶: Returns a mutable view of the full buffer.

std::span<const std::byte> span(ByteSpan view) const noexcept¶: Returns a view for view, or an empty span if out of range.

std::span<std::byte> span_mut(ByteSpan view) noexcept¶: Returns a mutable view for view, or an empty span if out of range.

Private Members

std::vector<std::byte> buffer_¶

struct ByteSpan¶

#include <byte_arena.h>

A span (offset,size) into a ByteArena buffer.

Public Members

uint32_t offset = 0¶

uint32_t size = 0¶

struct CcmField¶

#include <ccm_query.h>

One normalized CCM/white-balance/calibration field.

Public Members

std::string name¶: Canonical field name (e.g. ColorMatrix1).

std::string ifd¶: Source EXIF IFD token (e.g. ifd0).

uint16_t tag = 0¶: Source EXIF tag id.

uint32_t rows = 0¶: Logical row count (matrix/vector layout hint).

uint32_t cols = 0¶: Logical column count (matrix/vector layout hint).

std::vector<double> values¶: Normalized numeric values (row-major for matrices).

struct CcmIssue¶

#include <ccm_query.h>

Validation issue emitted by collect_dng_ccm_fields.

Public Members

CcmIssueSeverity severity = CcmIssueSeverity::Warning ¶

CcmIssueCode code = CcmIssueCode::DecodeFailed ¶

std::string ifd¶

std::string name¶

uint16_t tag = 0¶

std::string message¶

struct CcmQueryLimits¶

#include <ccm_query.h>

Limits for CCM query extraction.

Public Members

uint32_t max_fields = 128U¶

uint32_t max_values_per_field = 256U¶

struct CcmQueryOptions¶

#include <ccm_query.h>

Options for collect_dng_ccm_fields.

Public Members

bool require_dng_context = true¶: Require DNG context marker (DNGVersion) in the source IFD.

bool include_reduction_matrices = true¶: Include ReductionMatrix* tags.

CcmValidationMode validation_mode = CcmValidationMode::DngSpecWarnings ¶: Validation mode for DNG matrix/tag coherency diagnostics.

CcmQueryLimits limits¶

struct CcmQueryResult¶

#include <ccm_query.h>

Query result for collect_dng_ccm_fields.

Public Members

CcmQueryStatus status = CcmQueryStatus::Ok ¶

uint32_t fields_found = 0¶

uint32_t fields_dropped = 0¶

uint32_t issues_reported = 0¶

struct Comment¶

#include <meta_key.h>

Public Members

uint8_t reserved = 0¶

struct Comment¶

#include <meta_key.h>

Public Members

uint8_t reserved = 0¶

struct ContainerBlockRef¶

#include <container_scan.h>

Reference to a metadata payload within container bytes.

All offsets are relative to the start of the full file byte buffer passed to the scanner.

Note

Scanners are intentionally shallow: they locate blocks and annotate compression/chunking but do not decompress or parse the inner formats.

Public Members

ContainerFormat format = ContainerFormat::Unknown ¶

ContainerBlockKind kind = ContainerBlockKind::Unknown ¶

BlockCompression compression = BlockCompression::None ¶

BlockChunking chunking = BlockChunking::None ¶

uint64_t outer_offset = 0¶

uint64_t outer_size = 0¶

uint64_t data_offset = 0¶

uint64_t data_size = 0¶

uint32_t id = 0¶

uint32_t part_index = 0¶

uint32_t part_count = 0¶

uint64_t logical_offset = 0¶

uint64_t logical_size = 0¶

uint64_t group = 0¶

uint32_t aux_u32 = 0¶

union Data¶

#include <meta_key.h>

Public Functions

inline Data() noexcept¶

Public Members

struct openmeta::MetaKey::Data::ExifTag exif_tag¶

struct openmeta::MetaKey::Data::Comment comment¶

struct openmeta::MetaKey::Data::ExrAttribute exr_attribute¶

struct openmeta::MetaKey::Data::IptcDataset iptc_dataset¶

struct openmeta::MetaKey::Data::XmpProperty xmp_property¶

struct openmeta::MetaKey::Data::IccHeaderField icc_header_field¶

struct openmeta::MetaKey::Data::IccTag icc_tag¶

struct openmeta::MetaKey::Data::PhotoshopIrb photoshop_irb¶

struct openmeta::MetaKey::Data::PhotoshopIrbField photoshop_irb_field¶

struct openmeta::MetaKey::Data::GeotiffKey geotiff_key¶

struct openmeta::MetaKey::Data::PrintImField printim_field¶

struct openmeta::MetaKey::Data::BmffField bmff_field¶

struct openmeta::MetaKey::Data::JumbfField jumbf_field¶

struct openmeta::MetaKey::Data::JumbfCborKey jumbf_cbor_key¶

struct openmeta::MetaKey::Data::PngText png_text¶

union Data¶

#include <meta_key.h>

Public Functions

inline Data() noexcept¶

Public Members

struct openmeta::MetaKeyView::Data::ExifTag exif_tag¶

struct openmeta::MetaKeyView::Data::Comment comment¶

struct openmeta::MetaKeyView::Data::ExrAttribute exr_attribute¶

struct openmeta::MetaKeyView::Data::IptcDataset iptc_dataset¶

struct openmeta::MetaKeyView::Data::XmpProperty xmp_property¶

struct openmeta::MetaKeyView::Data::IccHeaderField icc_header_field¶

struct openmeta::MetaKeyView::Data::IccTag icc_tag¶

struct openmeta::MetaKeyView::Data::PhotoshopIrb photoshop_irb¶

struct openmeta::MetaKeyView::Data::PhotoshopIrbField photoshop_irb_field¶

struct openmeta::MetaKeyView::Data::GeotiffKey geotiff_key¶

struct openmeta::MetaKeyView::Data::PrintImField printim_field¶

struct openmeta::MetaKeyView::Data::BmffField bmff_field¶

struct openmeta::MetaKeyView::Data::JumbfField jumbf_field¶

struct openmeta::MetaKeyView::Data::JumbfCborKey jumbf_cbor_key¶

struct openmeta::MetaKeyView::Data::PngText png_text¶

union Data¶

#include <meta_value.h>

Public Functions

inline Data() noexcept¶

Public Members

uint64_t u64¶

int64_t i64¶

uint32_t f32_bits¶: Raw IEEE-754 bits for MetaElementType::F32.

uint64_t f64_bits¶: Raw IEEE-754 bits for MetaElementType::F64.

URational ur¶

SRational sr¶

ByteSpan span¶

struct DngSdkAdapterOptions¶

#include <dng_sdk_adapter.h>

Options for applying prepared OpenMeta metadata onto DNG SDK objects.

Public Members

bool apply_exif = true¶

bool apply_xmp = true¶

bool apply_iptc = true¶

bool synchronize_metadata = true¶

bool cleanup_for_update = true¶

struct DngSdkAdapterResult¶

#include <dng_sdk_adapter.h>

Result for DNG SDK adapter apply/update operations.

Public Members

DngSdkAdapterStatus status = DngSdkAdapterStatus::Ok ¶

uint32_t applied_blocks = 0¶

uint32_t skipped_blocks = 0¶

bool exif_applied = false¶

bool xmp_applied = false¶

bool iptc_applied = false¶

bool synchronized_metadata = false¶

bool cleaned_for_update = false¶

bool updated_stream = false¶

TransferBlockKind failed_kind = TransferBlockKind::Other ¶

std::string message¶

struct EditOp¶

#include <meta_edit.h>

A single edit operation recorded by MetaEdit.

Public Members

EditOpKind kind = EditOpKind::AddEntry ¶

EntryId target = kInvalidEntryId ¶

Entry entry¶

MetaValue value¶

struct EmittedBmffItemSummary¶

#include <metadata_transfer.h>

One emitted ISO-BMFF metadata item summary entry.

Public Members

uint32_t item_type = 0U¶

uint32_t count = 0U¶

uint64_t bytes = 0U¶

bool mime_xmp = false¶

struct EmittedBmffPropertySummary¶

#include <metadata_transfer.h>

One emitted ISO-BMFF metadata property summary entry.

Public Members

uint32_t property_type = 0U¶

uint32_t property_subtype = 0U¶

uint32_t count = 0U¶

uint64_t bytes = 0U¶

struct EmittedExrAttributeSummary¶

#include <metadata_transfer.h>

One emitted EXR attribute summary entry.

Public Members

std::string name¶

std::string type_name¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmittedJp2BoxSummary¶

#include <metadata_transfer.h>

One emitted JP2 box summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmittedJpegMarkerSummary¶

#include <metadata_transfer.h>

One emitted JPEG marker summary entry.

Public Members

uint8_t marker = 0¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmittedJxlBoxSummary¶

#include <metadata_transfer.h>

One emitted JPEG XL box summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmittedPngChunkSummary¶

#include <metadata_transfer.h>

One emitted PNG chunk summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmittedTiffTagSummary¶

#include <metadata_transfer.h>

One emitted TIFF tag summary entry.

Public Members

uint16_t tag = 0¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmittedWebpChunkSummary¶

#include <metadata_transfer.h>

One emitted WebP chunk summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}¶

uint32_t count = 0¶

uint64_t bytes = 0¶

struct EmitTransferOptions¶

#include <metadata_transfer.h>

Emission options shared by backend emit entry points.

Public Members

bool skip_empty_payloads = true¶

bool stop_on_error = true¶

struct EmitTransferResult¶

#include <metadata_transfer.h>

Result details for bundle emission.

Public Members

TransferStatus status = TransferStatus::Ok ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint32_t emitted = 0¶

uint32_t skipped = 0¶

uint32_t errors = 0¶

uint32_t failed_block_index = 0xFFFFFFFFU¶

std::string message¶

struct Entry¶

#include <meta_store.h>

A single metadata entry (key/value) with provenance.

Note

Duplicate keys are allowed and preserved.

Public Members

MetaKey key¶

MetaValue value¶

Origin origin¶

EntryFlags flags = EntryFlags::None ¶

struct ExecutePreparedTransferBundleOptions¶

#include <metadata_transfer.h>

Options for execute_prepared_transfer_bundle.

Public Members

ExecutePreparedTransferOptions execute¶

OpenMetaResourcePolicy policy¶

std::string edit_target_path¶

std::string xmp_sidecar_base_path¶

XmpWritebackMode xmp_writeback_mode = XmpWritebackMode::EmbeddedOnly ¶

XmpDestinationEmbeddedMode xmp_destination_embedded_mode = XmpDestinationEmbeddedMode::PreserveExisting ¶

XmpDestinationSidecarMode xmp_destination_sidecar_mode = XmpDestinationSidecarMode::PreserveExisting ¶

XmpExistingDestinationSidecarState xmp_existing_destination_sidecar_state = XmpExistingDestinationSidecarState::Unknown ¶

bool c2pa_stage_requested = false¶

PreparedTransferC2paSignerInput c2pa_signer_input¶

bool c2pa_signed_package_provided = false¶

PreparedTransferC2paSignedPackage c2pa_signed_package¶

struct ExecutePreparedTransferFileOptions¶

#include <metadata_transfer.h>

Options for execute_prepared_transfer_file.

Public Members

PrepareTransferFileOptions prepare¶

ExecutePreparedTransferOptions execute¶

std::string edit_target_path¶

std::string xmp_sidecar_base_path¶

Base path used to derive sibling .xmp output or cleanup paths.

When empty, the file-helper derives the sidecar path from edit_target_path.

XmpExistingDestinationEmbeddedMode xmp_existing_destination_embedded_mode = XmpExistingDestinationEmbeddedMode::Ignore ¶

XmpExistingDestinationEmbeddedPrecedence xmp_existing_destination_embedded_precedence = XmpExistingDestinationEmbeddedPrecedence::DestinationWins ¶

XmpWritebackMode xmp_writeback_mode = XmpWritebackMode::EmbeddedOnly ¶

XmpDestinationEmbeddedMode xmp_destination_embedded_mode = XmpDestinationEmbeddedMode::PreserveExisting ¶

XmpDestinationSidecarMode xmp_destination_sidecar_mode = XmpDestinationSidecarMode::PreserveExisting ¶

XmpExistingDestinationSidecarState xmp_existing_destination_sidecar_state = XmpExistingDestinationSidecarState::Unknown ¶

bool c2pa_stage_requested = false¶

PreparedTransferC2paSignerInput c2pa_signer_input¶

bool c2pa_signed_package_provided = false¶

PreparedTransferC2paSignedPackage c2pa_signed_package¶

struct ExecutePreparedTransferFileResult¶

#include <metadata_transfer.h>

Result for execute_prepared_transfer_file.

Public Members

PrepareTransferFileResult prepared¶

ExecutePreparedTransferResult execute¶

bool xmp_existing_destination_embedded_loaded = false¶

TransferStatus xmp_existing_destination_embedded_status = TransferStatus::Unsupported ¶

std::string xmp_existing_destination_embedded_message¶

std::string xmp_existing_destination_embedded_path¶

bool xmp_sidecar_requested = false¶

TransferStatus xmp_sidecar_status = TransferStatus::Unsupported ¶

std::string xmp_sidecar_message¶

std::string xmp_sidecar_path¶

std::vector<std::byte> xmp_sidecar_output¶

bool xmp_sidecar_cleanup_requested = false¶

TransferStatus xmp_sidecar_cleanup_status = TransferStatus::Unsupported ¶

std::string xmp_sidecar_cleanup_message¶

std::string xmp_sidecar_cleanup_path¶

struct ExecutePreparedTransferOptions¶

#include <metadata_transfer.h>

Options for execute_prepared_transfer.

Public Members

std::vector<TransferTimePatchInput> time_patches¶

ApplyTimePatchOptions time_patch¶

bool time_patch_auto_nul = true¶

EmitTransferOptions emit¶

uint32_t emit_repeat = 1¶

TransferByteWriter *emit_output_writer = nullptr¶

bool edit_requested = false¶

bool edit_apply = false¶

TransferByteWriter *edit_output_writer = nullptr¶

bool strip_existing_xmp = false¶

PlanJpegEditOptions jpeg_edit¶

PlanTiffEditOptions tiff_edit¶

struct ExecutePreparedTransferResult¶

#include <metadata_transfer.h>

Result for execute_prepared_transfer.

Public Members

bool c2pa_stage_requested = false¶

ValidatePreparedC2paSignResult c2pa_stage_validation¶

EmitTransferResult c2pa_stage¶

ApplyTimePatchResult time_patch¶

EmitTransferResult compile¶

uint32_t compiled_ops = 0¶

EmitTransferResult emit¶

std::vector<EmittedJpegMarkerSummary> marker_summary¶

std::vector<EmittedTiffTagSummary> tiff_tag_summary¶

std::vector<EmittedJxlBoxSummary> jxl_box_summary¶

std::vector<EmittedWebpChunkSummary> webp_chunk_summary¶

std::vector<EmittedPngChunkSummary> png_chunk_summary¶

std::vector<EmittedJp2BoxSummary> jp2_box_summary¶

std::vector<EmittedExrAttributeSummary> exr_attribute_summary¶

std::vector<EmittedBmffItemSummary> bmff_item_summary¶

std::vector<EmittedBmffPropertySummary> bmff_property_summary¶

bool tiff_commit = false¶

uint64_t emit_output_size = 0¶

bool strip_existing_xmp = false¶

bool edit_requested = false¶

TransferStatus edit_plan_status = TransferStatus::Unsupported ¶

std::string edit_plan_message¶

JpegEditPlan jpeg_edit_plan¶

TiffEditPlan tiff_edit_plan¶

EmitTransferResult edit_apply¶

uint64_t edit_input_size = 0¶

uint64_t edit_output_size = 0¶

std::vector<std::byte> edited_output¶

struct ExecutePreparedTransferSnapshotOptions¶

#include <metadata_transfer.h>

Options for execute_prepared_transfer_snapshot.

Public Members

PrepareTransferRequest prepare¶

ExecutePreparedTransferOptions execute¶

OpenMetaResourcePolicy policy¶

std::string edit_target_path¶

std::string xmp_existing_sidecar_base_path¶

Base path used to load one existing sibling .xmp sidecar for XMP merge during bundle preparation.

When empty, the helper uses edit_target_path.

std::string xmp_sidecar_base_path¶

Base path used to derive sibling .xmp output or cleanup paths.

When empty, the helper derives the sidecar path from edit_target_path.

XmpExistingSidecarMode xmp_existing_sidecar_mode = XmpExistingSidecarMode::Ignore ¶

XmpExistingSidecarPrecedence xmp_existing_sidecar_precedence = XmpExistingSidecarPrecedence::SidecarWins ¶

std::string xmp_existing_destination_embedded_path¶

Optional path used to load existing destination embedded XMP before bundle preparation.

When empty and destination embedded merge is requested, the helper uses edit_target_path.

XmpExistingDestinationEmbeddedMode xmp_existing_destination_embedded_mode = XmpExistingDestinationEmbeddedMode::Ignore ¶

XmpExistingDestinationEmbeddedPrecedence xmp_existing_destination_embedded_precedence = XmpExistingDestinationEmbeddedPrecedence::DestinationWins ¶

XmpExistingDestinationCarrierPrecedence xmp_existing_destination_carrier_precedence = XmpExistingDestinationCarrierPrecedence::SidecarWins ¶

XmpWritebackMode xmp_writeback_mode = XmpWritebackMode::EmbeddedOnly ¶

XmpDestinationEmbeddedMode xmp_destination_embedded_mode = XmpDestinationEmbeddedMode::PreserveExisting ¶

XmpDestinationSidecarMode xmp_destination_sidecar_mode = XmpDestinationSidecarMode::PreserveExisting ¶

XmpExistingDestinationSidecarState xmp_existing_destination_sidecar_state = XmpExistingDestinationSidecarState::Unknown ¶

bool c2pa_stage_requested = false¶

PreparedTransferC2paSignerInput c2pa_signer_input¶

bool c2pa_signed_package_provided = false¶

PreparedTransferC2paSignedPackage c2pa_signed_package¶

struct ExifDecodeLimits¶

#include <exif_tiff_decode.h>

Resource limits applied during decode to bound hostile inputs.

Public Members

uint32_t max_ifds = 128¶

uint32_t max_entries_per_ifd = 4096¶

uint32_t max_total_entries = 200000¶

uint64_t max_value_bytes = 16ULL * 1024ULL * 1024ULL¶

struct ExifDecodeOptions¶

#include <exif_tiff_decode.h>

Decoder options for decode_exif_tiff.

Public Members

bool include_pointer_tags = true¶: If true, pointer tags are preserved as entries in addition to being followed.

bool decode_printim = true¶: If true, decode EXIF PrintIM (0xC4A5) into MetaKeyKind::PrintImField.

bool decode_geotiff = true¶: If true, decode GeoTIFF GeoKeyDirectoryTag (0x87AF) into MetaKeyKind::GeotiffKey entries (best-effort).

bool decode_makernote = false¶: If true, attempt best-effort MakerNote decoding (vendor blocks).

bool decode_embedded_containers = false¶: If true, attempt best-effort decoding of embedded containers stored as EXIF tag byte blobs (for example, Panasonic RW2 JpgFromRaw).

ExifIfdTokenPolicy tokens¶: IFD token naming policy (affects emitted EXIF key IFD strings).

ExifDecodeLimits limits¶

struct ExifDecodeResult¶

#include <exif_tiff_decode.h>

Aggregated decode statistics.

Public Members

ExifDecodeStatus status = ExifDecodeStatus::Ok ¶

uint32_t ifds_written = 0¶

uint32_t ifds_needed = 0¶

uint32_t entries_decoded = 0¶

ExifLimitReason limit_reason = ExifLimitReason::None ¶

uint64_t limit_ifd_offset = 0¶

uint16_t limit_tag = 0¶

struct ExifIfdRef¶

#include <exif_tiff_decode.h>

Reference to a decoded IFD within the input TIFF byte stream.

Public Members

ExifIfdKind kind = ExifIfdKind::Ifd ¶

uint32_t index = 0¶

uint64_t offset = 0¶

BlockId block = kInvalidBlockId ¶

struct ExifIfdTokenPolicy¶

#include <exif_tiff_decode.h>

Token strings used to label decoded IFD blocks.

Public Members

std::string_view ifd_prefix = "ifd"¶: Prefix used for generic IFD chain blocks (e.g. ifd0, ifd1).

std::string_view subifd_prefix = "subifd"¶: Prefix used for SubIFD blocks (e.g. subifd0, subifd1).

std::string_view exif_ifd_token = "exififd"¶: Token used for the EXIF sub-IFD pointer directory.

std::string_view gps_ifd_token = "gpsifd"¶: Token used for the GPS sub-IFD pointer directory.

std::string_view interop_ifd_token = "interopifd"¶: Token used for the Interop sub-IFD pointer directory.

struct ExifOrientationInterpretation¶

#include <orientation.h>

Normalized interpretation for one EXIF/TIFF orientation value.

Public Members

ExifOrientationStatus status = ExifOrientationStatus::Ok ¶

uint16_t orientation = 1¶

uint16_t rotation_degrees_cw = 0¶

uint16_t rotation_only_orientation = 1¶

bool mirrored = false¶

bool swaps_width_height = false¶

const char *name = "Horizontal (normal)"¶

struct ExifTag¶

#include <meta_key.h>

Public Members

ByteSpan ifd¶

uint16_t tag = 0¶

struct ExifTag¶

#include <meta_key.h>

Public Members

std::string_view ifd¶

uint16_t tag = 0¶

struct ExportItem¶

#include <interop_export.h>

A single exported metadata item.

The name view is valid only for the duration of MetadataSink::on_item.

Public Members

std::string_view name¶

const Entry *entry = nullptr¶

const Origin *origin = nullptr¶

EntryFlags flags = EntryFlags::None ¶

struct ExportOptions¶

#include <interop_export.h>

Export controls for visit_metadata.

Public Members

ExportNameStyle style = ExportNameStyle::Canonical ¶

ExportNamePolicy name_policy = ExportNamePolicy::ExifToolAlias ¶

bool include_origin = false¶

bool include_flags = false¶

bool include_makernotes = true¶

struct ExrAdapterAttribute¶

#include <exr_adapter.h>

One owned EXR-native attribute payload.

Public Members

uint32_t part_index = 0¶

std::string name¶

std::string type_name¶

std::vector<std::byte> value¶

bool is_opaque = false¶

struct ExrAdapterBatch¶

#include <exr_adapter.h>

One owned EXR-native attribute batch.

Public Members

uint32_t encoding_version = kExrCanonicalEncodingVersion ¶

ExrAdapterOptions options¶

std::vector<ExrAdapterAttribute> attributes¶

struct ExrAdapterOptions¶

#include <exr_adapter.h>

Options for EXR attribute batch export.

Public Members

bool include_opaque = true¶: Include opaque/custom EXR attributes when type name is preserved.

bool fail_on_unencodable = true¶: If false, unencodable entries are skipped instead of failing.

struct ExrAdapterPartSpan¶

#include <exr_adapter.h>

One contiguous per-part span inside ExrAdapterBatch::attributes.

Public Members

uint32_t part_index = 0¶

uint32_t first_attribute = 0¶

uint32_t attribute_count = 0¶

struct ExrAdapterPartView¶

#include <exr_adapter.h>

One zero-copy per-part attribute view over ExrAdapterBatch.

Public Members

uint32_t part_index = 0¶

std::span<const ExrAdapterAttribute> attributes¶

struct ExrAdapterReplayCallbacks¶

#include <exr_adapter.h>

Replay callbacks for replay_exr_attribute_batch.

Public Members

ExrAdapterStatus (*begin_part)(void *user, uint32_t part_index, uint32_t attribute_count) noexcept = nullptr¶

ExrAdapterStatus (*emit_attribute)(void *user, uint32_t part_index, const ExrAdapterAttribute *attribute) noexcept = nullptr¶

ExrAdapterStatus (*end_part)(void *user, uint32_t part_index) noexcept = nullptr¶

void *user = nullptr¶

struct ExrAdapterReplayResult¶

#include <exr_adapter.h>

Result for EXR adapter batch replay.

Public Members

ExrAdapterStatus status = ExrAdapterStatus::Ok ¶

uint32_t replayed_parts = 0¶

uint32_t replayed_attributes = 0¶

uint32_t failed_part_index = std::numeric_limits<uint32_t>::max()¶

uint32_t failed_attribute_index = std::numeric_limits<uint32_t>::max()¶

std::string message¶

struct ExrAdapterResult¶

#include <exr_adapter.h>

Result for EXR adapter batch export.

Public Members

ExrAdapterStatus status = ExrAdapterStatus::Ok ¶

uint32_t exported = 0¶

uint32_t skipped = 0¶

uint32_t errors = 0¶

EntryId failed_entry = kInvalidEntryId ¶

std::string message¶

struct ExrAttribute¶

#include <meta_key.h>

Public Members

uint32_t part_index = 0¶

ByteSpan name¶

struct ExrAttribute¶

#include <meta_key.h>

Public Members

uint32_t part_index = 0¶

std::string_view name¶

struct ExrDecodeLimits¶

#include <exr_decode.h>

Resource limits applied during EXR header decode.

Public Members

uint32_t max_parts = 64¶

uint32_t max_attributes_per_part = 1U << 16¶

uint32_t max_attributes = 200000¶

uint32_t max_name_bytes = 1024¶

uint32_t max_type_name_bytes = 1024¶

uint32_t max_attribute_bytes = 8U * 1024U * 1024U¶

uint64_t max_total_attribute_bytes = 64ULL * 1024ULL * 1024ULL¶

struct ExrDecodeOptions¶

#include <exr_decode.h>

Decoder options for decode_exr_header.

Public Members

bool decode_known_types = true¶: If true, decodes known scalar/vector EXR attribute types into typed values. Unknown and complex attribute types are always preserved as raw bytes.

bool preserve_unknown_type_name = true¶: If true, preserves original EXR type name for unknown/custom attrs in Origin::wire_type_name.

ExrDecodeLimits limits¶

struct ExrDecodeResult¶

#include <exr_decode.h>

Public Members

ExrDecodeStatus status = ExrDecodeStatus::Ok ¶

uint32_t parts_decoded = 0¶

uint32_t entries_decoded = 0¶

struct ExrPreparedAttribute¶

#include <metadata_transfer.h>

EXR attribute payload for transfer emission.

Public Members

std::string name¶

std::string type_name¶

std::vector<std::byte> value¶

bool is_opaque = false¶

struct ExrPreparedAttributeView¶

#include <metadata_transfer.h>

Zero-copy EXR attribute view for prepared transfer emission.

Public Members

std::string_view name¶

std::string_view type_name¶

std::span<const std::byte> value¶

bool is_opaque = false¶

class ExrTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for OpenEXR header attribute emission.

Public Functions

virtual ~ExrTransferEmitter() = default¶

virtual TransferStatus set_attribute(const ExrPreparedAttribute &attr) noexcept = 0¶

inline virtual TransferStatus set_attribute_view(const ExrPreparedAttributeView &attr) noexcept¶

struct GeotiffKey¶

#include <meta_key.h>

Public Members

uint16_t key_id = 0¶

struct GeotiffKey¶

#include <meta_key.h>

Public Members

uint16_t key_id = 0¶

struct IccDecodeLimits¶

#include <icc_decode.h>

Resource limits applied during ICC decode to bound hostile inputs.

Public Members

uint32_t max_tags = 1U << 16¶

uint32_t max_tag_bytes = 32U * 1024U * 1024U¶

uint64_t max_total_tag_bytes = 64ULL * 1024ULL * 1024ULL¶

struct IccDecodeOptions¶

#include <icc_decode.h>

Decoder options for decode_icc_profile.

Public Members

IccDecodeLimits limits¶

struct IccDecodeResult¶

#include <icc_decode.h>

Public Members

IccDecodeStatus status = IccDecodeStatus::Ok ¶

uint32_t entries_decoded = 0¶

struct IccHeaderField¶

#include <meta_key.h>

Public Members

uint32_t offset = 0¶

struct IccHeaderField¶

#include <meta_key.h>

Public Members

uint32_t offset = 0¶

struct IccTag¶

#include <meta_key.h>

Public Members

uint32_t signature = 0¶

struct IccTag¶

#include <meta_key.h>

Public Members

uint32_t signature = 0¶

struct IccTagInterpretation¶

#include <icc_interpret.h>

Best-effort decoded view of an ICC tag payload.

Public Members

uint32_t signature = 0¶: ICC tag signature (from tag table).

std::string_view name¶: Tag display name for signature, when known.

std::string type¶: ICC tag type signature as text/fourcc (for example desc, XYZ, curv).

std::string text¶: Decoded text (for text-like tags).

std::vector<double> values¶: Decoded numeric values (for XYZ/curve/parametric forms).

uint32_t rows = 0¶: Optional layout hint for matrix-like values.

uint32_t cols = 0¶: Optional layout hint for matrix-like values.

struct IccTagInterpretLimits¶

#include <icc_interpret.h>

Limits for ICC tag interpretation helpers.

Public Members

uint32_t max_values = 512U¶

uint32_t max_text_bytes = 4096U¶

struct IccTagInterpretOptions¶

#include <icc_interpret.h>

Options for interpret_icc_tag.

Public Members

IccTagInterpretLimits limits¶

struct InteropSafetyError¶

#include <interop_export.h>

Structured error details returned by strict safe interop exports.

Public Members

InteropSafetyReason reason = InteropSafetyReason::None ¶

std::string field_name¶

std::string key_path¶

std::string message¶

struct IptcDataset¶

#include <meta_key.h>

Public Members

uint16_t record = 0¶

uint16_t dataset = 0¶

struct IptcDataset¶

#include <meta_key.h>

Public Members

uint16_t record = 0¶

uint16_t dataset = 0¶

struct IptcIimDecodeLimits¶

#include <iptc_iim_decode.h>

Resource limits applied during IPTC-IIM decode to bound hostile inputs.

Public Members

uint32_t max_datasets = 200000¶

uint32_t max_dataset_bytes = 8U * 1024U * 1024U¶

uint64_t max_total_bytes = 64ULL * 1024ULL * 1024ULL¶

struct IptcIimDecodeOptions¶

#include <iptc_iim_decode.h>

Decoder options for decode_iptc_iim.

Public Members

IptcIimDecodeLimits limits¶

struct IptcIimDecodeResult¶

#include <iptc_iim_decode.h>

Public Members

IptcIimDecodeStatus status = IptcIimDecodeStatus::Ok ¶

uint32_t entries_decoded = 0¶

class Jp2TransferEmitter¶

#include <metadata_transfer.h>

Backend contract for JP2 metadata box emission.

Public Functions

virtual ~Jp2TransferEmitter() = default¶

virtual TransferStatus add_box(std::array<char, 4> type, std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus close_boxes() noexcept = 0¶

struct JpegEditPlan¶

#include <metadata_transfer.h>

Planned JPEG edit summary (draft API).

Public Members

TransferStatus status = TransferStatus::Ok ¶

JpegEditMode requested_mode = JpegEditMode::Auto ¶

JpegEditMode selected_mode = JpegEditMode::MetadataRewrite ¶

bool in_place_possible = false¶

bool strip_existing_xmp = false¶

uint32_t emitted_segments = 0¶

uint32_t replaced_segments = 0¶

uint32_t appended_segments = 0¶

uint32_t removed_existing_segments = 0¶

uint32_t removed_existing_jumbf_segments = 0¶

uint32_t removed_existing_c2pa_segments = 0¶

uint64_t input_size = 0¶

uint64_t output_size = 0¶

uint64_t leading_scan_end = 0¶

std::string message¶

class JpegTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for JPEG metadata emission.

Public Functions

virtual ~JpegTransferEmitter() = default¶

virtual TransferStatus write_app_marker(uint8_t marker_code, std::span<const std::byte> payload) noexcept = 0¶

struct JumbfCborKey¶

#include <meta_key.h>

Public Members

ByteSpan key¶

struct JumbfCborKey¶

#include <meta_key.h>

Public Members

std::string_view key¶

struct JumbfDecodeLimits¶

#include <jumbf_decode.h>

Resource limits for JUMBF/C2PA decode.

Public Members

uint64_t max_input_bytes = 64ULL * 1024ULL * 1024ULL¶: Maximum input bytes to accept (0 = unlimited).

uint32_t max_box_depth = 32¶: Maximum BMFF box depth. 0 is normalized to a safe default (32).

uint32_t max_boxes = 1U << 16¶: Maximum BMFF boxes to traverse. 0 is normalized to a safe default (65536).

uint32_t max_entries = 200000¶: Maximum emitted entries. 0 is normalized to a safe default (200000).

uint32_t max_cbor_depth = 64¶: Maximum CBOR recursion depth. 0 is normalized to a safe default (64).

uint32_t max_cbor_items = 200000¶: Maximum CBOR items to parse. 0 is normalized to a safe default (200000).

uint32_t max_cbor_key_bytes = 1024¶: Maximum CBOR string key bytes.

uint32_t max_cbor_text_bytes = 8U * 1024U * 1024U¶: Maximum CBOR text value bytes.

uint32_t max_cbor_bytes_bytes = 8U * 1024U * 1024U¶: Maximum CBOR byte-string value bytes.

struct JumbfDecodeOptions¶

#include <jumbf_decode.h>

Decoder options for decode_jumbf_payload.

Public Members

bool decode_cbor = true¶: If true, traverse cbor boxes and emit decoded CBOR key/value entries.

bool detect_c2pa = true¶: If true, emit a c2pa.detected marker when C2PA-like payload is seen.

bool verify_c2pa = false¶: If true, request draft C2PA verification scaffold fields.

C2paVerifyBackend verify_backend = C2paVerifyBackend::Auto ¶: Verification backend preference (used when verify_c2pa is true).

bool verify_require_trusted_chain = false¶: If true, require the certificate chain to validate against the system trust store. Untrusted or missing chains fail verification even when the signature matches.

bool verify_require_resolved_references = false¶: If true, explicit claim references must resolve deterministically: unresolved or ambiguous explicit-reference signatures fail verification.

JumbfDecodeLimits limits¶

struct JumbfDecodeResult¶

#include <jumbf_decode.h>

JUMBF decode result summary.

Public Members

JumbfDecodeStatus status = JumbfDecodeStatus::Unsupported ¶

uint32_t boxes_decoded = 0¶

uint32_t cbor_items = 0¶

uint32_t entries_decoded = 0¶

C2paVerifyStatus verify_status = C2paVerifyStatus::NotRequested ¶

C2paVerifyBackend verify_backend_selected = C2paVerifyBackend::None ¶

struct JumbfField¶

#include <meta_key.h>

Public Members

ByteSpan field¶

struct JumbfField¶

#include <meta_key.h>

Public Members

std::string_view field¶

struct JumbfStructureEstimate¶

#include <jumbf_decode.h>

Preflight structural estimate for a JUMBF/C2PA payload.

This is a scan-only estimate: it does not emit metadata entries.

Public Members

JumbfDecodeStatus status = JumbfDecodeStatus::Unsupported ¶

uint32_t boxes_scanned = 0¶

uint32_t max_box_depth = 0¶

uint32_t cbor_payloads = 0¶

uint32_t cbor_items = 0¶

uint32_t max_cbor_depth = 0¶

class JxlTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for JPEG XL metadata box emission.

Public Functions

virtual ~JxlTransferEmitter() = default¶

virtual TransferStatus set_icc_profile(std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus add_box(std::array<char, 4> type, std::span<const std::byte> payload, bool compress) noexcept = 0¶

virtual TransferStatus close_boxes() noexcept = 0¶

struct KeySpan¶

#include <meta_store.h>

Public Members

uint32_t start = 0¶

uint32_t count = 0¶

EntryId repr = kInvalidEntryId ¶

struct LibRawFlipToExifOptions¶

#include <libraw_adapter.h>

Options for map_libraw_flip_to_exif_orientation.

Public Members

LibRawOrientationTarget target = LibRawOrientationTarget::RawImage ¶: Raw-image flips should normally map back into EXIF orientation.

bool preserve_embedded_preview_orientation = true¶: Embedded previews are usually delivered as-is or carry their own EXIF.

struct LibRawFlipToExifResult¶

#include <libraw_adapter.h>

Result for map_libraw_flip_to_exif_orientation.

Public Members

LibRawOrientationStatus status = LibRawOrientationStatus::Ok ¶

LibRawFlipToExifCode code = LibRawFlipToExifCode::None ¶

uint32_t libraw_flip = 0¶

uint16_t exif_orientation = 1¶

bool preview_passthrough = false¶

struct LibRawOrientationFileOptions¶

#include <libraw_adapter.h>

Options for map_meta_orientation_to_libraw_flip_from_file.

Public Members

uint64_t max_file_bytes = 0¶

SimpleMetaDecodeOptions decode¶

LibRawOrientationOptions orientation¶

struct LibRawOrientationFileResult¶

#include <libraw_adapter.h>

Result for map_meta_orientation_to_libraw_flip_from_file.

Public Members

LibRawOrientationFileStatus file_status = LibRawOrientationFileStatus::Ok ¶

MappedFileStatus mapped_file_status = MappedFileStatus::Ok ¶

uint64_t file_size = 0¶

SimpleMetaResult read¶

LibRawOrientationResult orientation¶

struct LibRawOrientationOptions¶

#include <libraw_adapter.h>

Options for map_exif_orientation_to_libraw_flip.

Public Members

LibRawOrientationTarget target = LibRawOrientationTarget::RawImage ¶: Raw-image orientation should normally map into imgdata.sizes.flip.

bool preserve_embedded_preview_orientation = true¶: Embedded previews are usually delivered as-is or carry their own EXIF.

LibRawMirrorPolicy mirror_policy = LibRawMirrorPolicy::Reject ¶: Mirrored TIFF/EXIF orientations are not representable in LibRaw flip.

struct LibRawOrientationResult¶

#include <libraw_adapter.h>

Result for map_exif_orientation_to_libraw_flip.

Public Members

LibRawOrientationStatus status = LibRawOrientationStatus::Ok ¶

LibRawOrientationCode code = LibRawOrientationCode::None ¶

LibRawOrientationSource source = LibRawOrientationSource::ExplicitInput ¶

uint16_t exif_orientation = 1¶

uint32_t libraw_flip = 0¶

bool apply_flip = false¶

bool mirrored = false¶

bool preview_passthrough = false¶

bool has_exif_ifd0_orientation = false¶

bool has_xmp_tiff_orientation = false¶

uint16_t exif_ifd0_orientation = 0¶

uint16_t xmp_tiff_orientation = 0¶

bool orientation_conflict = false¶

class MappedFile¶

#include <mapped_file.h>

Read-only, whole-file memory mapping.

This is a utility used by tools/bindings to avoid copying multi-GB files into memory while still exposing a std::span<const std::byte> view that OpenMeta’s decoders can operate on.

Public Functions

MappedFile() noexcept¶

~MappedFile() noexcept¶

MappedFile(const MappedFile&) = delete¶

MappedFile &operator=(const MappedFile&) = delete¶

MappedFile(MappedFile &&other) noexcept¶

MappedFile &operator=(MappedFile &&other) noexcept¶

MappedFileStatus open(const char *path, uint64_t max_file_bytes = 0) noexcept¶: Opens and maps path (read-only). max_file_bytes is a hard cap (0 = unlimited).

void close() noexcept¶: Unmaps/closes the file (idempotent).

bool is_open() const noexcept¶

uint64_t size() const noexcept¶

std::span<const std::byte> bytes() const noexcept¶

Private Members

int fd_ = -1¶

const std::byte *data_ = nullptr¶

uint64_t size_ = 0¶

struct MetadataCapability¶

#include <metadata_capabilities.h>

Capability record for one format/family pair.

Public Members

TransferTargetFormat format = TransferTargetFormat::Jpeg ¶

MetadataCapabilityFamily family = MetadataCapabilityFamily::Exif ¶

MetadataCapabilitySupport read = MetadataCapabilitySupport::Unsupported ¶

MetadataCapabilitySupport structured_decode = MetadataCapabilitySupport::Unsupported ¶

MetadataCapabilitySupport transfer_prepare = MetadataCapabilitySupport::Unsupported ¶

MetadataCapabilitySupport target_edit = MetadataCapabilitySupport::Unsupported ¶

MetadataCapabilitySupport raw_preservation = MetadataCapabilitySupport::Unsupported ¶: Existing raw-carrier preservation in current transfer flows. This does not imply raw-preserving source snapshots.

struct MetadataCompatibilityDumpOptions¶

#include <compatibility_dump.h>

Options for dump_metadata_compatibility.

Public Members

ExportNameStyle style = ExportNameStyle::FlatHost ¶

ExportNamePolicy name_policy = ExportNamePolicy::ExifToolAlias ¶

bool include_values = true¶

bool include_origins = true¶

bool include_flags = true¶

uint32_t max_value_bytes = 256U¶

struct MetadataConceptCandidate¶

#include <metadata_concepts.h>

Public Members

MetadataConceptKind kind = MetadataConceptKind::Orientation ¶

MetadataConceptRole role = MetadataConceptRole::Primary ¶

MetadataConceptSourceFamily family = MetadataConceptSourceFamily::Unknown ¶

MetadataQuerySemanticKind semantic = MetadataQuerySemanticKind::Unknown ¶

MetadataQueryValueShape shape = MetadataQueryValueShape::Unknown ¶

EntryId entry_id = kInvalidEntryId ¶

std::vector<EntryId> source_entries¶

uint8_t priority = 0U¶

bool preferred = false¶

bool conflict = false¶

MetadataConceptTransferHint transfer_hint = MetadataConceptTransferHint::Unknown ¶

bool compatible_file_safe = false¶

bool rendered_image_safe = false¶

bool requires_target_image_spec = false¶

bool source_bound = false¶

bool has_numeric = false¶

uint8_t numeric_count = 0U¶

double numeric[4] = {}¶

bool has_values = false¶

std::vector<double> values¶

bool has_origin = false¶

double origin[2] = {}¶

bool has_size = false¶

double size[2] = {}¶

bool has_rect = false¶

double rect[4] = {}¶: Rect is normalized as x, y, width, height.

bool has_margins = false¶

double margins[4] = {}¶: Margins are normalized as left, top, right, bottom.

std::string text¶

std::string value_key¶: Normalized value used for same-role conflict checks.

bool has_date_time = false¶

bool date_time_has_time = false¶

bool date_time_has_utc_offset = false¶

MetadataConceptDateTimePrecision date_time_precision = MetadataConceptDateTimePrecision::Unknown ¶

MetadataConceptTimeZoneKind date_time_zone = MetadataConceptTimeZoneKind::Unknown ¶

int16_t date_time_year = 0¶

uint8_t date_time_month = 0U¶

uint8_t date_time_day = 0U¶

uint8_t date_time_hour = 0U¶

uint8_t date_time_minute = 0U¶

uint8_t date_time_second = 0U¶

int16_t date_time_utc_offset_min = 0¶

bool has_gps_altitude_reference = false¶

bool gps_altitude_below_sea_level = false¶

uint8_t gps_altitude_reference_code = 0U¶

struct MetadataConceptResolution¶

#include <metadata_concepts.h>

Public Members

MetadataConceptKind kind = MetadataConceptKind::Orientation ¶

bool found = false¶

bool conflict = false¶

EntryId preferred_entry = kInvalidEntryId ¶

std::vector<EntryId> source_entries¶

std::vector<MetadataConceptCandidate> candidates¶

struct MetadataConceptResult¶

#include <metadata_concepts.h>

Public Members

std::vector<MetadataConceptResolution> concepts¶

struct MetadataInterpretationRecord¶

#include <metadata_interpretation.h>

One normalized interpretation record.

Records preserve the source entries that produced the interpretation and use the same semantic and shape vocabulary as metadata query. Numeric geometry is normalized where available: rect is x, y, width, height; margins are left, top, right, bottom.

Public Members

MetadataQueryKind query_kind = MetadataQueryKind::Crop ¶

MetadataQuerySemanticKind semantic = MetadataQuerySemanticKind::Unknown ¶

MetadataQueryValueShape shape = MetadataQueryValueShape::Unknown ¶

uint8_t confidence = 0U¶

std::vector<EntryId> source_entries¶

bool has_origin = false¶

double origin[2] = {}¶

bool has_size = false¶

double size[2] = {}¶

bool has_rect = false¶

double rect[4] = {}¶

bool has_margins = false¶

double margins[4] = {}¶

bool has_values = false¶

std::vector<double> values¶

struct MetadataInterpretationResult¶

#include <metadata_interpretation.h>

Public Members

std::vector<MetadataInterpretationRecord> records¶

struct MetadataQueryCandidate¶

#include <metadata_query.h>

Public Members

MetadataQuerySemanticKind semantic = MetadataQuerySemanticKind::Unknown ¶

MetadataQueryValueShape normalized_shape = MetadataQueryValueShape::Unknown ¶

uint8_t confidence = 0U¶

std::vector<EntryId> source_entries¶

bool has_origin = false¶

double origin[2] = {}¶

bool has_size = false¶

double size[2] = {}¶

bool has_rect = false¶

double rect[4] = {}¶: Rect is normalized as x, y, width, height.

bool has_margins = false¶

double margins[4] = {}¶: Margins are normalized as left, top, right, bottom.

bool has_values = false¶

std::vector<double> values¶

struct MetadataQueryMatch¶

#include <metadata_query.h>

Public Members

EntryId entry_id = kInvalidEntryId ¶

MetaKeyKind key_kind = MetaKeyKind::ExifTag ¶

MetadataQuerySemanticKind semantic = MetadataQuerySemanticKind::Unknown ¶

MetadataQueryValueShape shape = MetadataQueryValueShape::Unknown ¶

uint8_t confidence = 0U¶

uint32_t matched_terms = 0U¶

bool exact_match = false¶

bool fuzzy_match = false¶

uint8_t fuzzy_score = 0U¶

uint16_t exif_tag = 0U¶

std::string group¶

std::string name¶

struct MetadataQueryResult¶

#include <metadata_query.h>

Public Members

MetadataQueryKind kind = MetadataQueryKind::Crop ¶

std::vector<MetadataQueryMatch> matches¶

std::vector<MetadataQueryCandidate> candidates¶

class MetadataSink¶

#include <interop_export.h>

Callback sink for visit_metadata.

API Stability: Stable host-facing v1 callback contract.

Public Functions

virtual ~MetadataSink() = default¶

virtual void on_item(const ExportItem &item) noexcept = 0¶

class MetaEdit¶

#include <meta_edit.h>

A batch of metadata edits to apply to a MetaStore.

Designed for multi-threaded production via per-thread edit buffers: build edits without mutating the base store, then apply with commit.

New keys/values that require storage use this edit’s ByteArena.

Public Functions

MetaEdit() = default¶

ByteArena &arena() noexcept¶

const ByteArena &arena() const noexcept¶

void reserve_ops(size_t count)¶: Reserves space for count operations (may allocate).

void add_entry(const Entry &entry)¶: Appends a new entry.

void set_value(EntryId target, const MetaValue &value)¶: Updates the value of an existing entry id.

void tombstone(EntryId target)¶: Marks an entry as deleted (tombstone).

std::span<const EditOp> ops() const noexcept¶

Private Members

ByteArena arena_¶

std::vector<EditOp> ops_¶

struct MetaKey¶

#include <meta_key.h>

An owned metadata key.

Uses ByteSpan fields for string-like components so keys can be stored compactly in a ByteArena (e.g. IFD token, XMP schema namespace).

Public Members

MetaKeyKind kind = MetaKeyKind::ExifTag ¶

union openmeta::MetaKey::Data data¶

struct MetaKeyView¶

#include <meta_key.h>

A borrowed metadata key view.

Intended for lookups and comparisons without allocating/copying strings.

Public Members

MetaKeyKind kind = MetaKeyKind::ExifTag ¶

union openmeta::MetaKeyView::Data data¶

class MetaStore¶

#include <meta_store.h>

Stores decoded metadata entries grouped into blocks.

Lifecycle:

Build phase: call add_block and add_entry (not thread-safe).
Finalize: call finalize to build lookup indices; treat as read-only.

Indices:

entries_in_block returns entries sorted by Origin::order_in_block.
find_all returns all matching entries (duplicates preserved).

Public Functions

MetaStore() = default¶

BlockId add_block(const BlockInfo &info)¶: Adds a new block and returns its id.

EntryId add_entry(const Entry &entry)¶: Appends an entry and returns its id.

ByteArena &arena() noexcept¶

const ByteArena &arena() const noexcept¶

void finalize()¶: Builds lookup indices and marks the store as finalized.

void rehash()¶: Rebuilds indices after an edit pipeline (invalidates previous spans).

uint32_t block_count() const noexcept¶

const BlockInfo &block_info(BlockId id) const noexcept¶

std::span<const Entry> entries() const noexcept¶

const Entry &entry(EntryId id) const noexcept¶

std::span<const EntryId> entries_in_block(BlockId block) const noexcept¶: Returns all entries in block, ordered by Origin::order_in_block.

std::span<const EntryId> find_all(const MetaKeyView &key) const noexcept¶: Returns all entry ids matching key (excluding tombstones).

Private Functions

void rebuild_block_index()¶

void rebuild_key_index()¶

void clear_indices() noexcept¶

Private Members

ByteArena arena_¶

std::vector<Entry> entries_¶

std::vector<BlockInfo> blocks_¶

std::vector<EntryId> entries_by_block_¶

std::vector<BlockSpan> block_spans_¶

std::vector<EntryId> entries_by_key_¶

std::vector<KeySpan> key_spans_¶

bool finalized_ = false¶

Friends

friend MetaStore commit(const MetaStore &base, std::span<const MetaEdit> edits)¶: Applies edits to base and returns a new MetaStore snapshot.

friend MetaStore compact(const MetaStore &base)¶: Compacts a store by removing tombstones and rewriting indices.

struct MetaValue¶

#include <meta_value.h>

A typed metadata value.

Storage rules:

Scalar values are stored inline in MetaValue::data.
Array/Bytes/Text values store their payload in MetaValue::data.span (a ByteSpan into a ByteArena). Text payload is not nul-terminated.

The count field is:

1 for scalars
number of elements for arrays
number of bytes for bytes/text

Public Members

MetaValueKind kind = MetaValueKind::Empty ¶

MetaElementType elem_type = MetaElementType::U8 ¶

TextEncoding text_encoding = TextEncoding::Unknown ¶

uint32_t count = 0¶

union openmeta::MetaValue::Data data¶

struct OcioAdapterOptions¶

#include <ocio_adapter.h>

Options for build_ocio_metadata_tree.

Public Functions

inline OcioAdapterOptions() noexcept¶

Public Members

ExportOptions export_options¶

uint32_t max_value_bytes = 1024¶

bool include_empty = false¶

bool include_normalized_ccm = true¶: Append derived normalized DNG CCM fields under dngnorm:*.

struct OcioAdapterRequest¶

#include <ocio_adapter.h>

Stable flat request for OCIO adapter export.

Public Members

ExportNameStyle style = ExportNameStyle::XmpPortable ¶

ExportNamePolicy name_policy = ExportNamePolicy::ExifToolAlias ¶

bool include_makernotes = false¶

bool include_origin = false¶

bool include_flags = false¶

uint32_t max_value_bytes = 1024¶

bool include_empty = false¶

bool include_normalized_ccm = true¶

struct OcioMetadataNode¶

#include <ocio_adapter.h>

Minimal tree node similar to OCIO FormatMetadata composition.

Public Members

std::string name¶

std::string value¶

std::vector<OcioMetadataNode> children¶

struct OpenMetaResourcePolicy¶

#include <resource_policy.h>

Draft, storage-agnostic resource limits for untrusted metadata input.

This policy intentionally favors parser/output budgets over hard file-size caps, so large legitimate assets (for example RAW/EXR) can still be processed when decode limits are respected.

Public Members

uint64_t max_file_bytes = 0¶: Optional file mapping cap (0 = unlimited).

PayloadLimits payload_limits¶: Reassembly/decompression budgets.

ExifDecodeLimits exif_limits¶: EXIF/TIFF decode budgets.

XmpDecodeLimits xmp_limits¶: XMP RDF/XML decode budgets.

ExrDecodeLimits exr_limits¶: OpenEXR header decode budgets.

JumbfDecodeLimits jumbf_limits¶: JUMBF/C2PA decode budgets.

IccDecodeLimits icc_limits¶: ICC profile decode budgets.

IptcIimDecodeLimits iptc_limits¶: IPTC-IIM decode budgets.

PhotoshopIrbDecodeLimits photoshop_irb_limits¶: Photoshop IRB decode budgets.

PreviewScanLimits preview_scan_limits¶: Embedded preview discovery/extraction budgets.

uint64_t max_preview_output_bytes = 128ULL * 1024ULL * 1024ULL¶

XmpDumpLimits xmp_dump_limits¶: XMP sidecar dump budgets.

uint32_t max_decode_millis = 0¶: Draft future budget hooks (not enforced yet).

uint32_t max_decompression_ratio = 0¶

uint64_t max_total_decode_work_bytes = 0¶

struct Origin¶

#include <meta_store.h>

Where an Entry came from inside the original container.

Public Members

BlockId block = kInvalidBlockId ¶

uint32_t order_in_block = 0¶

WireType wire_type¶

uint32_t wire_count = 0¶

ByteSpan wire_type_name¶: Optional wire type name (for formats with named types, e.g. OpenEXR custom attrs).

EntryNameContextKind name_context_kind = EntryNameContextKind::None ¶

uint8_t name_context_variant = 0¶

struct PayloadLimits¶

#include <container_payload.h>

Resource limits applied during payload extraction to bound hostile inputs.

Public Members

uint32_t max_parts = 1U << 14¶

uint64_t max_output_bytes = 64ULL * 1024ULL * 1024ULL¶

struct PayloadOptions¶

#include <container_payload.h>

Options for payload extraction.

Public Members

bool decompress = true¶: If true, attempt to decompress payloads marked with BlockCompression.

PayloadLimits limits¶

struct PayloadResult¶

#include <container_payload.h>

Public Members

PayloadStatus status = PayloadStatus::Ok ¶

uint64_t written = 0¶

uint64_t needed = 0¶

struct PersistPreparedTransferFileOptions¶

#include <metadata_transfer.h>

Options for persist_prepared_transfer_file_result.

Public Members

std::string output_path¶

bool write_output = true¶

bool overwrite_output = false¶

uint64_t prewritten_output_bytes = 0¶

bool overwrite_xmp_sidecar = false¶

bool remove_destination_xmp_sidecar = true¶

struct PersistPreparedTransferFileResult¶

#include <metadata_transfer.h>

Result for persist_prepared_transfer_file_result.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

std::string message¶

TransferStatus output_status = TransferStatus::Unsupported ¶

std::string output_message¶

std::string output_path¶

uint64_t output_bytes = 0¶

TransferStatus xmp_sidecar_status = TransferStatus::Unsupported ¶

std::string xmp_sidecar_message¶

std::string xmp_sidecar_path¶

uint64_t xmp_sidecar_bytes = 0¶

TransferStatus xmp_sidecar_cleanup_status = TransferStatus::Unsupported ¶

std::string xmp_sidecar_cleanup_message¶

std::string xmp_sidecar_cleanup_path¶

bool xmp_sidecar_cleanup_removed = false¶

struct PhaseOneRawGeometry¶

#include <phaseone_geometry.h>

Public Members

uint32_t sensor_width = 0¶

uint32_t sensor_height = 0¶

uint32_t sensor_left_margin = 0¶

uint32_t sensor_top_margin = 0¶

uint32_t image_width = 0¶

uint32_t image_height = 0¶

uint32_t active_x = 0¶

uint32_t active_y = 0¶

uint32_t active_width = 0¶

uint32_t active_height = 0¶

uint32_t right_margin = 0¶

uint32_t bottom_margin = 0¶

struct PhaseOneRawGeometryResult¶

#include <phaseone_geometry.h>

Public Members

PhaseOneRawGeometryStatus status = PhaseOneRawGeometryStatus::MissingField ¶

PhaseOneRawGeometry geometry¶

struct PhaseOneRawProcessingInfo¶

#include <phaseone_geometry.h>

Public Members

bool has_color_matrix1 = false¶

double color_matrix1[9] = {}¶

bool has_color_matrix2 = false¶

double color_matrix2[9] = {}¶

bool has_wb_rgb_levels = false¶

double wb_rgb_levels[3] = {}¶

bool has_black_level = false¶

uint32_t black_level = 0¶

bool has_sensor_temperature_c = false¶

double sensor_temperature_c = 0.0¶

bool has_sensor_temperature2_c = false¶

double sensor_temperature2_c = 0.0¶

bool has_raw_format = false¶

uint32_t raw_format = 0¶

bool has_raw_data = false¶

uint64_t raw_data_bytes = 0¶

bool has_strip_offsets = false¶

uint64_t strip_offsets_bytes = 0¶

bool has_black_level_data = false¶

uint64_t black_level_data_bytes = 0¶

bool has_sensor_calibration = false¶

uint32_t sensor_calibration_entry_count = 0¶

uint64_t sensor_calibration_payload_bytes = 0¶

bool has_sensor_defects = false¶

uint64_t sensor_defects_bytes = 0¶

bool has_flat_field = false¶

uint64_t flat_field_bytes = 0¶

bool has_linearization_coefficients = false¶

uint32_t linearization_coefficients_count = 0¶

struct PhaseOneRawProcessingResult¶

#include <phaseone_geometry.h>

Public Members

PhaseOneRawProcessingStatus status = PhaseOneRawProcessingStatus::MissingField ¶

uint32_t fields_seen = 0¶

uint32_t fields_decoded = 0¶

uint32_t invalid_fields = 0¶

PhaseOneRawProcessingInfo info¶

struct PhotoshopIrb¶

#include <meta_key.h>

Public Members

uint16_t resource_id = 0¶

struct PhotoshopIrb¶

#include <meta_key.h>

Public Members

uint16_t resource_id = 0¶

struct PhotoshopIrbDecodeLimits¶

#include <photoshop_irb_decode.h>

Resource limits applied during IRB decode to bound hostile inputs.

Public Members

uint32_t max_resources = 1U << 16¶

uint64_t max_total_bytes = 64ULL * 1024ULL * 1024ULL¶

uint32_t max_resource_len = 32U * 1024U * 1024U¶

struct PhotoshopIrbDecodeOptions¶

#include <photoshop_irb_decode.h>

Decoder options for decode_photoshop_irb.

Public Members

bool decode_iptc_iim = true¶

bool decode_xmp_packet = true¶

bool decode_icc_profile = true¶

PhotoshopIrbStringCharset string_charset = PhotoshopIrbStringCharset::Latin ¶

PhotoshopIrbDecodeLimits limits¶

IptcIimDecodeOptions iptc¶

XmpDecodeOptions xmp¶

IccDecodeOptions icc¶

struct PhotoshopIrbDecodeResult¶

#include <photoshop_irb_decode.h>

Public Members

PhotoshopIrbDecodeStatus status = PhotoshopIrbDecodeStatus::Ok ¶

uint32_t resources_decoded = 0¶

uint32_t entries_decoded = 0¶

uint32_t iptc_entries_decoded = 0¶

uint32_t xmp_entries_decoded = 0¶

uint32_t icc_entries_decoded = 0¶

struct PhotoshopIrbField¶

#include <meta_key.h>

Public Members

uint16_t resource_id = 0¶

ByteSpan field¶

struct PhotoshopIrbField¶

#include <meta_key.h>

Public Members

uint16_t resource_id = 0¶

std::string_view field¶

struct PlanJpegEditOptions¶

#include <metadata_transfer.h>

Options for JPEG edit planning.

Public Members

JpegEditMode mode = JpegEditMode::Auto ¶

bool require_in_place = false¶

bool skip_empty_payloads = true¶

bool strip_existing_xmp = false¶

struct PlanTiffEditOptions¶

#include <metadata_transfer.h>

Options for TIFF edit planning.

Public Members

bool require_updates = true¶: If true, fail planning when the bundle has no TIFF-applicable updates.

bool strip_existing_xmp = false¶

struct PngText¶

#include <meta_key.h>

Public Members

ByteSpan keyword¶

ByteSpan field¶

struct PngText¶

#include <meta_key.h>

Public Members

std::string_view keyword¶

std::string_view field¶

class PngTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for PNG metadata chunk emission.

Public Functions

virtual ~PngTransferEmitter() = default¶

virtual TransferStatus add_chunk(std::array<char, 4> type, std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus close_chunks() noexcept = 0¶

struct PreparedBmffEmitOp¶

#include <metadata_transfer.h>

One precompiled ISO-BMFF metadata emit operation.

Public Members

PreparedBmffEmitKind kind = PreparedBmffEmitKind::Item ¶

uint32_t block_index = 0¶

uint32_t item_type = 0U¶

uint32_t property_type = 0U¶

uint32_t property_subtype = 0U¶

struct PreparedBmffEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled ISO-BMFF metadata emit plan.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedBmffEmitOp> ops¶

struct PreparedExrEmitOp¶

#include <metadata_transfer.h>

One precompiled EXR emit operation (prepared block -> EXR attribute).

Public Members

uint32_t block_index = 0¶

struct PreparedExrEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled EXR emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedExrEmitOp> ops¶

struct PreparedJp2EmitOp¶

#include <metadata_transfer.h>

One precompiled JP2 emit operation (route -> JP2 box mapping).

Public Members

uint32_t block_index = 0¶

std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}¶

struct PreparedJp2EmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled JP2 emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedJp2EmitOp> ops¶

struct PreparedJpegEmitOp¶

#include <metadata_transfer.h>

One precompiled JPEG emit operation (route -> marker mapping).

Public Members

uint32_t block_index = 0¶

uint8_t marker_code = 0¶

struct PreparedJpegEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled JPEG emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedJpegEmitOp> ops¶

struct PreparedJxlEmitOp¶

#include <metadata_transfer.h>

One precompiled JPEG XL emit operation (route -> backend mapping).

Public Members

PreparedJxlEmitKind kind = PreparedJxlEmitKind::Box ¶

uint32_t block_index = 0¶

std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}¶

bool compress = false¶

struct PreparedJxlEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled JPEG XL emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedJxlEmitOp> ops¶

struct PreparedJxlEncoderHandoff¶

#include <metadata_transfer.h>

Owned JXL encoder-side handoff independent from bundle payload storage.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

bool has_icc_profile = false¶

uint32_t icc_block_index = 0xFFFFFFFFU¶

uint32_t box_count = 0U¶

uint64_t box_payload_bytes = 0U¶

std::vector<std::byte> icc_profile¶

struct PreparedJxlEncoderHandoffIoResult¶

#include <metadata_transfer.h>

Result for serializing or parsing persisted JXL encoder handoff data.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint64_t bytes = 0U¶

uint32_t errors = 0U¶

std::string message¶

struct PreparedJxlEncoderHandoffView¶

#include <metadata_transfer.h>

Encoder-side handoff view for prepared JPEG XL metadata.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

bool has_icc_profile = false¶

uint32_t icc_block_index = 0xFFFFFFFFU¶

uint64_t icc_profile_bytes = 0U¶

std::span<const std::byte> icc_profile¶

uint32_t box_count = 0U¶

uint64_t box_payload_bytes = 0U¶

struct PreparedPngEmitOp¶

#include <metadata_transfer.h>

One precompiled PNG emit operation (route -> PNG chunk mapping).

Public Members

uint32_t block_index = 0¶

std::array<char, 4> chunk_type = {'\0', '\0', '\0', '\0'}¶

struct PreparedPngEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled PNG emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedPngEmitOp> ops¶

struct PreparedTiffEmitOp¶

#include <metadata_transfer.h>

One precompiled TIFF emit operation (route -> TIFF tag mapping).

Public Members

uint32_t block_index = 0¶

uint16_t tiff_tag = 0¶

struct PreparedTiffEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled TIFF emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedTiffEmitOp> ops¶

struct PreparedTransferAdapterOp¶

#include <metadata_transfer.h>

One compiled adapter-facing operation derived from a prepared bundle.

Public Members

TransferAdapterOpKind kind = TransferAdapterOpKind::JpegMarker ¶

uint32_t block_index = 0U¶

uint64_t payload_size = 0U¶

uint64_t serialized_size = 0U¶

uint8_t jpeg_marker_code = 0U¶

uint16_t tiff_tag = 0U¶

std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}¶

std::array<char, 4> chunk_type = {'\0', '\0', '\0', '\0'}¶

uint32_t bmff_item_type = 0U¶

uint32_t bmff_property_type = 0U¶

uint32_t bmff_property_subtype = 0U¶

bool bmff_mime_xmp = false¶

bool compress = false¶

struct PreparedTransferAdapterView¶

#include <metadata_transfer.h>

One target-neutral adapter view over prepared transfer operations.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

EmitTransferOptions emit¶

std::vector<PreparedTransferAdapterOp> ops¶

struct PreparedTransferArtifactInfo¶

#include <metadata_transfer.h>

Common summary for one persisted transfer artifact.

Public Members

PreparedTransferArtifactKind kind = PreparedTransferArtifactKind::Unknown ¶

bool has_contract_version = false¶

uint32_t contract_version = 0U¶

bool has_target_format = false¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

uint32_t entry_count = 0U¶

uint64_t payload_bytes = 0U¶

uint64_t binding_bytes = 0U¶

uint64_t signed_payload_bytes = 0U¶

bool has_icc_profile = false¶

uint32_t icc_block_index = 0xFFFFFFFFU¶

uint64_t icc_profile_bytes = 0U¶

uint64_t box_payload_bytes = 0U¶

std::string carrier_route¶

std::string manifest_label¶

struct PreparedTransferArtifactIoResult¶

#include <metadata_transfer.h>

Result for identifying and inspecting one persisted transfer artifact.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint64_t bytes = 0U¶

uint32_t errors = 0U¶

std::string message¶

struct PreparedTransferBlock¶

#include <metadata_transfer.h>

One container-ready payload in emit order.

Public Members

TransferBlockKind kind = TransferBlockKind::Other ¶

uint32_t order = 0¶

std::string route¶: Route token for backend dispatch, for example: jpeg:app1-exif.

std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}¶: Optional 4CC when route is box-based (Exif, xml, jumb…).

std::vector<std::byte> payload¶: Payload bytes as prepared by the transfer packager.

struct PreparedTransferBundle¶

#include <metadata_transfer.h>

Immutable prepared metadata transfer artifact.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

DngTargetMode dng_target_mode = DngTargetMode::MinimalFreshScaffold ¶

TransferProfile profile¶

PreparedTransferC2paRewriteRequirements c2pa_rewrite¶

std::vector<PreparedTransferPolicyDecision> policy_decisions¶

std::vector<PreparedTransferBlock> blocks¶

std::vector<TimePatchSlot> time_patch_map¶

std::vector<std::byte> generated_xmp_sidecar¶

struct PreparedTransferC2paHandoffPackage¶

#include <metadata_transfer.h>

Structured external-signer handoff package for one prepared rewrite.

Public Members

PreparedTransferC2paSignRequest request¶

BuildPreparedC2paBindingResult binding¶

std::vector<std::byte> binding_bytes¶

struct PreparedTransferC2paPackageIoResult¶

#include <metadata_transfer.h>

Result for serializing or parsing persisted C2PA transfer packages.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint64_t bytes = 0¶

uint32_t errors = 0¶

std::string message¶

struct PreparedTransferC2paRewriteChunk¶

#include <metadata_transfer.h>

One deterministic chunk in the rewrite-without-C2PA byte stream.

Public Members

TransferC2paRewriteChunkKind kind = TransferC2paRewriteChunkKind::SourceRange ¶

uint64_t source_offset = 0¶

uint64_t size = 0¶

uint32_t block_index = 0xFFFFFFFFU¶

uint8_t jpeg_marker_code = 0U¶

struct PreparedTransferC2paRewriteRequirements¶

#include <metadata_transfer.h>

Future-facing signer prerequisites for C2PA rewrite.

Public Members

TransferC2paRewriteState state = TransferC2paRewriteState::NotApplicable ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

TransferC2paSourceKind source_kind = TransferC2paSourceKind::NotApplicable ¶

uint32_t matched_entries = 0¶

uint32_t existing_carrier_segments = 0¶

bool target_carrier_available = false¶

bool content_change_invalidates_existing = false¶

bool requires_manifest_builder = false¶

bool requires_content_binding = false¶

bool requires_certificate_chain = false¶

bool requires_private_key = false¶

bool requires_signing_time = false¶

uint64_t content_binding_bytes = 0¶

std::vector<PreparedTransferC2paRewriteChunk> content_binding_chunks¶

std::string message¶

struct PreparedTransferC2paSignedPackage¶

#include <metadata_transfer.h>

Persistable external-signer result package for one prepared rewrite.

Public Members

PreparedTransferC2paSignRequest request¶

PreparedTransferC2paSignerInput signer_input¶

struct PreparedTransferC2paSignerInput¶

#include <metadata_transfer.h>

External signer material returned for one prepared C2PA rewrite request.

Public Members

std::string signing_time¶

std::vector<std::byte> certificate_chain_bytes¶

std::string private_key_reference¶

std::vector<std::byte> manifest_builder_output¶

std::vector<std::byte> signed_c2pa_logical_payload¶

struct PreparedTransferC2paSignRequest¶

#include <metadata_transfer.h>

Derived external signer input request for prepared C2PA rewrite.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

TransferC2paRewriteState rewrite_state = TransferC2paRewriteState::NotApplicable ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

TransferC2paSourceKind source_kind = TransferC2paSourceKind::NotApplicable ¶

std::string carrier_route¶

std::string manifest_label¶

uint32_t existing_carrier_segments = 0¶

uint32_t source_range_chunks = 0¶

uint32_t prepared_segment_chunks = 0¶

uint64_t content_binding_bytes = 0¶

std::vector<PreparedTransferC2paRewriteChunk> content_binding_chunks¶

bool requires_manifest_builder = false¶

bool requires_content_binding = false¶

bool requires_certificate_chain = false¶

bool requires_private_key = false¶

bool requires_signing_time = false¶

std::string message¶

struct PreparedTransferExecutionPlan¶

#include <metadata_transfer.h>

Reusable compiled execution plan for high-throughput transfer workflows.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

EmitTransferOptions emit¶

PreparedJpegEmitPlan jpeg_emit¶

PreparedTiffEmitPlan tiff_emit¶

PreparedJxlEmitPlan jxl_emit¶

PreparedWebpEmitPlan webp_emit¶

PreparedPngEmitPlan png_emit¶

PreparedJp2EmitPlan jp2_emit¶

PreparedExrEmitPlan exr_emit¶

PreparedBmffEmitPlan bmff_emit¶

struct PreparedTransferPackageBatch¶

#include <metadata_transfer.h>

One owned final-output batch independent from input bytes or bundle storage.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

uint64_t input_size = 0¶

uint64_t output_size = 0¶

std::vector<PreparedTransferPackageBlob> chunks¶

struct PreparedTransferPackageBlob¶

#include <metadata_transfer.h>

One owned output chunk materialized from a package plan.

Public Members

TransferPackageChunkKind kind = TransferPackageChunkKind::SourceRange ¶

uint64_t output_offset = 0¶

uint64_t source_offset = 0¶

uint32_t block_index = 0xFFFFFFFFU¶

uint8_t jpeg_marker_code = 0U¶

std::string route¶

std::vector<std::byte> bytes¶

struct PreparedTransferPackageChunk¶

#include <metadata_transfer.h>

One deterministic output chunk for a packaged transfer write.

Public Members

TransferPackageChunkKind kind = TransferPackageChunkKind::SourceRange ¶

uint64_t output_offset = 0¶

uint64_t source_offset = 0¶

uint64_t size = 0¶

uint32_t block_index = 0xFFFFFFFFU¶

uint8_t jpeg_marker_code = 0U¶

std::vector<std::byte> inline_bytes¶

struct PreparedTransferPackageIoResult¶

#include <metadata_transfer.h>

Result for serializing or parsing persisted transfer package batches.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint64_t bytes = 0¶

uint32_t errors = 0¶

std::string message¶

struct PreparedTransferPackagePlan¶

#include <metadata_transfer.h>

Deterministic chunk plan for a final transfer output.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

uint64_t input_size = 0¶

uint64_t output_size = 0¶

std::vector<PreparedTransferPackageChunk> chunks¶

struct PreparedTransferPackageReplayCallbacks¶

#include <metadata_transfer.h>

Replay callbacks for replay_prepared_transfer_package_batch.

Public Members

TransferStatus (*begin_batch)(void *user, TransferTargetFormat target_format, uint32_t chunk_count) noexcept = nullptr¶

TransferStatus (*emit_chunk)(void *user, const PreparedTransferPackageView *view) noexcept = nullptr¶

TransferStatus (*end_batch)(void *user, TransferTargetFormat target_format) noexcept = nullptr¶

void *user = nullptr¶

struct PreparedTransferPackageReplayResult¶

#include <metadata_transfer.h>

Result for target-neutral package-batch replay.

Public Members

TransferStatus status = TransferStatus::Ok ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint32_t replayed = 0¶

uint32_t failed_chunk_index = 0xFFFFFFFFU¶

std::string message¶

struct PreparedTransferPackageView¶

#include <metadata_transfer.h>

One zero-copy semantic view over a persisted transfer package chunk.

Public Members

TransferSemanticKind semantic_kind = TransferSemanticKind::Unknown ¶

std::string_view route¶

TransferPackageChunkKind package_kind = TransferPackageChunkKind::SourceRange ¶

uint64_t output_offset = 0¶

uint8_t jpeg_marker_code = 0U¶

std::span<const std::byte> bytes¶

struct PreparedTransferPayload¶

#include <metadata_transfer.h>

One owned semantic payload copied from a prepared transfer bundle.

Public Members

TransferSemanticKind semantic_kind = TransferSemanticKind::Unknown ¶

std::string semantic_name¶

std::string route¶

PreparedTransferAdapterOp op¶

std::vector<std::byte> payload¶

struct PreparedTransferPayloadBatch¶

#include <metadata_transfer.h>

One owned semantic payload batch independent from bundle payload storage.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

EmitTransferOptions emit¶

std::vector<PreparedTransferPayload> payloads¶

struct PreparedTransferPayloadIoResult¶

#include <metadata_transfer.h>

Result for serializing or parsing persisted transfer payload batches.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint64_t bytes = 0¶

uint32_t errors = 0¶

std::string message¶

struct PreparedTransferPayloadReplayCallbacks¶

#include <metadata_transfer.h>

Replay callbacks for replay_prepared_transfer_payload_batch.

Public Members

TransferStatus (*begin_batch)(void *user, TransferTargetFormat target_format, uint32_t payload_count) noexcept = nullptr¶

TransferStatus (*emit_payload)(void *user, const PreparedTransferPayloadView *view) noexcept = nullptr¶

TransferStatus (*end_batch)(void *user, TransferTargetFormat target_format) noexcept = nullptr¶

void *user = nullptr¶

struct PreparedTransferPayloadReplayResult¶

#include <metadata_transfer.h>

Result for target-neutral payload-batch replay.

Public Members

TransferStatus status = TransferStatus::Ok ¶

EmitTransferCode code = EmitTransferCode::None ¶

uint32_t replayed = 0¶

uint32_t failed_payload_index = 0xFFFFFFFFU¶

std::string message¶

struct PreparedTransferPayloadView¶

#include <metadata_transfer.h>

One zero-copy semantic payload view over a prepared transfer bundle.

Public Members

TransferSemanticKind semantic_kind = TransferSemanticKind::Unknown ¶

std::string_view semantic_name¶

std::string_view route¶

PreparedTransferAdapterOp op¶

std::span<const std::byte> payload¶

struct PreparedTransferPolicyDecision¶

#include <metadata_transfer.h>

Effective policy decision captured during bundle preparation.

Public Members

TransferPolicySubject subject = TransferPolicySubject::MakerNote ¶

TransferPolicyAction requested = TransferPolicyAction::Keep ¶

TransferPolicyAction effective = TransferPolicyAction::Keep ¶

TransferPolicyReason reason = TransferPolicyReason::Default ¶

TransferC2paMode c2pa_mode = TransferC2paMode::NotApplicable ¶

TransferC2paSourceKind c2pa_source_kind = TransferC2paSourceKind::NotApplicable ¶

TransferC2paPreparedOutput c2pa_prepared_output = TransferC2paPreparedOutput::NotApplicable ¶

uint32_t matched_entries = 0¶

std::string message¶

struct PreparedWebpEmitOp¶

#include <metadata_transfer.h>

One precompiled WebP emit operation (route -> RIFF chunk mapping).

Public Members

uint32_t block_index = 0¶

std::array<char, 4> chunk_type = {'\0', '\0', '\0', '\0'}¶

struct PreparedWebpEmitPlan¶

#include <metadata_transfer.h>

Reusable precompiled WebP emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion ¶

std::vector<PreparedWebpEmitOp> ops¶

struct PrepareTransferFileOptions¶

#include <metadata_transfer.h>

File-read + decode options for prepare_metadata_for_target_file.

Public Members

bool include_pointer_tags = true¶

bool decode_makernote = false¶

bool decode_embedded_containers = true¶

bool decompress = true¶

std::string xmp_existing_sidecar_base_path¶

std::string xmp_existing_destination_embedded_path¶

XmpExistingSidecarMode xmp_existing_sidecar_mode = XmpExistingSidecarMode::Ignore ¶

XmpExistingSidecarPrecedence xmp_existing_sidecar_precedence = XmpExistingSidecarPrecedence::SidecarWins ¶

XmpExistingDestinationEmbeddedMode xmp_existing_destination_embedded_mode = XmpExistingDestinationEmbeddedMode::Ignore ¶

XmpExistingDestinationEmbeddedPrecedence xmp_existing_destination_embedded_precedence = XmpExistingDestinationEmbeddedPrecedence::DestinationWins ¶

XmpExistingDestinationCarrierPrecedence xmp_existing_destination_carrier_precedence = XmpExistingDestinationCarrierPrecedence::SidecarWins ¶

OpenMetaResourcePolicy policy¶

PrepareTransferRequest prepare¶

struct PrepareTransferFileResult¶

#include <metadata_transfer.h>

High-level file read/prepare result.

Public Members

TransferFileStatus file_status = TransferFileStatus::Ok ¶

PrepareTransferFileCode code = PrepareTransferFileCode::None ¶

uint64_t file_size = 0¶

uint32_t entry_count = 0¶

bool xmp_existing_sidecar_loaded = false¶

TransferStatus xmp_existing_sidecar_status = TransferStatus::Unsupported ¶

std::string xmp_existing_sidecar_message¶

std::string xmp_existing_sidecar_path¶

bool xmp_existing_destination_embedded_loaded = false¶

TransferStatus xmp_existing_destination_embedded_status = TransferStatus::Unsupported ¶

std::string xmp_existing_destination_embedded_message¶

std::string xmp_existing_destination_embedded_path¶

SimpleMetaResult read¶

PrepareTransferResult prepare¶

PreparedTransferBundle bundle¶

struct PrepareTransferRequest¶

#include <metadata_transfer.h>

Request options for preparation.

Public Members

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

DngTargetMode dng_target_mode = DngTargetMode::MinimalFreshScaffold ¶

TransferProfile profile¶

TransferTargetImageSpec target_image_spec¶

TransferRawCarrierPassthroughMode raw_carrier_passthrough_mode = TransferRawCarrierPassthroughMode::Disabled ¶: Disabled by default. Currently used only for snapshot preparation.

bool include_exif_app1 = true¶

bool include_xmp_app1 = true¶

bool include_icc_app2 = true¶

bool include_iptc_app13 = true¶

bool xmp_portable = true¶

bool xmp_project_exif = true¶

bool xmp_project_iptc = true¶

bool xmp_include_existing = true¶

XmpExistingNamespacePolicy xmp_existing_namespace_policy = XmpExistingNamespacePolicy::KnownPortableOnly ¶

XmpExistingStandardNamespacePolicy xmp_existing_standard_namespace_policy = XmpExistingStandardNamespacePolicy::PreserveAll ¶

XmpConflictPolicy xmp_conflict_policy = XmpConflictPolicy::CurrentBehavior ¶

bool xmp_exiftool_gpsdatetime_alias = false¶

struct PrepareTransferResult¶

#include <metadata_transfer.h>

Result details for preparation.

Public Members

TransferStatus status = TransferStatus::Ok ¶

PrepareTransferCode code = PrepareTransferCode::None ¶

uint32_t warnings = 0¶

uint32_t errors = 0¶

std::string message¶

struct PreviewCandidate¶

#include <preview_extract.h>

Preview candidate discovered in a container.

Public Members

PreviewKind kind = PreviewKind::ExifJpegInterchange ¶

ContainerFormat format = ContainerFormat::Unknown ¶

uint32_t block_index = 0¶

uint16_t offset_tag = 0¶

uint16_t length_tag = 0¶

uint64_t file_offset = 0¶

uint64_t size = 0¶

bool has_jpeg_soi_signature = false¶

struct PreviewExtractOptions¶

#include <preview_extract.h>

Options for preview extraction.

Public Members

uint64_t max_output_bytes = 128ULL * 1024ULL * 1024ULL¶

bool require_jpeg_soi = false¶

struct PreviewExtractResult¶

#include <preview_extract.h>

Result for preview extraction.

Public Members

PreviewExtractStatus status = PreviewExtractStatus::Ok ¶

uint64_t written = 0¶

uint64_t needed = 0¶

struct PreviewScanLimits¶

#include <preview_extract.h>

Limits for preview candidate discovery.

Public Members

uint32_t max_ifds = 256¶

uint32_t max_total_entries = 8192¶

uint64_t max_preview_bytes = 512ULL * 1024ULL * 1024ULL¶

struct PreviewScanOptions¶

#include <preview_extract.h>

Options for preview candidate discovery.

Public Members

bool include_exif_jpeg_interchange = true¶

bool include_jpg_from_raw = true¶

bool include_cr3_prvw_jpeg = true¶

bool require_jpeg_soi = false¶

PreviewScanLimits limits¶

struct PreviewScanResult¶

#include <preview_extract.h>

Result for preview candidate discovery.

Public Members

PreviewScanStatus status = PreviewScanStatus::Ok ¶

uint32_t written = 0¶

uint32_t needed = 0¶

struct PrintImDecodeLimits¶

#include <printim_decode.h>

Resource limits for decoding a PrintIM block.

Public Members

uint32_t max_entries = 4096¶: Maximum number of PrintIM entries to decode.

uint64_t max_bytes = 256ULL * 1024ULL¶: Maximum input bytes to accept (0 = unlimited).

struct PrintImDecodeResult¶

#include <printim_decode.h>

PrintIM decode result summary.

Public Members

PrintImDecodeStatus status = PrintImDecodeStatus::Unsupported ¶

uint32_t entries_decoded = 0¶

struct PrintImField¶

#include <meta_key.h>

Public Members

ByteSpan field¶

struct PrintImField¶

#include <meta_key.h>

Public Members

std::string_view field¶

struct ReadTransferSourceSnapshotBytesResult¶

#include <metadata_transfer.h>

High-level in-memory read result for read_transfer_source_snapshot_bytes.

API Stability: Experimental host-facing API.

Public Members

TransferStatus status = TransferStatus::Ok ¶

ReadTransferSourceSnapshotBytesCode code = ReadTransferSourceSnapshotBytesCode::None ¶

uint64_t input_size = 0¶

uint32_t entry_count = 0¶

uint32_t raw_carrier_count = 0U¶

uint64_t raw_carrier_bytes = 0U¶

bool raw_carrier_bytes_truncated = false¶

SimpleMetaResult read¶

TransferSourceSnapshot snapshot¶

struct ReadTransferSourceSnapshotFileOptions¶

#include <metadata_transfer.h>

File-read + decode options for read_transfer_source_snapshot_file.

API Stability: Experimental host-facing API.

Public Members

bool include_pointer_tags = true¶

bool decode_makernote = false¶

bool decode_embedded_containers = true¶

bool decompress = true¶

bool preserve_raw_carriers = false¶

uint64_t max_raw_carrier_bytes = 64ULL * 1024ULL * 1024ULL¶

OpenMetaResourcePolicy policy¶

struct ReadTransferSourceSnapshotFileResult¶

#include <metadata_transfer.h>

High-level file read result for read_transfer_source_snapshot_file.

API Stability: Experimental host-facing API.

Public Members

TransferFileStatus file_status = TransferFileStatus::Ok ¶

ReadTransferSourceSnapshotFileCode code = ReadTransferSourceSnapshotFileCode::None ¶

uint64_t file_size = 0¶

uint32_t entry_count = 0¶

uint32_t raw_carrier_count = 0U¶

uint64_t raw_carrier_bytes = 0U¶

bool raw_carrier_bytes_truncated = false¶

SimpleMetaResult read¶

TransferSourceSnapshot snapshot¶

struct ScanResult¶

#include <container_scan.h>

Public Members

ScanStatus status = ScanStatus::Ok ¶

uint32_t written = 0¶

uint32_t needed = 0¶

struct SimpleMetaDecodeOptions¶

#include <simple_meta.h>

Full decoder option set for simple_meta_read.

Public Members

ExifDecodeOptions exif¶

PayloadOptions payload¶

XmpDecodeOptions xmp¶

ExrDecodeOptions exr¶

JumbfDecodeOptions jumbf¶

IccDecodeOptions icc¶

IptcIimDecodeOptions iptc¶

PhotoshopIrbDecodeOptions photoshop_irb¶

struct SimpleMetaResult¶

#include <simple_meta.h>

Public Members

ScanResult scan¶

PayloadResult payload¶

ExrDecodeResult exr¶

ExifDecodeResult exif¶

JumbfDecodeResult jumbf¶

XmpDecodeResult xmp¶

class SpanTransferByteWriter : public openmeta::TransferByteWriter ¶

#include <metadata_transfer.h>

Fixed-buffer writer for encoder integrations with preallocated memory.

Public Functions

inline explicit SpanTransferByteWriter(std::span<std::byte> buffer) noexcept¶

inline virtual TransferStatus write(std::span<const std::byte> bytes) noexcept override¶

inline void reset() noexcept¶

inline size_t capacity() const noexcept¶

inline size_t bytes_written() const noexcept¶

inline size_t remaining() const noexcept¶

inline TransferStatus status() const noexcept¶

inline virtual uint64_t remaining_capacity_hint() const noexcept override¶

inline std::span<const std::byte> written_bytes() const noexcept¶

Private Members

std::span<std::byte> buffer_¶

size_t written_ = 0U¶

TransferStatus status_ = TransferStatus::Ok ¶

struct SRational¶

#include <meta_value.h>

Signed rational (numerator/denominator), typically used by EXIF/TIFF.

Public Members

int32_t numer = 0¶

int32_t denom = 1¶

struct TiffEditPlan¶

#include <metadata_transfer.h>

Planned TIFF edit summary (draft API).

Public Members

TransferStatus status = TransferStatus::Ok ¶

uint32_t tag_updates = 0¶

bool has_exif_ifd = false¶

bool strip_existing_xmp = false¶

uint64_t input_size = 0¶

uint64_t output_size = 0¶

std::string message¶

class TiffTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for TIFF metadata emission.

Public Functions

virtual ~TiffTransferEmitter() = default¶

virtual TransferStatus set_tag_u32(uint16_t tag, uint32_t value) noexcept = 0¶

virtual TransferStatus set_tag_bytes(uint16_t tag, std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus commit_exif_directory(uint64_t *out_ifd_offset) noexcept = 0¶

struct TimePatchSlot¶

#include <metadata_transfer.h>

One fixed-width patch location in a prepared payload block.

Public Members

TimePatchField field = TimePatchField::DateTime ¶

uint32_t block_index = 0¶

uint32_t byte_offset = 0¶

uint16_t width = 0¶

struct TimePatchUpdate¶

#include <metadata_transfer.h>

One time patch update payload for apply_time_patches.

Public Members

TimePatchField field = TimePatchField::DateTime ¶

std::vector<std::byte> value¶

struct TimePatchView¶

#include <metadata_transfer.h>

Non-owning time patch view for hot-path transfer execution.

Public Members

TimePatchField field = TimePatchField::DateTime ¶

std::span<const std::byte> value¶

class TransferAdapterSink¶

#include <metadata_transfer.h>

Generic host-side sink for adapter-view transfer operations.

Public Functions

virtual ~TransferAdapterSink() = default¶

virtual TransferStatus emit_op(const PreparedTransferAdapterOp &op, std::span<const std::byte> payload) noexcept = 0¶

class TransferByteWriter¶

#include <metadata_transfer.h>

Streaming byte sink for edit/write transfer paths.

Subclassed by openmeta::SpanTransferByteWriter

Public Functions

virtual ~TransferByteWriter() = default¶

virtual TransferStatus write(std::span<const std::byte> bytes) noexcept = 0¶

inline virtual uint64_t remaining_capacity_hint() const noexcept¶

struct TransferCompatibilityDumpOptions¶

#include <compatibility_dump.h>

Options for dump_transfer_compatibility.

Public Members

bool include_prepared_blocks = true¶

bool include_policy_decisions = true¶

bool include_writeback_summary = true¶

uint32_t max_message_bytes = 256U¶

struct TransferConceptDiagnostic¶

#include <metadata_transfer.h>

Public Members

MetadataConceptKind kind = MetadataConceptKind::Orientation ¶

MetadataConceptRole role = MetadataConceptRole::Primary ¶

MetadataConceptTransferHint hint = MetadataConceptTransferHint::Unknown ¶

TransferConceptDiagnosticAction action = TransferConceptDiagnosticAction::Drop ¶

TransferConceptDiagnosticReason reason = TransferConceptDiagnosticReason::Unknown ¶

TransferConceptDiagnosticSeverity severity = TransferConceptDiagnosticSeverity::Warning ¶

EntryId entry_id = kInvalidEntryId ¶

std::vector<EntryId> source_entries¶

bool preferred = false¶

bool conflict = false¶

bool compatible_file_safe = false¶

bool rendered_image_safe = false¶

bool requires_target_image_spec = false¶

bool source_bound = false¶

bool has_gps_altitude_reference = false¶

bool gps_altitude_below_sea_level = false¶

uint8_t gps_altitude_reference_code = 0U¶

struct TransferConceptDiagnostics¶

#include <metadata_transfer.h>

Public Members

TransferSafetyMode safety = TransferSafetyMode::CompatibleFile ¶

uint32_t candidate_count = 0U¶

uint32_t kept_count = 0U¶

uint32_t dropped_count = 0U¶

uint32_t requires_target_image_spec_count = 0U¶

uint32_t rendered_unsafe_count = 0U¶

uint32_t source_bound_count = 0U¶

uint32_t conflict_count = 0U¶

std::vector<TransferConceptDiagnostic> diagnostics¶

struct TransferProfile¶

#include <metadata_transfer.h>

Transfer policy profile for initial no-edits workflows.

Public Members

TransferPolicyAction makernote = TransferPolicyAction::Keep ¶

TransferPolicyAction jumbf = TransferPolicyAction::Keep ¶

TransferPolicyAction c2pa = TransferPolicyAction::Keep ¶

bool allow_time_patch = true¶

TransferSafetyMode safety = TransferSafetyMode::CompatibleFile ¶

struct TransferRawCarrierPassthroughAudit¶

#include <metadata_transfer.h>

Diagnostic summary for raw-carrier passthrough eligibility.

Public Members

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

TransferSafetyMode safety = TransferSafetyMode::CompatibleFile ¶

uint32_t carrier_count = 0U¶

uint32_t eligible_count = 0U¶

uint32_t blocked_missing_payload = 0U¶

uint32_t blocked_target_incompatible = 0U¶

uint32_t blocked_safety_filtered = 0U¶

uint32_t blocked_content_bound_metadata = 0U¶

uint32_t blocked_policy = 0U¶

uint32_t blocked_decode_link_unavailable = 0U¶

uint32_t blocked_unsupported_kind = 0U¶

std::vector<TransferRawCarrierPassthroughDecision> decisions¶

struct TransferRawCarrierPassthroughAuditOptions¶

#include <metadata_transfer.h>

Options for auditing raw-carrier passthrough eligibility.

Public Members

TransferTargetFormat target_format = TransferTargetFormat::Jpeg ¶

TransferProfile profile¶

bool require_decoded_entry_links = true¶

struct TransferRawCarrierPassthroughDecision¶

#include <metadata_transfer.h>

One raw-carrier passthrough eligibility decision.

Public Members

uint32_t carrier_index = 0U¶

uint32_t decoded_entry_count = 0U¶

TransferBlockKind semantic_kind = TransferBlockKind::Other ¶

bool eligible = false¶

TransferRawCarrierPassthroughReason reason = TransferRawCarrierPassthroughReason::UnsupportedKind ¶

std::string source_route¶

std::string target_route¶

struct TransferSafetyAudit¶

#include <metadata_transfer.h>

Source metadata and filtered-entry counts for one transfer safety mode.

Public Members

TransferSafetyMode safety = TransferSafetyMode::CompatibleFile ¶

uint32_t source_image_properties = 0U¶

uint32_t source_raw_color_calibration = 0U¶

uint32_t source_camera_raw_settings = 0U¶

uint32_t source_icc_profiles = 0U¶

uint32_t source_makernotes = 0U¶

uint32_t source_non_c2pa_jumbf = 0U¶

uint32_t source_c2pa = 0U¶

uint32_t filtered_image_properties = 0U¶

uint32_t filtered_raw_color_calibration = 0U¶

uint32_t filtered_camera_raw_settings = 0U¶

uint32_t filtered_icc_profiles = 0U¶

uint32_t filtered_makernotes = 0U¶

uint32_t filtered_non_c2pa_jumbf = 0U¶

uint32_t invalidated_c2pa = 0U¶

VendorRawProcessingSummary sony_raw_processing¶

VendorRawProcessingSummary canon_raw_processing¶

VendorRawProcessingSummary nikon_raw_processing¶

VendorRawProcessingSummary fujifilm_raw_processing¶

VendorRawProcessingSummary pentax_raw_processing¶

VendorRawProcessingSummary panasonic_raw_processing¶

VendorRawProcessingSummary olympus_raw_processing¶

VendorRawProcessingSummary kodak_raw_processing¶

VendorRawProcessingSummary minolta_raw_processing¶

VendorRawProcessingSummary sigma_raw_processing¶

VendorRawProcessingSummary samsung_raw_processing¶

VendorRawProcessingSummary ricoh_raw_processing¶

VendorRawProcessingSummary apple_raw_processing¶

VendorRawProcessingSummary dji_raw_processing¶

VendorRawProcessingSummary google_raw_processing¶

VendorRawProcessingSummary flir_raw_processing¶

VendorRawProcessingSummary casio_raw_processing¶

VendorRawProcessingSummary sanyo_raw_processing¶

VendorRawProcessingSummary kyocera_raw_processing¶

VendorRawProcessingSummary reconyx_raw_processing¶

VendorRawProcessingSummary hp_raw_processing¶

VendorRawProcessingSummary jvc_raw_processing¶

VendorRawProcessingSummary ge_raw_processing¶

VendorRawProcessingSummary motorola_raw_processing¶

VendorRawProcessingSummary nintendo_raw_processing¶

VendorRawProcessingSummary microsoft_raw_processing¶

struct TransferSourceRawCarrier¶

#include <metadata_transfer.h>

One opt-in raw source carrier captured next to a decoded snapshot.

Public Members

ContainerBlockRef block¶: Original container block reference, including byte ranges and chunking.

TransferBlockKind semantic_kind = TransferBlockKind::Other ¶: Transfer semantic family inferred from the scanned block kind.

uint32_t order = 0U¶: Scan order among preserved source carriers.

std::string route¶: Stable route hint for passthrough and decoded re-emission policy.

bool payload_preserved = false¶: True when payload contains the original block payload bytes.

std::vector<std::byte> payload¶: Original metadata payload bytes, bounded by read options.

std::vector<EntryId> decoded_entry_ids¶: Decoded MetaStore entry ids attributed to this source carrier.

struct TransferSourceSnapshot¶

#include <metadata_transfer.h>

Reusable source snapshot for later transfer preparation.

Const reuse is safe when callers do not mutate the snapshot and do not share returned result objects across writers.

API Stability: Experimental host-facing API. The default snapshot remains decoded-store backed. Raw carrier provenance and payload bytes are kept only when read options explicitly request them; transfer preparation still uses decoded re-emission unless the request enables an explicit bounded passthrough mode.

Public Members

MetaStore store¶

std::vector<TransferSourceRawCarrier> raw_carriers¶

uint64_t raw_carrier_bytes = 0U¶

bool raw_carrier_bytes_truncated = false¶

struct TransferTargetImageSpec¶

#include <metadata_transfer.h>

Host-supplied target image facts for content-changing transfer.

These values describe the actual output image buffer/container, not the source metadata. When present, prepared transfer uses these target facts for generated EXIF/XMP image-layout fields after filtering stale source fields. Leave fields unset when the host cannot guarantee that the value matches the target pixels.

Public Members

bool has_dimensions = false¶

uint32_t width = 0U¶

uint32_t height = 0U¶

bool has_orientation = false¶

uint16_t orientation = 1U¶

bool has_samples_per_pixel = false¶

uint16_t samples_per_pixel = 0U¶

uint16_t bits_per_sample_count = 0U¶

std::array<uint16_t, kTransferTargetImageSpecMaxSamples> bits_per_sample = {}¶

uint16_t sample_format_count = 0U¶

std::array<uint16_t, kTransferTargetImageSpecMaxSamples> sample_format = {}¶

bool has_photometric_interpretation = false¶

uint16_t photometric_interpretation = 0U¶

bool has_planar_configuration = false¶

uint16_t planar_configuration = 1U¶

bool has_compression = false¶

uint16_t compression = 0U¶

bool has_exif_color_space = false¶

uint16_t exif_color_space = 0U¶

struct TransferTimePatchInput¶

#include <metadata_transfer.h>

One high-level time patch input for transfer execution helpers.

Public Members

TimePatchField field = TimePatchField::DateTime ¶

std::vector<std::byte> value¶

bool text_value = false¶

struct URational¶

#include <meta_value.h>

Unsigned rational (numerator/denominator), typically used by EXIF/TIFF.

Public Members

uint32_t numer = 0¶

uint32_t denom = 1¶

struct ValidateIssue¶

#include <validate.h>

One validation issue emitted by validate_file.

Public Members

ValidateIssueSeverity severity = ValidateIssueSeverity::Warning ¶

std::string category¶: Domain/category (scan, exif, ccm, file, …).

std::string code¶: Stable issue token (malformed, limit_exceeded, …).

std::string ifd¶: Optional source IFD token (for CCM issues).

std::string name¶: Optional source field/tag name (for CCM issues).

uint16_t tag = 0¶: Optional source tag id (for CCM issues).

std::string message¶: Human-readable details.

struct ValidateOptions¶

#include <validate.h>

Options for validate_file.

Public Members

bool include_pointer_tags = true¶

bool decode_makernote = false¶

bool decode_printim = true¶

bool decompress = true¶

bool include_xmp_sidecar = false¶

bool verify_c2pa = false¶

C2paVerifyBackend verify_backend = C2paVerifyBackend::Auto ¶

bool verify_require_trusted_chain = false¶

bool verify_require_resolved_references = false¶

bool warnings_as_errors = false¶: Treat warnings as failures in ValidateResult::failed.

CcmQueryOptions ccm¶: DNG/CCM query + validation options.

OpenMetaResourcePolicy policy¶: Resource budgets for decode/scans.

struct ValidatePreparedC2paSignResult¶

#include <metadata_transfer.h>

Result for validating one externally signed C2PA payload before staging.

Public Members

TransferStatus status = TransferStatus::Unsupported ¶

EmitTransferCode code = EmitTransferCode::None ¶

TransferC2paSignedPayloadKind payload_kind = TransferC2paSignedPayloadKind::NotApplicable ¶

TransferC2paSemanticStatus semantic_status = TransferC2paSemanticStatus::NotChecked ¶

uint64_t logical_payload_bytes = 0¶

uint64_t staged_payload_bytes = 0¶

uint64_t semantic_manifest_present = 0¶

uint64_t semantic_manifest_count = 0¶

uint64_t semantic_claim_generator_present = 0¶

uint64_t semantic_assertion_count = 0¶

uint64_t semantic_primary_claim_assertion_count = 0¶

uint64_t semantic_primary_claim_referenced_by_signature_count = 0¶

uint64_t semantic_primary_signature_linked_claim_count = 0¶

uint64_t semantic_primary_signature_reference_key_hits = 0¶

uint64_t semantic_primary_signature_explicit_reference_present = 0¶

uint64_t semantic_primary_signature_explicit_reference_resolved_claim_count = 0¶

uint64_t semantic_claim_count = 0¶

uint64_t semantic_signature_count = 0¶

uint64_t semantic_signature_linked = 0¶

uint64_t semantic_signature_orphan = 0¶

uint64_t semantic_explicit_reference_signature_count = 0¶

uint64_t semantic_explicit_reference_unresolved_signature_count = 0¶

uint64_t semantic_explicit_reference_ambiguous_signature_count = 0¶

uint32_t staged_segments = 0¶

uint32_t errors = 0¶

std::string semantic_reason¶

std::string message¶

struct ValidateResult¶

#include <validate.h>

Result of validate_file.

Public Members

ValidateStatus status = ValidateStatus::Ok ¶

uint64_t file_size = 0¶

SimpleMetaResult read¶: Decode summary from simple_meta_read.

CcmQueryResult ccm¶: CCM query summary from collect_dng_ccm_fields.

uint32_t ccm_fields = 0¶: Number of extracted CCM fields.

uint32_t entries = 0¶: Final decoded entry count.

uint32_t warning_count = 0¶

uint32_t error_count = 0¶

bool failed = false¶

std::vector<ValidateIssue> issues¶

struct VendorRawProcessingSummary¶

#include <vendor_raw_processing.h>

Public Members

uint32_t fields_seen = 0U¶

uint32_t color_fields = 0U¶

uint32_t white_balance_fields = 0U¶

uint32_t geometry_fields = 0U¶

uint32_t storage_fields = 0U¶

uint32_t lens_correction_fields = 0U¶

uint32_t raw_data_fields = 0U¶

uint32_t sensor_fields = 0U¶

uint32_t private_table_fields = 0U¶

uint32_t preview_fields = 0U¶

uint32_t face_geometry_fields = 0U¶

uint32_t computational_fields = 0U¶

uint32_t thermal_fields = 0U¶

uint32_t stitch_fields = 0U¶

class WebpTransferEmitter¶

#include <metadata_transfer.h>

Backend contract for WebP metadata chunk emission.

Public Functions

virtual ~WebpTransferEmitter() = default¶

virtual TransferStatus add_chunk(std::array<char, 4> type, std::span<const std::byte> payload) noexcept = 0¶

virtual TransferStatus close_chunks() noexcept = 0¶

struct WireType¶

#include <meta_store.h>

Wire-format element type + family (e.g. TIFF type code).

Public Members

WireFamily family = WireFamily::None ¶

uint16_t code = 0¶

struct XmpDecodeLimits¶

#include <xmp_decode.h>

Resource limits applied during XMP decode to bound hostile inputs.

Public Members

uint32_t max_depth = 128¶

uint32_t max_properties = 200000¶

uint64_t max_input_bytes = 64ULL * 1024ULL * 1024ULL¶: Caps the input XMP packet size (0 = unlimited).

uint32_t max_path_bytes = 1024¶: Max bytes per decoded property path string.

uint32_t max_value_bytes = 8U * 1024U * 1024U¶: Max text bytes per decoded value (element/attribute).

uint64_t max_total_value_bytes = 64ULL * 1024ULL * 1024ULL¶: Max total text bytes accumulated across values (0 = unlimited).

struct XmpDecodeOptions¶

#include <xmp_decode.h>

Decoder options for decode_xmp_packet.

Public Members

bool decode_description_attributes = true¶: If true, decodes attributes on rdf:Description as XMP properties.

XmpDecodeMalformedMode malformed_mode = XmpDecodeMalformedMode::Malformed ¶: Controls whether malformed XML should be reported as Malformed or as best-effort OutputTruncated.

XmpDecodeLimits limits¶

struct XmpDecodeResult¶

#include <xmp_decode.h>

Public Members

XmpDecodeStatus status = XmpDecodeStatus::Ok ¶

uint32_t entries_decoded = 0¶

struct XmpDumpLimits¶

#include <xmp_dump.h>

Resource limits applied during dump to bound output generation.

Public Members

uint64_t max_output_bytes = 0¶: If non-zero, refuse to generate output larger than this many bytes.

uint32_t max_entries = 0¶: If non-zero, refuse to emit more than this many entries.

struct XmpDumpOptions¶

#include <xmp_dump.h>

Dump options for dump_xmp_lossless.

Public Members

XmpDumpLimits limits¶

bool include_origin = true¶

bool include_wire = true¶: Includes wire family/code/count and EXR-specific wire type name when available.

bool include_flags = true¶

bool include_names = true¶

struct XmpDumpResult¶

#include <xmp_dump.h>

Dump result (size stats + how many entries were emitted).

Public Members

XmpDumpStatus status = XmpDumpStatus::Ok ¶

uint64_t written = 0¶

uint64_t needed = 0¶

uint32_t entries = 0¶

struct XmpPortableOptions¶

#include <xmp_dump.h>

Options for dump_xmp_portable.

Public Members

XmpDumpLimits limits¶

bool include_exif = true¶: Include TIFF/EXIF/GPS derived properties.

bool include_iptc = true¶: Include IPTC-IIM derived portable XMP properties.

bool include_existing_xmp = false¶: Include MetaKeyKind::XmpProperty entries already present in the store.

Note

Currently simple property_path values, indexed [n] paths, bounded lang-alt paths like title[@xml:lang=x-default], bounded one-level structured paths like CreatorContactInfo/CiEmailWork, bounded qualified one-level structured child paths like LocationShown[1]/xmp:Identifier[1], LocationShown[1]/exif:GPSLatitude, DerivedFrom/stRef:documentID, JobRef[1]/stJob:id, RenditionOf/stRef:filePath, Ingredients[1]/stRef:documentID, MaxPageSize/stDim:w, Fonts[1]/stFnt:fontName, Fonts[1]/stFnt:childFontFiles[1], Colorants[1]/xmpG:swatchName, SwatchGroups[1]/xmpG:groupName, ProjectRef/path, beatSpliceParams/riseInTimeDuration/scale, markers/cuePointParams/key, contributedMedia[1]/duration/scale, Tracks[1]/trackName, Tracks[1]/markers/name, Tracks[1]/markers/cuePointParams/key, resampleParams/quality, startTimecode/timeValue, timeScaleParams/quality, Pantry[1]/InstanceID, Pantry[1]/dc:format, videoFrameSize/stDim:w, videoAlphaPremultipleColor/xmpG:mode, Manifest[1]/stMfs:reference/stRef:filePath, and Versions[1]/stVer:event/stEvt:action, bounded indexed-structured paths like Licensee[1]/LicenseeName, bounded second-level structured scalar paths like CreatorContactInfo/CiAdrRegion/ProvinceName, bounded structured child indexed paths like CreatorContactInfo/CiAdrExtadr[1], and bounded structured child lang-alt paths like CreatorContactInfo/CiAdrCity[@xml:lang=x-default] are emitted. Known standard malformed flat structured child values like Creator[1]/Name and Creator[1]/Role are also promoted into the canonical lang-alt or indexed shapes when no explicit canonical child entries already exist. Known malformed Adobe structured child paths like DerivedFrom/documentID, JobRef[1]/id, Manifest[1]/reference/filePath, and Versions[1]/event/action are likewise promoted into their canonical qualified child prefixes. The same bounded promotion applies to known second-level standard shapes like CreatorContactInfo/CiAdrRegion/ProvinceName and CreatorContactInfo/CiAdrRegion/ProvinceCode. Bounded second-level structured child lang-alt paths like CreatorContactInfo/CiAdrRegion/ProvinceName[@xml:lang=x-default] and bounded second-level structured child indexed paths like CreatorContactInfo/CiAdrRegion/ProvinceCode[1] are also emitted.

XmpExistingNamespacePolicy existing_namespace_policy = XmpExistingNamespacePolicy::KnownPortableOnly ¶: Existing XMP namespace writeback policy for portable output.

XmpExistingStandardNamespacePolicy existing_standard_namespace_policy = XmpExistingStandardNamespacePolicy::PreserveAll ¶: Existing standard portable-namespace reconciliation policy.

XmpConflictPolicy conflict_policy = XmpConflictPolicy::CurrentBehavior ¶: Conflict policy between existing decoded XMP and generated portable EXIF/IPTC mappings.

bool exiftool_gpsdatetime_alias = false¶

Emit exif:GPSDateTime instead of exif:GPSTimeStamp for GPS time.

Default keeps standard portable naming. This compatibility mode is useful for tools that normalize XMP GPS time under GPSDateTime.

struct XmpProperty¶

#include <meta_key.h>

Public Members

ByteSpan schema_ns¶

ByteSpan property_path¶

struct XmpProperty¶

#include <meta_key.h>

Public Members

std::string_view schema_ns¶

std::string_view property_path¶

struct XmpSidecarOptions¶

#include <xmp_dump.h>

High-level sidecar options for dump_xmp_sidecar.

Public Members

XmpSidecarFormat format = XmpSidecarFormat::Lossless ¶

XmpDumpOptions lossless¶

XmpPortableOptions portable¶

uint64_t initial_output_bytes = 0¶: Initial output buffer size before automatic growth (0 uses default).

struct XmpSidecarRequest¶

#include <xmp_dump.h>

Stable flat request for sidecar export.

This shape is intended for wrapper/front-end APIs that need one option set independent of selected format.

Public Members

XmpSidecarFormat format = XmpSidecarFormat::Lossless ¶

XmpDumpLimits limits¶

bool include_exif = true¶: Portable mode options (applied when format == Portable).

bool include_iptc = true¶

bool include_existing_xmp = false¶

XmpExistingNamespacePolicy portable_existing_namespace_policy = XmpExistingNamespacePolicy::KnownPortableOnly ¶

XmpExistingStandardNamespacePolicy portable_existing_standard_namespace_policy = XmpExistingStandardNamespacePolicy::PreserveAll ¶

XmpConflictPolicy portable_conflict_policy = XmpConflictPolicy::CurrentBehavior ¶

bool portable_exiftool_gpsdatetime_alias = false¶

bool include_origin = true¶: Lossless mode options (applied when format == Lossless).

bool include_wire = true¶

bool include_flags = true¶

bool include_names = true¶

uint64_t initial_output_bytes = 0¶: Initial output buffer size before automatic growth (0 uses default).

namespace openmeta¶

Scalar constructors

MetaValue make_u8(uint8_t value) noexcept¶

MetaValue make_i8(int8_t value) noexcept¶

MetaValue make_u16(uint16_t value) noexcept¶

MetaValue make_i16(int16_t value) noexcept¶

MetaValue make_u32(uint32_t value) noexcept¶

MetaValue make_i32(int32_t value) noexcept¶

MetaValue make_u64(uint64_t value) noexcept¶

MetaValue make_i64(int64_t value) noexcept¶

MetaValue make_f32_bits(uint32_t bits) noexcept¶

MetaValue make_f64_bits(uint64_t bits) noexcept¶

MetaValue make_urational(uint32_t numer, uint32_t denom) noexcept¶

MetaValue make_srational(int32_t numer, int32_t denom) noexcept¶

Arena-backed constructors

MetaValue make_bytes(ByteArena &arena, std::span<const std::byte> bytes)¶

MetaValue make_text(ByteArena &arena, std::string_view text, TextEncoding encoding)¶

MetaValue make_array(ByteArena &arena, MetaElementType elem_type, std::span<const std::byte> raw_elements, uint32_t element_size)¶

Convenience array constructors

MetaValue make_u8_array(ByteArena &arena, std::span<const uint8_t> values)¶

MetaValue make_i8_array(ByteArena &arena, std::span<const int8_t> values)¶

MetaValue make_u16_array(ByteArena &arena, std::span<const uint16_t> values)¶

MetaValue make_i16_array(ByteArena &arena, std::span<const int16_t> values)¶

MetaValue make_u32_array(ByteArena &arena, std::span<const uint32_t> values)¶

MetaValue make_i32_array(ByteArena &arena, std::span<const int32_t> values)¶

MetaValue make_u64_array(ByteArena &arena, std::span<const uint64_t> values)¶

MetaValue make_i64_array(ByteArena &arena, std::span<const int64_t> values)¶

MetaValue make_f32_bits_array(ByteArena &arena, std::span<const uint32_t> bits)¶

MetaValue make_f64_bits_array(ByteArena &arena, std::span<const uint64_t> bits)¶

MetaValue make_urational_array(ByteArena &arena, std::span<const URational> values)¶

MetaValue make_srational_array(ByteArena &arena, std::span<const SRational> values)¶

Typedefs

using BlockId = uint32_t¶

using EntryId = uint32_t¶

using ReadTransferSourceSnapshotOptions = ReadTransferSourceSnapshotFileOptions ¶: Generic decode options for transfer source snapshot reads.

Enums

enum class CcmQueryStatus : uint8_t¶

Query status for collect_dng_ccm_fields.

Values:

enumerator Ok¶

enumerator LimitExceeded¶: Input was valid but query limits were exceeded.

enum class CcmValidationMode : uint8_t¶

Validation mode for CCM query normalization.

Values:

enumerator None¶: Do not emit spec-level diagnostics.

enumerator DngSpecWarnings¶: Emit DNG-oriented structure/coherency diagnostics as warnings.

enum class CcmIssueSeverity : uint8_t¶

Validation issue severity.

Values:

enumerator Warning¶

enumerator Error¶: Field-level hard-invalid issue (the field is skipped).

enum class CcmIssueCode : uint16_t¶

Validation issue code for CcmIssue.

Values:

enumerator DecodeFailed¶

enumerator NonFiniteValue¶

enumerator UnexpectedCount¶

enumerator MatrixCountNotDivisibleBy3¶

enumerator NonPositiveValue¶

enumerator AsShotConflict¶

enumerator MissingCompanionTag¶

enumerator TripleIlluminantRule¶

enumerator CalibrationSignatureMismatch¶

enumerator MissingIlluminantData¶

enumerator InvalidIlluminantCode¶

enumerator WhiteXYOutOfRange¶

enum class PayloadStatus : uint8_t¶

Payload extraction result status.

Values:

enumerator Ok¶

enumerator OutputTruncated¶: Output buffer was too small; PayloadResult::needed reports required size.

enumerator Unsupported¶: The payload encoding requires an optional dependency that is not available.

enumerator Malformed¶: The container data is malformed or inconsistent.

enumerator LimitExceeded¶: Resource limits were exceeded (e.g. too many parts or too large output).

enum class ScanStatus : uint8_t¶

Scanner result status.

Values:

enumerator Ok¶

enumerator OutputTruncated¶: Output buffer was too small; ScanResult::needed reports required size.

enumerator Unsupported¶: The bytes do not match the container format handled by the scanner.

enumerator Malformed¶: The container structure is malformed or inconsistent.

enum class ContainerFormat : uint8_t¶

Supported high-level container formats for block scanning.

Values:

enumerator Unknown¶

enumerator Jpeg¶

enumerator Png¶

enumerator Webp¶

enumerator Gif¶

enumerator Tiff¶

enumerator Crw¶

enumerator Raf¶

enumerator X3f¶

enumerator Jp2¶

enumerator Jxl¶

enumerator Heif¶

enumerator Avif¶

enumerator Cr3¶

enum class ContainerBlockKind : uint8_t¶

Logical kind of a discovered metadata block.

Values:

enumerator Unknown¶

enumerator Exif¶

enumerator Ciff¶: Canon CRW (CIFF) directory tree (non-TIFF metadata container).

enumerator MakerNote¶

enumerator Xmp¶

enumerator XmpExtended¶

enumerator Jumbf¶: JPEG Universal Metadata Box Format payload (including C2PA manifests).

enumerator Icc¶

enumerator IptcIim¶

enumerator PhotoshopIrB¶

enumerator Mpf¶

enumerator Comment¶

enumerator Text¶

enumerator CompressedMetadata¶

enum class BlockCompression : uint8_t¶

Compression type for the block payload bytes (if any).

Values:

enumerator None¶

enumerator Deflate¶

enumerator Brotli¶

enum class BlockChunking : uint8_t¶

Chunking scheme used to represent a logical stream split across blocks.

Values:

enumerator None¶

enumerator JpegApp2SeqTotal¶

enumerator JpegXmpExtendedGuidOffset¶

enumerator GifSubBlocks¶

enumerator BmffExifTiffOffsetU32Be¶

enumerator BrobU32BeRealTypePrefix¶

enumerator Jp2UuidPayload¶

enumerator PsIrB8Bim¶

enum class DngSdkAdapterStatus : uint8_t¶

Result status for the optional DNG SDK adapter.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator Unsupported¶

enumerator Malformed¶

enumerator InternalError¶

enum class ExifTagNamePolicy : uint8_t¶

Values:

enumerator Canonical¶

enumerator ExifToolCompat¶

enum class ExifDecodeStatus : uint8_t¶

EXIF/TIFF decode result status.

Values:

enumerator Ok¶

enumerator OutputTruncated¶

enumerator Unsupported¶

enumerator Malformed¶

enumerator LimitExceeded¶

enum class ExifLimitReason : uint8_t¶

Best-effort reason for ExifDecodeStatus::LimitExceeded.

Values:

enumerator None¶

enumerator MaxIfds¶

enumerator MaxEntriesPerIfd¶

enumerator MaxTotalEntries¶

enumerator ValueCountTooLarge¶

enum class ExifIfdKind : uint8_t¶

Logical IFD kinds exposed by decode_exif_tiff().

Values:

enumerator Ifd¶

enumerator ExifIfd¶

enumerator GpsIfd¶

enumerator InteropIfd¶

enumerator SubIfd¶

enum class ExrAdapterStatus : uint8_t¶

Result status for EXR adapter export.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator Unsupported¶

enum class ExrDecodeStatus : uint8_t¶

OpenEXR decode result status.

Values:

enumerator Ok¶

enumerator Unsupported¶: The bytes do not look like an OpenEXR file.

enumerator Malformed¶: The EXR header is malformed or inconsistent.

enumerator LimitExceeded¶: Resource limits were exceeded.

enum class IccDecodeStatus : uint8_t¶

ICC decode result status.

Values:

enumerator Ok¶

enumerator Unsupported¶: The bytes do not look like an ICC profile.

enumerator Malformed¶: The profile is malformed or inconsistent.

enumerator LimitExceeded¶: Resource limits were exceeded.

enum class IccTagInterpretStatus : uint8_t¶

Best-effort status for interpret_icc_tag.

Values:

enumerator Ok¶

enumerator Unsupported¶

enumerator Malformed¶

enumerator LimitExceeded¶

enum class InteropSafetyStatus : uint8_t¶

Status for strict safe interop export APIs.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator UnsafeData¶

enumerator InternalError¶

enum class InteropSafetyReason : uint8_t¶

Reason code for InteropSafetyError.

Values:

enumerator None¶

enumerator UnsafeBytes¶

enumerator InvalidTextEncoding¶

enumerator UnsafeTextControlCharacter¶

enumerator InternalMismatch¶

enum class ExportNameStyle : uint8_t¶

Key naming policy used by visit_metadata.

API Stability: Stable enum shape. Canonical, XmpPortable, and FlatHost naming contracts are stable.

Values:

enumerator Canonical¶: Stable, key-space-aware names (for example: exif:ifd0:0x010F).

enumerator XmpPortable¶: Portable XMP-like names (for example: tiff:Make, exif:ExposureTime).

enumerator FlatHost¶: Stable v1 flat host-attribute names (Make, Exif:ExposureTime).

enum class ExportNamePolicy : uint8_t¶

Name normalization policy for interop exports.

Values:

enumerator Spec¶: Preserve native OpenMeta/EXIF naming (spec-oriented).

enumerator ExifToolAlias¶: Apply ExifTool-compatible aliases and filtering for parity workflows.

enum class IptcIimDecodeStatus : uint8_t¶

IPTC-IIM decode result status.

Values:

enumerator Ok¶

enumerator Unsupported¶: The bytes do not look like an IPTC-IIM dataset stream.

enumerator Malformed¶: The stream is malformed or inconsistent.

enumerator LimitExceeded¶: Resource limits were exceeded.

enum class JumbfDecodeStatus : uint8_t¶

JUMBF decode result status.

Values:

enumerator Ok¶

enumerator Unsupported¶: Input does not look like a JUMBF payload.

enumerator Malformed¶: Input is truncated or structurally invalid.

enumerator LimitExceeded¶: Refused due to configured resource limits.

enum class C2paVerifyBackend : uint8_t¶

Draft C2PA verification backend selection.

Values:

enumerator None¶

enumerator Auto¶

enumerator Native¶

enumerator OpenSsl¶

enum class C2paVerifyStatus : uint8_t¶

Draft C2PA verification status.

Values:

enumerator NotRequested¶

enumerator DisabledByBuild¶

enumerator BackendUnavailable¶

enumerator NoSignatures¶

enumerator InvalidSignature¶

enumerator VerificationFailed¶

enumerator Verified¶

enumerator NotImplemented¶

enum class LibRawOrientationStatus : uint8_t¶

Result status for EXIF/XMP orientation to LibRaw flip mapping.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator Unsupported¶

enum class LibRawOrientationCode : uint8_t¶

Detailed mapping code for LibRawOrientationResult.

Values:

enumerator None¶

enumerator PreviewPassThrough¶

enumerator MissingExifOrientationAssumedDefault¶

enumerator InvalidExifOrientation¶

enumerator UnsupportedMirroredOrientation¶

enumerator MirroredOrientationDropped¶

enum class LibRawOrientationSource : uint8_t¶

Canonical metadata source used for LibRawOrientationResult.

Values:

enumerator ExplicitInput¶

enumerator AssumedDefault¶

enumerator ExifIfd0¶

enumerator XmpTiffOrientation¶

enum class LibRawOrientationTarget : uint8_t¶

Output target for LibRaw orientation mapping.

Values:

enumerator RawImage¶

enumerator EmbeddedPreview¶

enum class LibRawMirrorPolicy : uint8_t¶

Policy for mirrored EXIF orientations (2/4/5/7).

Values:

enumerator Reject¶

enumerator DropMirror¶

enum class LibRawFlipToExifCode : uint8_t¶

Detailed mapping code for LibRawFlipToExifResult.

Values:

enumerator None¶

enumerator PreviewPassThrough¶

enumerator InvalidLibRawFlip¶

enum class LibRawOrientationFileStatus : uint8_t¶

Status for map_meta_orientation_to_libraw_flip_from_file.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator OpenFailed¶

enumerator StatFailed¶

enumerator TooLarge¶

enumerator MapFailed¶

enumerator DecodeFailed¶

enum class MappedFileStatus : uint8_t¶

Status code for MappedFile operations.

Values:

enumerator Ok¶

enumerator OpenFailed¶

enumerator StatFailed¶

enumerator TooLarge¶

enumerator MapFailed¶

enum class EditOpKind : uint8_t¶

The operation kind for a MetaEdit command stream.

Values:

enumerator AddEntry¶

enumerator SetValue¶

enumerator Tombstone¶

enum class EntryFlags : uint8_t¶

Per-entry flags used during edits and provenance tracking.

Values:

enumerator None¶

enumerator Deleted¶: Entry is logically removed (kept for stable ids / provenance).

enumerator Dirty¶: Entry was modified or added relative to an origin snapshot.

enumerator Derived¶: Entry was derived from other data (e.g. EXIF->XMP mapping).

enumerator Truncated¶: Value payload was truncated or omitted due to configured limits.

enumerator Unreadable¶: Value payload could not be read from the underlying container.

enumerator ContextualName¶: Entry name has a decode-time contextual display variant.

enum class MetaKeyKind : uint8_t¶

Namespace for different metadata key spaces.

Values:

enumerator ExifTag¶

enumerator Comment¶

enumerator ExrAttribute¶

enumerator IptcDataset¶

enumerator XmpProperty¶

enumerator IccHeaderField¶

enumerator IccTag¶

enumerator PhotoshopIrb¶

enumerator PhotoshopIrbField¶

enumerator GeotiffKey¶

enumerator PrintImField¶

enumerator BmffField¶

enumerator JumbfField¶

enumerator JumbfCborKey¶

enumerator PngText¶

enum class WireFamily : uint8_t¶

The wire-format family a value came from (used for round-trip encoding).

Values:

enumerator None¶

enumerator Tiff¶

enumerator Other¶

enum class EntryNameContextKind : uint8_t¶

Decode-time contextual-name selector for compatibility/display surfaces.

Values:

enumerator None¶

enumerator CasioType2Legacy¶

enumerator FujifilmMain1304¶

enumerator OlympusFocusInfo1600¶

enumerator KodakMain0028¶

enumerator MinoltaMainCompat¶

enumerator MotorolaMain6420¶

enumerator SonyMainCompat¶

enumerator SonyTag94060005¶

enumerator SigmaMainCompat¶

enumerator RicohMainCompat¶

enumerator NikonSettingsMain¶

enumerator NikonMainZ¶

enumerator NikonMainCompactType2¶

enumerator NikonFlashInfoGroups¶

enumerator NikonFlashInfoLegacy¶

enumerator NikonShotInfoD800¶

enumerator NikonShotInfoD850¶

enumerator NikonShotInfoZ8¶

enumerator PentaxMain0062¶

enumerator CanonMain0038¶

enumerator CanonShotInfo000E¶

enumerator CanonCameraSettings0021¶

enumerator CanonColorData4PSInfo¶

enumerator CanonColorData7PSInfo2¶

enumerator CanonColorData400EA¶

enumerator CanonColorData400EE¶

enumerator CanonColorData402CF¶

enumerator CanonColorCalib0038¶

enumerator CanonCameraInfo1D0048¶

enumerator CanonCameraInfo600D00EA¶

enumerator CanonCustomFunctions20103¶

enumerator CanonCustomFunctions2010C¶

enumerator CanonCustomFunctions20510¶

enumerator CanonCustomFunctions20701¶

enumerator CanonMain0000¶

enum class MetaValueKind : uint8_t¶

Top-level value storage kind.

Values:

enumerator Empty¶

enumerator Scalar¶: An inline scalar stored in MetaValue::data.

enumerator Array¶: An array stored as raw bytes in a ByteArena span.

enumerator Bytes¶: Raw uninterpreted bytes in a ByteArena span.

enumerator Text¶: Text bytes in a ByteArena span with an associated encoding.

enum class MetaElementType : uint8_t¶

Element type used for scalar and array values.

Values:

enumerator U8¶

enumerator I8¶

enumerator U16¶

enumerator I16¶

enumerator U32¶

enumerator I32¶

enumerator U64¶

enumerator I64¶

enumerator F32¶

enumerator F64¶

enumerator URational¶

enumerator SRational¶

enum class TextEncoding : uint8_t¶

Encoding hint for text values.

Values:

enumerator Unknown¶

enumerator Ascii¶

enumerator Utf8¶

enumerator Utf16LE¶

enumerator Utf16BE¶

enum class MetadataCapabilityFamily : uint8_t¶

Metadata family used by metadata_capability.

Values:

enumerator Exif¶

enumerator Xmp¶

enumerator Icc¶

enumerator Iptc¶

enumerator MakerNote¶

enumerator PhotoshopIrb¶

enumerator Jumbf¶

enumerator C2pa¶

enumerator BmffFields¶

enumerator GeoTiff¶

enumerator ExrAttribute¶

enum class MetadataCapabilitySupport : uint8_t¶

Support level for one operation in MetadataCapability.

Values:

enumerator Unsupported¶

enumerator Supported¶

enumerator Bounded¶

enumerator Disabled¶

enum class MetadataConceptKind : uint8_t¶

Values:

enumerator Orientation¶

enumerator DateTime¶

enumerator ColorProfile¶

enumerator Gps¶

enumerator Geometry¶

enumerator LensCorrection¶

enumerator RawProcessing¶

enumerator Exposure¶

enum class MetadataConceptSourceFamily : uint8_t¶

Values:

enumerator Unknown¶

enumerator Exif¶

enumerator Xmp¶

enumerator Iptc¶

enumerator Icc¶

enumerator PngText¶

enumerator InterpretationRecord¶

enum class MetadataConceptRole : uint8_t¶

Values:

enumerator Primary¶

enumerator Orientation¶

enumerator Created¶

enumerator Digitized¶

enumerator Modified¶

enumerator MetadataDate¶

enumerator DateCreated¶

enumerator ColorSpace¶

enumerator IccProfile¶

enumerator ColorMatrix¶

enumerator WhiteBalance¶

enumerator Latitude¶

enumerator Longitude¶

enumerator Altitude¶

enumerator Timestamp¶

enumerator Crop¶

enumerator ActiveArea¶

enumerator Border¶

enumerator SensorGeometry¶

enumerator LensCorrection¶

enumerator BlackLevel¶

enumerator WhiteLevel¶

enumerator Linearization¶

enumerator CfaLayout¶

enumerator RawStorage¶

enumerator SourceProcessing¶

enumerator ComputationalProcessing¶

enumerator ThermalProcessing¶

enumerator StitchProcessing¶

enumerator ExposureTime¶

enumerator Aperture¶

enumerator IsoSensitivity¶

enumerator ExposureBias¶

enumerator ExposureProgram¶

enumerator Gain¶

enumerator RawExposureAdjustment¶

enumerator SourceColorTransform¶

enum class MetadataConceptDateTimePrecision : uint8_t¶

Values:

enumerator Unknown¶

enumerator Date¶

enumerator DateTime¶

enum class MetadataConceptTimeZoneKind : uint8_t¶

Values:

enumerator Unknown¶

enumerator Local¶

enumerator Utc¶

enumerator Offset¶

enum class MetadataConceptTransferHint : uint8_t¶

Values:

enumerator Unknown¶

enumerator Safe¶

enumerator SourceBound¶

enumerator RenderedUnsafe¶

enumerator RequiresTargetImageSpec¶

enum class MetadataQueryKind : uint8_t¶

Values:

enumerator Crop¶

enumerator ExposureGain¶

enumerator WhiteBalance¶

enumerator Color¶

enumerator LensCorrection¶

enumerator Orientation¶

enumerator RawProcessing¶

enumerator Descriptive¶

enum class MetadataQuerySemanticKind : uint8_t¶

Values:

enumerator Unknown¶

enumerator Crop¶

enumerator Border¶

enumerator ActiveArea¶

enumerator Exposure¶

enumerator Gain¶

enumerator Color¶

enumerator ColorProfile¶

enumerator WhiteBalance¶

enumerator ColorMatrix¶

enumerator LensCorrection¶

enumerator Orientation¶

enumerator ExposureGain¶

enumerator BlackLevel¶

enumerator WhiteLevel¶

enumerator Linearization¶

enumerator CfaLayout¶

enumerator SensorGeometry¶

enumerator RawStorage¶

enumerator SourceProcessing¶

enumerator ComputationalProcessing¶

enumerator ThermalProcessing¶

enumerator StitchProcessing¶

enumerator Title¶

enumerator Description¶

enumerator Creator¶

enumerator Keywords¶

enumerator SourceColorTransform¶

enum class MetadataQueryValueShape : uint8_t¶

Values:

enumerator Unknown¶

enumerator Scalar¶

enumerator Vec2¶

enumerator Vec3¶

enumerator Vec4¶

enumerator Rect¶

enumerator Matrix3x3¶

enumerator VectorSet¶

enumerator MatrixSet¶

enumerator Table¶

enumerator Array¶

enumerator Blob¶

enumerator Text¶

enum class MetadataQueryMatchTerm : uint32_t¶

Values:

enumerator None¶

enumerator Crop¶

enumerator Border¶

enumerator Margin¶

enumerator Padding¶

enumerator ActiveArea¶

enumerator Origin¶

enumerator Offset¶

enumerator Size¶

enumerator Sensor¶

enumerator Image¶

enumerator Exposure¶

enumerator Bias¶

enumerator Gain¶

enumerator WhiteBalance¶

enumerator Color¶

enumerator Matrix¶

enumerator Calibration¶

enumerator Profile¶

enumerator Lens¶

enumerator Correction¶

enumerator Orientation¶

enumerator BlackLevel¶

enumerator WhiteLevel¶

enumerator Linearization¶

enumerator Cfa¶

enumerator Raw¶

enumerator Storage¶

enumerator SourceProcessing¶

enumerator Title¶

enumerator Description¶

enumerator Creator¶

enumerator Keywords¶

enum class TransferTargetFormat : uint8_t¶

Target container family for prepared transfer bundles.

Values:

enumerator Jpeg¶

enumerator Tiff¶

enumerator Jxl¶

enumerator Webp¶

enumerator Heif¶

enumerator Avif¶

enumerator Cr3¶

enumerator Exr¶

enumerator Png¶

enumerator Jp2¶

enumerator Dng¶

enum class DngTargetMode : uint8_t¶

Public DNG target contract for metadata-only transfer workflows.

Values:

enumerator ExistingTarget¶

enumerator TemplateTarget¶

enumerator MinimalFreshScaffold¶

enum class TransferBlockKind : uint8_t¶

Prepared payload block category.

Values:

enumerator Exif¶

enumerator Xmp¶

enumerator IptcIim¶

enumerator PhotoshopIrb¶

enumerator Icc¶

enumerator Jumbf¶

enumerator C2pa¶

enumerator ExrAttribute¶

enumerator Other¶

enum class TransferStatus : uint8_t¶

Status for transfer preparation and emit APIs.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator Unsupported¶

enumerator LimitExceeded¶

enumerator Malformed¶

enumerator UnsafeData¶

enumerator InternalError¶

enum class PrepareTransferCode : uint16_t¶

Stable preparation error code for PrepareTransferResult.

Values:

enumerator None¶

enumerator NullOutBundle¶

enumerator UnsupportedTargetFormat¶

enumerator ExifPackFailed¶

enumerator XmpPackFailed¶

enumerator IccPackFailed¶

enumerator IptcPackFailed¶

enumerator RequestedMetadataNotSerializable¶

enum class EmitTransferCode : uint16_t¶

Stable emit error code for EmitTransferResult.

Values:

enumerator None¶

enumerator InvalidArgument¶

enumerator BundleTargetNotJpeg¶

enumerator UnsupportedRoute¶

enumerator InvalidPayload¶

enumerator ContentBoundPayloadUnsupported¶

enumerator BackendWriteFailed¶

enumerator PlanMismatch¶

enum class PrepareTransferFileCode : uint16_t¶

Stable file/read/prepare error code for PrepareTransferFileResult.

Values:

enumerator None¶

enumerator EmptyPath¶

enumerator MapFailed¶

enumerator PayloadBufferPlatformLimit¶

enumerator DecodeFailed¶

enum class ReadTransferSourceSnapshotFileCode : uint16_t¶

Stable file/read error code for ReadTransferSourceSnapshotFileResult.

Values:

enumerator None¶

enumerator EmptyPath¶

enumerator MapFailed¶

enumerator PayloadBufferPlatformLimit¶

enumerator DecodeFailed¶

enum class ReadTransferSourceSnapshotBytesCode : uint16_t¶

Stable bytes/read error code for ReadTransferSourceSnapshotBytesResult.

Values:

enumerator None¶

enumerator PayloadBufferPlatformLimit¶

enumerator DecodeFailed¶

enum class TransferFileStatus : uint8_t¶

Status for high-level file-to-bundle transfer preparation.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enumerator OpenFailed¶

enumerator StatFailed¶

enumerator TooLarge¶

enumerator MapFailed¶

enumerator ReadFailed¶

enum class TransferPolicySubject : uint8_t¶

Transfer-policy subject handled during bundle preparation.

Values:

enumerator MakerNote¶

enumerator Jumbf¶

enumerator C2pa¶

enumerator XmpExifProjection¶

enumerator XmpIptcProjection¶

enumerator ImageProperties¶

enumerator IccProfile¶

enumerator RawColorCalibration¶

enumerator CameraRawSettings¶

enum class TransferPolicyAction : uint8_t¶

Requested/effective action for a metadata family during transfer.

Values:

enumerator Keep¶

enumerator Drop¶

enumerator Invalidate¶

enumerator Rewrite¶

enum class TransferPolicyReason : uint8_t¶

Reason attached to one prepared transfer policy decision.

Values:

enumerator Default¶

enumerator NotPresent¶

enumerator ExplicitDrop¶

enumerator CarrierDisabled¶

enumerator ProjectedPayload¶

enumerator DraftInvalidationPayload¶

enumerator ExternalSignedPayload¶

enumerator ContentBoundTransferUnavailable¶

enumerator SignedRewriteUnavailable¶

enumerator PortableInvalidationUnavailable¶

enumerator RewriteUnavailablePreservedRaw¶

enumerator TargetSerializationUnavailable¶

enumerator TargetImageProperties¶

enumerator SafetyModeFiltered¶

enum class TransferC2paMode : uint8_t¶

Explicit current C2PA transfer mode resolved during prepare.

Values:

enumerator NotApplicable¶

enumerator NotPresent¶

enumerator Drop¶

enumerator DraftUnsignedInvalidation¶

enumerator PreserveRaw¶

enumerator SignedRewrite¶

enum class TransferC2paSourceKind : uint8_t¶

Classified C2PA source state observed during prepare.

Values:

enumerator NotApplicable¶

enumerator NotPresent¶

enumerator DecodedOnly¶

enumerator ContentBound¶

enumerator DraftUnsignedInvalidation¶

enum class TransferC2paPreparedOutput : uint8_t¶

Prepared C2PA output contract selected during prepare.

Values:

enumerator NotApplicable¶

enumerator NotPresent¶

enumerator Dropped¶

enumerator PreservedRaw¶

enumerator GeneratedDraftUnsignedInvalidation¶

enumerator SignedRewrite¶

enum class TransferC2paRewriteState : uint8_t¶

Current rewrite-signing readiness for C2PA transfer.

Values:

enumerator NotApplicable¶

enumerator NotRequested¶

enumerator SigningMaterialRequired¶

enumerator Ready¶

enum class TransferC2paRewriteChunkKind : uint8_t¶

One deterministic chunk in the future C2PA rewrite binding sequence.

Values:

enumerator SourceRange¶

enumerator PreparedJpegSegment¶

enumerator PreparedJxlBox¶

enumerator PreparedBmffMetaBox¶

enum class TransferSafetyMode : uint8_t¶

Coarse transfer safety mode for source metadata reuse.

Values:

enumerator CompatibleFile¶: Compatible metadata repackage/recompression; preserves source color and camera-specific metadata except target-owned image-layout fields.

enumerator RenderedImage¶: Rendered/exported pixels; drops source color-calibration, raw pipeline, lens-correction, raw settings, source ICC, MakerNote, and non-C2PA JUMBF data unless host code supplies target-correct replacements.

enum class TransferC2paSignedPayloadKind : uint8_t¶

Classified logical C2PA payload kind supplied by an external signer.

Values:

enumerator NotApplicable¶

enumerator GenericJumbf¶

enumerator DraftUnsignedInvalidation¶

enumerator ContentBound¶

enum class TransferC2paSemanticStatus : uint8_t¶

Semantic validation status for a staged logical C2PA payload.

Values:

enumerator NotChecked¶

enumerator Ok¶

enumerator Invalid¶

enum class TransferConceptDiagnosticAction : uint8_t¶

Values:

enumerator Keep¶

enumerator Drop¶

enumerator RequiresTargetImageSpec¶

enum class TransferConceptDiagnosticReason : uint8_t¶

Values:

enumerator Unknown¶

enumerator Safe¶

enumerator SourceBound¶

enumerator RenderedUnsafe¶

enumerator TargetImageSpecRequired¶

enum class TransferConceptDiagnosticSeverity : uint8_t¶

Values:

enumerator Info¶

enumerator Warning¶

enum class TimePatchField : uint8_t¶

Optional fixed-width patch field identifiers for per-frame updates.

Values:

enumerator DateTime¶

enumerator DateTimeOriginal¶

enumerator DateTimeDigitized¶

enumerator SubSecTime¶

enumerator SubSecTimeOriginal¶

enumerator SubSecTimeDigitized¶

enumerator OffsetTime¶

enumerator OffsetTimeOriginal¶

enumerator OffsetTimeDigitized¶

enumerator GpsDateStamp¶

enumerator GpsTimeStamp¶

enum class TransferRawCarrierPassthroughReason : uint8_t¶

Primary passthrough eligibility result for one preserved raw carrier.

Values:

enumerator Candidate¶

enumerator MissingPayload¶

enumerator TargetIncompatible¶

enumerator SafetyFiltered¶

enumerator ContentBoundMetadata¶

enumerator PolicyBlocked¶

enumerator DecodeLinkUnavailable¶

enumerator UnsupportedKind¶

enum class TransferRawCarrierPassthroughMode : uint8_t¶

Opt-in raw-carrier use during snapshot transfer preparation.

Values:

enumerator Disabled¶: Do not reuse preserved raw carriers while preparing from a snapshot.

enumerator WhenSafe¶: Reuse only bounded carrier families that pass the active policy checks.

enum class JpegEditMode : uint8_t¶

Draft JPEG edit strategy selection.

Values:

enumerator Auto¶

enumerator InPlace¶

enumerator MetadataRewrite¶

enum class TransferPackageChunkKind : uint8_t¶

One chunk in a packaged transfer output plan.

Values:

enumerator SourceRange¶

enumerator PreparedTransferBlock¶

enumerator PreparedJpegSegment¶

enumerator InlineBytes¶

enum class TransferSemanticKind : uint8_t¶

Semantic metadata family carried by one transfer payload or package chunk.

Values:

enumerator Unknown¶

enumerator Exif¶

enumerator Xmp¶

enumerator Icc¶

enumerator Iptc¶

enumerator Jumbf¶

enumerator C2pa¶

enum class PreparedJxlEmitKind : uint8_t¶

Kind of precompiled JPEG XL emit operation.

Values:

enumerator Box¶

enumerator IccProfile¶

enum class PreparedTransferArtifactKind : uint8_t¶

Persisted transfer artifact family recognized by the generic inspect path.

Values:

enumerator Unknown¶

enumerator TransferPayloadBatch¶

enumerator TransferPackageBatch¶

enumerator C2paHandoffPackage¶

enumerator C2paSignedPackage¶

enumerator JxlEncoderHandoff¶

enum class PreparedBmffEmitKind : uint8_t¶

Kind of precompiled ISO-BMFF metadata emit operation.

Values:

enumerator Item¶

enumerator MimeXmp¶

enumerator Property¶

enum class TransferAdapterOpKind : uint8_t¶

One normalized adapter operation for external encoder or host integration.

Values:

enumerator JpegMarker¶

enumerator TiffTagBytes¶

enumerator JxlBox¶

enumerator JxlIccProfile¶

enumerator WebpChunk¶

enumerator PngChunk¶

enumerator Jp2Box¶

enumerator ExrAttribute¶

enumerator BmffItem¶

enumerator BmffProperty¶

enum class XmpExistingSidecarMode : uint8_t¶

Existing sibling XMP sidecar handling for transfer preparation.

Values:

enumerator Ignore¶

enumerator MergeIfPresent¶

enum class XmpExistingSidecarPrecedence : uint8_t¶

Conflict precedence between a merged destination-side .xmp and source-embedded existing XMP.

Values:

enumerator SidecarWins¶

enumerator SourceWins¶

enum class XmpExistingDestinationEmbeddedMode : uint8_t¶

Existing destination embedded-XMP handling for file-helper transfer execution.

Values:

enumerator Ignore¶

enumerator MergeIfPresent¶

enum class XmpExistingDestinationEmbeddedPrecedence : uint8_t¶

Conflict precedence between merged destination embedded XMP and source-embedded existing XMP.

Values:

enumerator DestinationWins¶

enumerator SourceWins¶

enum class XmpExistingDestinationCarrierPrecedence : uint8_t¶

Conflict precedence between existing destination sidecar XMP and existing destination embedded XMP when both are merged during transfer preparation.

Values:

enumerator SidecarWins¶

enumerator EmbeddedWins¶

enum class XmpWritebackMode : uint8_t¶

XMP carrier preference for file-helper transfer execution.

Values:

enumerator EmbeddedOnly¶: Keep generated XMP only in the managed embedded carrier.

enumerator SidecarOnly¶

Return generated XMP only as sibling .xmp output.

Existing embedded XMP stays in the edited file unless
\ref XmpDestinationEmbeddedMode::StripExisting is requested.

enumerator EmbeddedAndSidecar¶: Keep generated XMP in the managed embedded carrier and also return the same generated XMP packet for sibling .xmp writeback.

enum class XmpDestinationEmbeddedMode : uint8_t¶

Destination embedded-XMP handling for file-helper transfer execution.

Values:

enumerator PreserveExisting¶: Leave existing embedded XMP in the edited file when sidecar-only writeback suppresses generated embedded XMP.

enumerator StripExisting¶: Remove managed embedded XMP from the edited file when sidecar-only writeback is selected.

enum class XmpDestinationSidecarMode : uint8_t¶

Destination sibling XMP sidecar handling for file-helper transfer execution.

Values:

enumerator PreserveExisting¶: Leave an existing sibling .xmp untouched when embedded-only writeback is selected.

enumerator StripExisting¶: Request removal of an existing sibling .xmp when embedded-only writeback is selected.

enum class XmpExistingDestinationSidecarState : uint8_t¶

Host-reported presence of an existing destination sibling .xmp sidecar.

Values:

enumerator Unknown¶: Use path-based detection when a sidecar base path is available.

enumerator NotPresent¶: Host knows there is no existing destination sidecar.

enumerator Present¶: Host knows there is an existing destination sidecar to remove.

enum class ExifOrientationStatus : uint8_t¶

Result status for EXIF/TIFF orientation interpretation.

Values:

enumerator Ok¶

enumerator InvalidArgument¶

enum class PhaseOneRawGeometryStatus : uint8_t¶

Values:

enumerator Ok¶

enumerator MissingField¶

enumerator InvalidValue¶

enumerator OutOfBounds¶

enum class PhaseOneRawProcessingStatus : uint8_t¶

Values:

enumerator Ok¶

enumerator MissingField¶

enumerator InvalidValue¶

enumerator Partial¶

enum class PhotoshopIrbDecodeStatus : uint8_t¶

Photoshop IRB decode result status.

Values:

enumerator Ok¶

enumerator Unsupported¶: The bytes do not look like an IRB stream.

enumerator Malformed¶: The stream is malformed or inconsistent.

enumerator LimitExceeded¶: Resource limits were exceeded.

enum class PhotoshopIrbStringCharset : uint8_t¶

Charset policy for legacy 8-bit Photoshop IRB text payloads.

Values:

enumerator Latin¶

enumerator Ascii¶

enum class PreviewKind : uint8_t¶

Candidate preview source kind.

Values:

enumerator ExifJpegInterchange¶: EXIF/TIFF pair JPEGInterchangeFormat (0x0201) + length (0x0202).

enumerator ExifJpgFromRaw¶: EXIF/TIFF blob tag JpgFromRaw (0x002E).

enumerator ExifJpgFromRaw2¶: EXIF/TIFF blob tag JpgFromRaw2 (0x0127).

enumerator Cr3PrvwJpeg¶: Canon CR3 preview JPEG stored in a PRVW stream inside a UUID box.

enum class PreviewScanStatus : uint8_t¶

Status for preview candidate discovery.

Values:

enumerator Ok¶

enumerator OutputTruncated¶

enumerator Unsupported¶

enumerator Malformed¶

enumerator LimitExceeded¶

enum class PreviewExtractStatus : uint8_t¶

Status for preview extraction.

Values:

enumerator Ok¶

enumerator OutputTruncated¶

enumerator Malformed¶

enumerator LimitExceeded¶

enum class PrintImDecodeStatus : uint8_t¶

PrintIM decode result status.

Values:

enumerator Ok¶

enumerator Unsupported¶: Input does not look like a PrintIM block.

enumerator Malformed¶: Input is truncated or structurally invalid.

enumerator LimitExceeded¶: Refused due to size/entry-count limits.

enum class ValidateStatus : uint8_t¶

Top-level validation status for validate_file.

Values:

enumerator Ok¶

enumerator OpenFailed¶

enumerator TooLarge¶

enumerator ReadFailed¶

enum class ValidateIssueSeverity : uint8_t¶

Validation issue severity.

Values:

enumerator Warning¶

enumerator Error¶

enum class VendorRawProcessingFamily : uint8_t¶

Values:

enumerator Sony¶

enumerator Canon¶

enumerator Nikon¶

enumerator Fujifilm¶

enumerator Pentax¶

enumerator Panasonic¶

enumerator Olympus¶

enumerator Kodak¶

enumerator Minolta¶

enumerator Sigma¶

enumerator Samsung¶

enumerator Ricoh¶

enumerator Apple¶

enumerator Dji¶

enumerator Google¶

enumerator Flir¶

enumerator Casio¶

enumerator Sanyo¶

enumerator KyoceraRaw¶

enumerator Reconyx¶

enumerator Hp¶

enumerator Jvc¶

enumerator Ge¶

enumerator Motorola¶

enumerator Nintendo¶

enumerator Microsoft¶

enum class VendorRawProcessingGroup : uint32_t¶

Values:

enumerator None¶

enumerator Color¶

enumerator WhiteBalance¶

enumerator Geometry¶

enumerator Storage¶

enumerator LensCorrection¶

enumerator RawData¶

enumerator Sensor¶

enumerator PrivateTable¶

enumerator Preview¶

enumerator FaceGeometry¶

enumerator Computational¶

enumerator Thermal¶

enumerator Stitch¶

enum class XmpDecodeStatus : uint8_t¶

XMP decode result status.

Values:

enumerator Ok¶

enumerator OutputTruncated¶

enumerator Unsupported¶

enumerator Malformed¶

enumerator LimitExceeded¶

enum class XmpDecodeMalformedMode : uint8_t¶

Controls how malformed XMP packets are reported to callers.

Some workflows prefer treating malformed XML as “best-effort partial output” rather than a hard failure.

Values:

enumerator Malformed¶: Report malformed XML as XmpDecodeStatus::Malformed.

enumerator OutputTruncated¶: Report malformed XML as XmpDecodeStatus::OutputTruncated.

enum class XmpConflictPolicy : uint8_t¶

Conflict policy for existing XMP versus generated portable XMP properties.

This currently applies to portable XMP generation only.

Values:

enumerator CurrentBehavior¶: Preserve the historical OpenMeta order: EXIF-derived properties first, then existing XMP, then IPTC-derived properties.

enumerator ExistingWins¶: Existing decoded XMP properties win over generated EXIF/IPTC mappings.

enumerator GeneratedWins¶: Generated EXIF/IPTC mappings win over existing decoded XMP properties.

enum class XmpExistingNamespacePolicy : uint8_t¶

Existing XMP namespace policy for portable XMP generation.

Values:

enumerator KnownPortableOnly¶: Keep only the standard portable namespaces known to OpenMeta.

enumerator PreserveCustom¶: Also preserve safe simple/indexed properties from custom namespaces.

enum class XmpExistingStandardNamespacePolicy : uint8_t¶

Existing standard portable-namespace reconciliation policy.

Values:

enumerator PreserveAll¶: Preserve existing standard portable namespaces subject to conflict order.

enumerator CanonicalizeManaged¶: Drop OpenMeta-managed standard portable properties and regenerate them canonically from EXIF/IPTC mappings when available.

enum class XmpDumpStatus : uint8_t¶

XMP dump result status.

Values:

enumerator Ok¶

enumerator OutputTruncated¶: Output buffer was too small; XmpDumpResult::needed reports required size.

enumerator LimitExceeded¶: Caller-specified limits prevented generating a complete dump.

enum class XmpSidecarFormat : uint8_t¶

Sidecar format selection for dump_xmp_sidecar.

Values:

enumerator Lossless¶

enumerator Portable¶

Functions

const BuildInfo &build_info() noexcept¶: Returns build information for the linked OpenMeta library.

void format_build_info_lines(const BuildInfo &info, std::string *line1, std::string *line2) noexcept¶

Formats a stable, human-readable build info header (2 lines).

Output format:

OpenMeta vX.Y.Z <build_type> [features] <linkage>
built with <compiler> for <system>/<arch> (<timestamp>)

void format_build_info_lines(std::string *line1, std::string *line2) noexcept¶: Convenience overload for the linked OpenMeta library build.

CcmQueryResult collect_dng_ccm_fields(const MetaStore &store, std::vector<CcmField> *out, const CcmQueryOptions &options = CcmQueryOptions{}, std::vector<CcmIssue> *issues = nullptr) noexcept¶

Extracts normalized DNG/RAW CCM-related fields from a MetaStore.

The query scans EXIF tags and emits stable field names for:

ColorMatrix*, ForwardMatrix*, CameraCalibration*
ReductionMatrix* (optional)
AsShotNeutral, AsShotWhiteXY, AnalogBalance
CalibrationIlluminant*

bool dump_metadata_compatibility(const MetaStore &store, const MetadataCompatibilityDumpOptions &options, std::string *out) noexcept¶

Emit a deterministic line-oriented metadata compatibility dump.

The dump includes exported names, value kinds, scalar element types, optional value text, optional origin fields, and optional flags.

bool dump_transfer_compatibility(const ExecutePreparedTransferFileResult &result, const PersistPreparedTransferFileResult *persisted, const TransferCompatibilityDumpOptions &options, std::string *out) noexcept¶

Emit deterministic transfer and writeback decision summaries.

Pass persisted when file persistence results should be included.

bool append_console_escaped_ascii(std::string_view s, uint32_t max_bytes, std::string *out) noexcept¶

void append_hex_bytes(std::span<const std::byte> bytes, uint32_t max_bytes, std::string *out) noexcept¶

PayloadResult extract_payload(std::span<const std::byte> file_bytes, std::span<const ContainerBlockRef> blocks, uint32_t seed_index, std::span<std::byte> out_payload, std::span<uint32_t> scratch_indices, const PayloadOptions &options) noexcept¶

Extracts the logical payload for a discovered block.

The function uses seed_index to identify the logical stream to extract and, when applicable, gathers additional parts from blocks to reassemble it.

Supported reassembly:

BlockChunking::GifSubBlocks
BlockChunking::JpegApp2SeqTotal (ICC)
BlockChunking::JpegXmpExtendedGuidOffset
Multi-part logical streams with ContainerBlockRef::part_count > 1

Supported decompression (optional):

BlockCompression::Deflate (zlib)
BlockCompression::Brotli

Callers provide buffers to keep data flow explicit and allocation-free.

static constexpr uint32_t fourcc(char a, char b, char c, char d) noexcept¶: Packs four ASCII characters into a big-endian FourCC integer.

ScanResult scan_auto(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶

ScanResult measure_scan_auto(std::span<const std::byte> bytes) noexcept¶

Measures discovered metadata block count for scan_auto.

Performs the same bounded scan logic and reports ScanResult::needed without requiring output block storage.

ScanResult scan_jpeg(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a JPEG byte stream and returns all metadata segments found.

ScanResult measure_scan_jpeg(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_png(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a PNG byte stream and returns all metadata chunks found.

ScanResult measure_scan_png(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_webp(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a RIFF/WebP byte stream and returns all metadata chunks found.

ScanResult measure_scan_webp(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_gif(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a GIF byte stream and returns all metadata extension blocks found.

ScanResult measure_scan_gif(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_tiff(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a TIFF/DNG byte stream; the whole file is exposed as an EXIF/TIFF-IFD block.

ScanResult measure_scan_tiff(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_jp2(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a JPEG 2000 (JP2) byte stream and returns metadata boxes found.

ScanResult measure_scan_jp2(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_jxl(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans a JPEG XL container byte stream and returns metadata boxes found.

ScanResult measure_scan_jxl(std::span<const std::byte> bytes) noexcept¶

ScanResult scan_bmff(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept¶: Scans an ISO-BMFF (ftyp) container (e.g. HEIF/AVIF/CR3) and returns metadata items found within meta boxes.

ScanResult measure_scan_bmff(std::span<const std::byte> bytes) noexcept¶

bool dng_sdk_adapter_available() noexcept¶: Returns true when OpenMeta was built with the optional DNG SDK adapter enabled.

DngSdkAdapterResult apply_prepared_dng_sdk_metadata(const PreparedTransferBundle &bundle, ::dng_host *host, ::dng_negative *negative, const DngSdkAdapterOptions &options = DngSdkAdapterOptions{}) noexcept¶

Applies prepared DNG-target metadata onto a DNG SDK negative.

Current v1 coverage is bounded to EXIF, XMP, and IPTC payloads emitted by OpenMeta’s prepared DNG transfer bundle. This API does not encode pixels or synthesize raw-image structure.

DngSdkAdapterResult update_prepared_dng_sdk_stream_metadata(const PreparedTransferBundle &bundle, ::dng_host *host, ::dng_negative *negative, ::dng_stream *stream, const DngSdkAdapterOptions &options = DngSdkAdapterOptions{}) noexcept¶: Applies prepared metadata onto a DNG SDK negative, then runs the SDK’s in-place metadata update path on an existing DNG stream.

ApplyDngSdkMetadataFileResult apply_dng_sdk_metadata_from_file(const char *path, ::dng_host *host, ::dng_negative *negative, const ApplyDngSdkMetadataFileOptions &options = ApplyDngSdkMetadataFileOptions{}) noexcept¶: Reads one source file, prepares a DNG-target bundle, then applies it onto a DNG SDK negative.

ApplyDngSdkMetadataFileResult update_dng_sdk_stream_metadata_from_file(const char *path, ::dng_host *host, ::dng_negative *negative, ::dng_stream *stream, const ApplyDngSdkMetadataFileOptions &options = ApplyDngSdkMetadataFileOptions{}) noexcept¶: Reads one source file, prepares a DNG-target bundle, applies it onto a DNG SDK negative, then updates an existing DNG stream in place.

ApplyDngSdkMetadataFileResult update_dng_sdk_file_from_file(const char *source_path, const char *target_path, const ApplyDngSdkMetadataFileOptions &options = ApplyDngSdkMetadataFileOptions{}) noexcept¶

Reads one source file, prepares a DNG-target bundle, parses one existing target DNG file through the Adobe DNG SDK, then updates that target file’s metadata in place.

This is the thin public file-helper used by bindings and host tools that want an end-to-end “source file -> existing DNG file” metadata update path without directly managing SDK object lifetimes.

std::string_view exif_tag_name(std::string_view ifd, uint16_t tag) noexcept¶

Returns a human-readable EXIF/TIFF tag name for a given IFD token and tag id.

The IFD token matches the decoder output (e.g. "ifd0", "exififd", "gpsifd").

Returns:: An empty view for unknown tags.

std::string_view exif_entry_name(const MetaStore &store, const Entry &entry, ExifTagNamePolicy policy) noexcept¶

Returns a human-readable name for an EXIF-tag entry.

Canonical names come from the static tag registry. Compatibility policy may use decode-time contextual variants for ambiguous MakerNote tags.

ExifDecodeResult decode_exif_tiff(std::span<const std::byte> tiff_bytes, MetaStore &store, std::span<ExifIfdRef> out_ifds, const ExifDecodeOptions &options) noexcept¶

Decodes a TIFF header + IFD chain and appends tags into store.

The decoded entries use:

MetaKeyKind::ExifTag
an IFD token string such as "ifd0", "exififd", "gpsifd", "subifd0"
the numeric TIFF tag id.

Provenance is recorded in Origin (block + order + wire type/count).

Parameters:

tiff_bytes – TIFF header + IFD stream (from an EXIF blob or a TIFF/DNG file).
store – Destination MetaStore (entries are appended).
out_ifds – Optional output array for decoded IFD references (may be empty).
options – Decode options + limits.

ExifDecodeResult measure_exif_tiff(std::span<const std::byte> tiff_bytes, const ExifDecodeOptions &options = ExifDecodeOptions{}) noexcept¶

Estimates EXIF/TIFF decode counts using the same limits/options.

This function performs a bounded decode pass into an internal scratch store and returns the same status/counter model as decode_exif_tiff. Callers can use this to preflight entry counts before full decode/export.

const char *tiff_compression_name(uint64_t value) noexcept¶

const char *tiff_photometric_interpretation_name(uint64_t value) noexcept¶

const char *tiff_planar_configuration_name(uint64_t value) noexcept¶

const char *tiff_resolution_unit_name(uint64_t value) noexcept¶

const char *exif_exposure_program_name(uint64_t value) noexcept¶

const char *exif_exposure_mode_name(uint64_t value) noexcept¶

const char *exif_metering_mode_name(uint64_t value) noexcept¶

const char *exif_light_source_name(uint64_t value) noexcept¶

const char *exif_flash_name(uint64_t value) noexcept¶

const char *exif_color_space_name(uint64_t value) noexcept¶

const char *exif_white_balance_name(uint64_t value) noexcept¶

const char *exif_scene_capture_type_name(uint64_t value) noexcept¶

const char *exif_gain_control_name(uint64_t value) noexcept¶

const char *dng_cfa_layout_name(uint64_t value) noexcept¶

const char *dng_calibration_illuminant_name(uint64_t value) noexcept¶

const char *exif_tag_numeric_value_name(std::string_view ifd, uint16_t tag, uint64_t value) noexcept¶

Interprets common numeric enum-like values by EXIF/TIFF/DNG tag id and selected bounded MakerNote contexts.

Returns an empty string when OpenMeta has no stable public interpretation for the value. Unknown values remain numeric and lossless in the underlying MetaStore entry.

ExrAdapterResult build_exr_attribute_batch(const MetaStore &store, ExrAdapterBatch *out, const ExrAdapterOptions &options = ExrAdapterOptions{}) noexcept¶

Builds one owned EXR-native attribute batch from a MetaStore.

Only MetaKeyKind::ExrAttribute entries are exported. Known scalar and vector EXR types are encoded back into EXR little-endian attribute bytes. Unknown/custom attributes are preserved as opaque raw bytes when the original type name is available in Origin::wire_type_name.

ExrAdapterResult build_prepared_exr_attribute_batch(const PreparedTransferBundle &bundle, ExrAdapterBatch *out, const ExrAdapterOptions &options = ExrAdapterOptions{}) noexcept¶

Builds one EXR-native attribute batch from a prepared EXR transfer bundle.

This bridges the transfer pipeline with EXR host integrations: callers can prepare metadata once with prepare_metadata_for_target using TransferTargetFormat::Exr, then materialize a host-facing ExrAdapterBatch without re-projecting from the source MetaStore.

Current EXR prepared transfer blocks serialize one logical string attribute per block and target part 0.

BuildExrAttributeBatchFileResult build_exr_attribute_batch_from_file(const char *path, ExrAdapterBatch *out, const BuildExrAttributeBatchFileOptions &options = BuildExrAttributeBatchFileOptions{}) noexcept¶

Reads one file, prepares EXR transfer metadata, then materializes a host-facing ExrAdapterBatch.

This is the direct public file-helper for thin bindings and host tools. Internally it wraps prepare_metadata_for_target_file, forces the prepared target format to TransferTargetFormat::Exr, then calls build_prepared_exr_attribute_batch.

ExrAdapterStatus build_exr_attribute_part_spans(const ExrAdapterBatch &batch, std::vector<ExrAdapterPartSpan> *out) noexcept¶

Builds contiguous per-part spans over one ExrAdapterBatch.

The batch must keep attributes grouped by nondecreasing part index. Batches built by build_exr_attribute_batch satisfy this contract.

ExrAdapterStatus build_exr_attribute_part_views(const ExrAdapterBatch &batch, std::vector<ExrAdapterPartView> *out) noexcept¶: Builds zero-copy per-part views over one ExrAdapterBatch.

ExrAdapterReplayResult replay_exr_attribute_batch(const ExrAdapterBatch &batch, const ExrAdapterReplayCallbacks &callbacks) noexcept¶

Replays one ExrAdapterBatch through explicit host callbacks.

ExrAdapterReplayCallbacks::emit_attribute must be non-null. ExrAdapterReplayCallbacks::begin_part and ExrAdapterReplayCallbacks::end_part are optional.

ExrDecodeResult decode_exr_header(std::span<const std::byte> exr_bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const ExrDecodeOptions &options = ExrDecodeOptions{}) noexcept¶

Decodes OpenEXR header attributes and appends entries into store.

Each decoded header attribute becomes one Entry with:

MetaKeyKind::ExrAttribute (part_index + attribute name)
typed MetaValue for common scalar/vector/matrix EXR types
raw MetaValueKind::Bytes for unknown/complex EXR types

Duplicate attribute names are preserved.

ExrDecodeResult measure_exr_header(std::span<const std::byte> exr_bytes, const ExrDecodeOptions &options = ExrDecodeOptions{}) noexcept¶: Estimates EXR header decode counts using the same limits/options.

std::string_view geotiff_key_name(uint16_t key_id) noexcept¶: Returns a best-effort GeoTIFF key name for a numeric GeoKey id.

IccDecodeResult decode_icc_profile(std::span<const std::byte> icc_bytes, MetaStore &store, const IccDecodeOptions &options = IccDecodeOptions{}) noexcept¶

Decodes an ICC profile header and tag table into store.

The decoder emits:

MetaKeyKind::IccHeaderField entries for common header fields (typed when interpretation is stable: signature/u32/u64/s15Fixed16 arrays)
MetaKeyKind::IccTag entries (tag signature -> raw tag bytes)

IccDecodeResult measure_icc_profile(std::span<const std::byte> icc_bytes, const IccDecodeOptions &options = IccDecodeOptions{}) noexcept¶: Estimates ICC decode entry count using the same limits/options.

std::string_view icc_tag_name(uint32_t signature) noexcept¶: Returns a short display name for an ICC tag signature.

IccTagInterpretStatus interpret_icc_tag(uint32_t signature, std::span<const std::byte> tag_bytes, IccTagInterpretation *out, const IccTagInterpretOptions &options = IccTagInterpretOptions{}) noexcept¶

Best-effort interpretation for selected ICC tag payload types.

Supported payload type signatures:

desc (ASCII profile description)
text (ASCII text payload)
sig (embedded 4-byte signature)
data (ASCII/binary data payload summary)
mluc (multi-localized Unicode)
ncl2 (named-color table summary)
dtim (date/time number)
view (viewing conditions summary + numeric values)
meas (measurement summary + backing/flare values)
chrm (chromaticity coordinates + colorant summary)
sf32 (s15Fixed16 array)
uf32 (u16Fixed16 array)
ui08 (uInt8 array)
ui16 (uInt16 array)
ui32 (uInt32 array)
mft1 / mft2 (LUT summaries)
mAB / mBA (LUT-A/B structural summaries)
XYZ (s15Fixed16 XYZ triplets)
curv (TRC curves)
para (parametric curves)

bool format_icc_tag_display_value(uint32_t signature, std::span<const std::byte> tag_bytes, uint32_t max_values, uint32_t max_text_bytes, std::string *out) noexcept¶

Formats a best-effort human-readable value string for an ICC tag.

This helper is intended for CLI/Python display paths. It uses interpret_icc_tag and returns false for unsupported/malformed payloads.

void visit_metadata(const MetaStore &store, const ExportOptions &options, MetadataSink &sink) noexcept¶

Visits exported metadata entries in store order.

Deleted entries are skipped. Name mapping depends on ExportOptions::style.

API Stability: Stable host-facing v1 traversal API. The callback receives borrowed views that are valid only during the call to MetadataSink::on_item.

IptcIimDecodeResult decode_iptc_iim(std::span<const std::byte> iptc_bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const IptcIimDecodeOptions &options = IptcIimDecodeOptions{}) noexcept¶

Decodes an IPTC-IIM dataset stream and appends datasets into store.

Each dataset becomes one Entry with:

MetaKeyKind::IptcDataset (record + dataset id)
MetaValueKind::Bytes (raw dataset payload)

Duplicate datasets are preserved.

IptcIimDecodeResult measure_iptc_iim(std::span<const std::byte> iptc_bytes, const IptcIimDecodeOptions &options = IptcIimDecodeOptions{}) noexcept¶: Estimates IPTC-IIM dataset count using the same limits/options.

JumbfDecodeResult decode_jumbf_payload(std::span<const std::byte> bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const JumbfDecodeOptions &options = JumbfDecodeOptions{}) noexcept¶

Decodes a JUMBF/C2PA payload and appends entries into store.

Emitted entries use:

MetaKeyKind::JumbfField for structural fields
MetaKeyKind::JumbfCborKey for decoded CBOR keys/values

Duplicate keys are preserved.

JumbfDecodeResult measure_jumbf_payload(std::span<const std::byte> bytes, const JumbfDecodeOptions &options = JumbfDecodeOptions{}) noexcept¶: Estimates JUMBF decode entry count using the same limits/options.

JumbfStructureEstimate measure_jumbf_structure(std::span<const std::byte> bytes, const JumbfDecodeLimits &limits = JumbfDecodeLimits{}) noexcept¶

Estimates structural nesting for a JUMBF/C2PA payload.

Performs bounded BMFF box traversal and bounded CBOR structural parsing to report maximum observed nesting depth and item counts. This function is intended for preflight risk checks before full decode.

LibRawOrientationResult map_exif_orientation_to_libraw_flip(uint16_t exif_orientation, const LibRawOrientationOptions &options = LibRawOrientationOptions{}) noexcept¶

Maps one EXIF/TIFF/XMP orientation value into the common LibRaw imgdata.sizes.flip convention.

Supported exact mappings are:

EXIF 1 -> LibRaw 0
EXIF 3 -> LibRaw 3
EXIF 6 -> LibRaw 6
EXIF 8 -> LibRaw 5

Mirrored EXIF orientations (2, 4, 5, 7) are not directly representable in LibRaw’s common flip model. With LibRawMirrorPolicy::Reject they fail explicitly. With LibRawMirrorPolicy::DropMirror they are collapsed to the nearest rotation-only convention:

2 -> 1
4 -> 3
5 -> 8
7 -> 6

For LibRawOrientationTarget::EmbeddedPreview, the default policy is to pass previews through unchanged because preview orientation is often already baked into the extracted bytes or carried by the preview’s own metadata.

LibRawFlipToExifResult map_libraw_flip_to_exif_orientation(uint32_t libraw_flip, const LibRawFlipToExifOptions &options = LibRawFlipToExifOptions{}) noexcept¶

Maps one common LibRaw imgdata.sizes.flip value back into EXIF/TIFF orientation space.

Supported exact mappings are:

LibRaw 0 -> EXIF 1
LibRaw 3 -> EXIF 3
LibRaw 5 -> EXIF 8
LibRaw 6 -> EXIF 6

This recovers only the non-mirrored EXIF orientation states because the common LibRaw flip model does not preserve the full TIFF 8-state orientation space.

For LibRawOrientationTarget::EmbeddedPreview, the default policy is to pass previews through unchanged and assume EXIF orientation 1.

LibRawOrientationResult map_meta_orientation_to_libraw_flip(const MetaStore &store, const LibRawOrientationOptions &options = LibRawOrientationOptions{}) noexcept¶

Extracts canonical orientation metadata from a MetaStore and maps it into the common LibRaw flip convention.

Source precedence is:

EXIF ifd0:0x0112
XMP tiff:Orientation
assumed default EXIF orientation 1 if neither is present

LibRawOrientationFileResult map_meta_orientation_to_libraw_flip_from_file(const char *path, const LibRawOrientationFileOptions &options = LibRawOrientationFileOptions{}) noexcept¶

Reads one file, decodes supported metadata, then maps canonical orientation metadata into the LibRaw flip convention.

This is the direct file-helper for thin host integrations that want the same explicit orientation result without manually calling simple_meta_read and extracting ifd0:0x0112.

MetaStore commit(const MetaStore &base, std::span<const MetaEdit> edits)¶: Applies edits to base and returns a new MetaStore snapshot.

MetaStore compact(const MetaStore &base)¶: Compacts a store by removing tombstones and rewriting indices.

constexpr EntryFlags operator|(EntryFlags a, EntryFlags b) noexcept¶

constexpr EntryFlags operator&(EntryFlags a, EntryFlags b) noexcept¶

constexpr EntryFlags &operator|=(EntryFlags &a, EntryFlags b) noexcept¶

constexpr bool any(EntryFlags flags, EntryFlags test) noexcept¶: Returns true if any bits in test are present in flags.

MetaKey make_exif_tag_key(ByteArena &arena, std::string_view ifd, uint16_t tag)¶: Creates a key for an EXIF/TIFF tag within a named IFD token (e.g. “ifd0”, “exififd”).

MetaKey make_comment_key() noexcept¶

MetaKey make_exr_attribute_key(ByteArena &arena, uint32_t part_index, std::string_view name)¶: Creates a key for an OpenEXR attribute name in a specific part.

MetaKey make_iptc_dataset_key(uint16_t record, uint16_t dataset) noexcept¶

MetaKey make_xmp_property_key(ByteArena &arena, std::string_view schema_ns, std::string_view property_path)¶

MetaKey make_icc_header_field_key(uint32_t offset) noexcept¶

MetaKey make_icc_tag_key(uint32_t signature) noexcept¶

MetaKey make_photoshop_irb_key(uint16_t resource_id) noexcept¶

MetaKey make_photoshop_irb_field_key(ByteArena &arena, uint16_t resource_id, std::string_view field)¶

MetaKey make_geotiff_key(uint16_t key_id) noexcept¶

MetaKey make_printim_field_key(ByteArena &arena, std::string_view field)¶

MetaKey make_bmff_field_key(ByteArena &arena, std::string_view field)¶

MetaKey make_jumbf_field_key(ByteArena &arena, std::string_view field)¶

MetaKey make_jumbf_cbor_key(ByteArena &arena, std::string_view key)¶

MetaKey make_png_text_key(ByteArena &arena, std::string_view keyword, std::string_view field)¶

int compare_key(const ByteArena &arena, const MetaKey &a, const MetaKey &b) noexcept¶: Orders keys for deterministic storage/indexing.

int compare_key_view(const ByteArena &arena, const MetaKeyView &a, const MetaKey &b) noexcept¶: Orders a borrowed key against an owned key using the same ordering as compare_key.

const char *metadata_capability_family_name(MetadataCapabilityFamily family) noexcept¶

const char *metadata_capability_support_name(MetadataCapabilitySupport support) noexcept¶

bool metadata_capability_available(MetadataCapabilitySupport support) noexcept¶

MetadataCapability metadata_capability(TransferTargetFormat format, MetadataCapabilityFamily family) noexcept¶

MetadataConceptResolution resolve_metadata_concept(const MetaStore &store, MetadataConceptKind kind)¶

MetadataConceptResult resolve_metadata_concepts(const MetaStore &store)¶

const char *metadata_concept_kind_name(MetadataConceptKind kind) noexcept¶

const char *metadata_concept_source_family_name(MetadataConceptSourceFamily family) noexcept¶

const char *metadata_concept_role_name(MetadataConceptRole role) noexcept¶

const char *metadata_concept_datetime_precision_name(MetadataConceptDateTimePrecision precision) noexcept¶

const char *metadata_concept_timezone_kind_name(MetadataConceptTimeZoneKind kind) noexcept¶

const char *metadata_concept_transfer_hint_name(MetadataConceptTransferHint hint) noexcept¶

const char *metadata_concept_gps_altitude_reference_name(uint8_t code) noexcept¶

MetadataInterpretationResult interpret_metadata_query(const MetaStore &store, MetadataQueryKind kind)¶

MetadataInterpretationResult interpret_metadata(const MetaStore &store)¶

MetadataQueryResult query_metadata(const MetaStore &store, MetadataQueryKind kind)¶

MetadataQueryResult query_crop_metadata(const MetaStore &store)¶

MetadataQueryResult query_exposure_gain_metadata(const MetaStore &store)¶

MetadataQueryResult query_white_balance_metadata(const MetaStore &store)¶

MetadataQueryResult query_color_metadata(const MetaStore &store)¶

MetadataQueryResult query_lens_correction_metadata(const MetaStore &store)¶

MetadataQueryResult query_orientation_metadata(const MetaStore &store)¶

MetadataQueryResult query_raw_processing_metadata(const MetaStore &store)¶

MetadataQueryResult query_descriptive_metadata(const MetaStore &store)¶

bool metadata_query_fuzzy_search_available() noexcept¶

const char *metadata_query_kind_name(MetadataQueryKind kind) noexcept¶

const char *metadata_query_semantic_kind_name(MetadataQuerySemanticKind kind) noexcept¶

const char *metadata_query_value_shape_name(MetadataQueryValueShape shape) noexcept¶

PersistPreparedTransferFileResult persist_prepared_transfer_file_result(const ExecutePreparedTransferFileResult &prepared, const PersistPreparedTransferFileOptions &options) noexcept¶

Persists edited output, generated XMP sidecar output, and any requested destination-sidecar cleanup from execute_prepared_transfer_file.

This is a bounded file helper for host applications that want the same output/sidecar behavior as the CLI or Python wrapper without reimplementing write and cleanup logic.

EmitTransferResult build_executed_transfer_package_batch(std::span<const std::byte> edit_input, const PreparedTransferBundle &bundle, const ExecutePreparedTransferResult &execute, PreparedTransferPackageBatch *out_batch) noexcept¶

Materializes the final persisted package batch for one executed transfer state.

For direct emit targets this builds the target-neutral emit package batch. For JPEG/TIFF/BMFF edit flows this builds the rewrite package batch from the selected edit state and input bytes.

PrepareTransferResult prepare_metadata_for_target(const MetaStore&, const PrepareTransferRequest&, PreparedTransferBundle *out_bundle) noexcept¶: Draft bundle preparation entry point.

PrepareTransferResult prepare_metadata_for_target_snapshot(const TransferSourceSnapshot &snapshot, const PrepareTransferRequest &request, PreparedTransferBundle *out_bundle) noexcept¶

Prepare a target-specific transfer bundle from a decoded source snapshot.

This is the fileless counterpart to prepare_metadata_for_target_file for host applications that already hold a reusable decoded source snapshot from an earlier read.

Current snapshot execution is decoded-store-backed. Opt-in raw carrier payloads can be retained in the snapshot for host diagnostics and future passthrough policy, but are not consumed by this preparation entry point yet.

API Stability: Experimental host-facing API.

TransferSourceSnapshot build_transfer_source_snapshot(const MetaStore &store) noexcept¶

Build a reusable decoded source snapshot from an existing MetaStore.

The snapshot stores its own finalized copy of the input store so later transfer preparation or execution does not depend on the caller keeping the original store alive or immutable.

API Stability: Experimental host-facing API.

TransferSafetyAudit transfer_safety_audit_from_store(const MetaStore &store, TransferSafetyMode safety) noexcept¶

Summarize metadata that a transfer safety mode will keep, filter, or invalidate before writing a target.

API Stability: Experimental host-facing API for diagnostics, UI, and preflight decisions.

TransferConceptDiagnostics transfer_concept_diagnostics_from_store(const MetaStore &store, TransferSafetyMode safety)¶

const char *transfer_concept_diagnostic_action_name(TransferConceptDiagnosticAction action) noexcept¶

const char *transfer_concept_diagnostic_reason_name(TransferConceptDiagnosticReason reason) noexcept¶

TransferConceptDiagnosticSeverity transfer_concept_diagnostic_severity(const TransferConceptDiagnostic &diagnostic) noexcept¶

const char *transfer_concept_diagnostic_severity_name(TransferConceptDiagnosticSeverity severity) noexcept¶

const char *transfer_concept_diagnostic_message(const TransferConceptDiagnostic &diagnostic) noexcept¶

TransferRawCarrierPassthroughAudit raw_carrier_passthrough_audit_from_snapshot(const TransferSourceSnapshot &snapshot, const TransferRawCarrierPassthroughAuditOptions &options = TransferRawCarrierPassthroughAuditOptions{}) noexcept¶

Report which opt-in raw source carriers are passthrough candidates.

This helper is diagnostic only. It checks preserved payload availability, target carrier compatibility, decoded-entry safety filtering, content-bound C2PA rules, and explicit profile drops. It does not enable passthrough by itself; callers must opt in through PrepareTransferRequest.

API Stability: Experimental host-facing API for diagnostics, UI, and preflight decisions.

EmitTransferResult append_prepared_bundle_jpeg_jumbf(PreparedTransferBundle *bundle, std::span<const std::byte> logical_payload, const AppendPreparedJpegJumbfOptions &options = AppendPreparedJpegJumbfOptions{}) noexcept¶

Append one logical raw JUMBF payload as JPEG APP11 transfer blocks.

The input must be a logical JUMBF BMFF payload (jumb/jumd…), not an already wrapped APP11 marker payload. C2PA content-bound payloads are rejected by this helper; they require a dedicated invalidation/re-sign path.

On success, the bundle policy decision for JUMBF is updated to explicit Keep, and one or more jpeg:app11-jumbf prepared blocks are appended.

EmitTransferResult emit_prepared_bundle_jpeg(const PreparedTransferBundle &bundle, JpegTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into a JPEG backend.

Route mapping:

jpeg:app1-exif -> APP1 (0xE1)
jpeg:app1-xmp -> APP1 (0xE1)
jpeg:app2-icc -> APP2 (0xE2)
jpeg:app13-iptc -> APP13 (0xED)
jpeg:appN / jpeg:appN-* where N in [0,15]
jpeg:com -> COM (0xFE)

EmitTransferResult emit_prepared_bundle_tiff(const PreparedTransferBundle &bundle, TiffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into a TIFF backend.

Route mapping:

tiff:tag-700-xmp -> TIFF tag 700 (XMP packet)
tiff:ifd-exif-app1 -> serialized EXIF APP1 input for ExifIFD materialization
tiff:tag-34675-icc -> TIFF tag 34675 (ICC profile)
tiff:tag-33723-iptc -> TIFF tag 33723 (IPTC IIM stream)

EmitTransferResult emit_prepared_bundle_jxl(const PreparedTransferBundle &bundle, JxlTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into a JPEG XL backend.

Route mapping:

jxl:icc-profile -> encoder ICC profile
jxl:box-exif -> Exif
jxl:box-xml -> xml
jxl:box-jumb -> jumb
jxl:box-c2pa -> c2pa

EmitTransferResult emit_prepared_bundle_webp(const PreparedTransferBundle &bundle, WebpTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into a WebP backend.

Route mapping:

webp:chunk-exif -> EXIF
webp:chunk-xmp -> XMP
webp:chunk-iccp -> ICCP
webp:chunk-c2pa -> C2PA

EmitTransferResult emit_prepared_bundle_png(const PreparedTransferBundle &bundle, PngTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into a PNG backend.

Route mapping:

png:chunk-exif -> eXIf
png:chunk-xmp -> iTXt
png:chunk-iccp -> iCCP

EmitTransferResult emit_prepared_bundle_jp2(const PreparedTransferBundle &bundle, Jp2TransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into a JP2 backend.

Route mapping:

jp2:box-exif -> Exif
jp2:box-xml -> xml
jp2:box-jp2h-colr -> jp2h carrying one colr ICC child box

EmitTransferResult emit_prepared_bundle_exr(const PreparedTransferBundle &bundle, ExrTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into an EXR backend.

Route mapping:

exr:attribute-string -> EXR string header attribute

This first-class EXR target is intentionally bounded to safe flattened string attributes. It does not rewrite complete EXR files.

EmitTransferResult emit_prepared_bundle_bmff(const PreparedTransferBundle &bundle, BmffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Emit prepared metadata blocks into an ISO-BMFF metadata backend.

Route mapping:

bmff:item-exif -> Exif item payload
bmff:item-xmp -> mime item carrying XMP
bmff:item-jumb -> jumb item payload
bmff:item-c2pa -> c2pa item payload
bmff:property-colr-icc -> colr property payload with prof ICC data

EmitTransferResult compile_prepared_bundle_tiff(const PreparedTransferBundle &bundle, PreparedTiffEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Compile a reusable TIFF emit plan from a prepared bundle.

This maps route strings to TIFF tags once for high-throughput “prepare once, emit many” workflows.

EmitTransferResult emit_prepared_bundle_tiff_compiled(const PreparedTransferBundle &bundle, const PreparedTiffEmitPlan &plan, TiffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled TIFF emit plan.

EmitTransferResult compile_prepared_bundle_jxl(const PreparedTransferBundle &bundle, PreparedJxlEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Compile a reusable JPEG XL emit plan from a prepared bundle.

This maps route strings to JPEG XL box types once for high-throughput “prepare once, emit many” workflows.

EmitTransferResult emit_prepared_bundle_jxl_compiled(const PreparedTransferBundle &bundle, const PreparedJxlEmitPlan &plan, JxlTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled JPEG XL emit plan.

EmitTransferResult build_prepared_jxl_encoder_handoff_view(const PreparedTransferBundle &bundle, PreparedJxlEncoderHandoffView *out_view, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Builds one encoder-side handoff view for prepared JPEG XL metadata.

This exposes the single encoder ICC profile separately from the normal JXL box path. Boxes remain on the regular jxl:box-* route contract.

EmitTransferResult build_prepared_jxl_encoder_handoff(const PreparedTransferBundle &bundle, PreparedJxlEncoderHandoff *out_handoff, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

PreparedJxlEncoderHandoffIoResult serialize_prepared_jxl_encoder_handoff(const PreparedJxlEncoderHandoff &handoff, std::vector<std::byte> *out_bytes) noexcept¶

PreparedJxlEncoderHandoffIoResult deserialize_prepared_jxl_encoder_handoff(std::span<const std::byte> bytes, PreparedJxlEncoderHandoff *out_handoff) noexcept¶

EmitTransferResult compile_prepared_bundle_webp(const PreparedTransferBundle &bundle, PreparedWebpEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Compile a reusable WebP emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_png(const PreparedTransferBundle &bundle, PreparedPngEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Compile a reusable PNG emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_jp2(const PreparedTransferBundle &bundle, PreparedJp2EmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Compile a reusable JP2 emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_exr(const PreparedTransferBundle &bundle, PreparedExrEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Compile a reusable EXR emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_bmff(const PreparedTransferBundle &bundle, PreparedBmffEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Compile a reusable ISO-BMFF metadata emit plan from a prepared bundle.

EmitTransferResult emit_prepared_bundle_webp_compiled(const PreparedTransferBundle &bundle, const PreparedWebpEmitPlan &plan, WebpTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled WebP emit plan.

EmitTransferResult emit_prepared_bundle_png_compiled(const PreparedTransferBundle &bundle, const PreparedPngEmitPlan &plan, PngTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled PNG emit plan.

EmitTransferResult emit_prepared_bundle_jp2_compiled(const PreparedTransferBundle &bundle, const PreparedJp2EmitPlan &plan, Jp2TransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled JP2 emit plan.

EmitTransferResult emit_prepared_bundle_exr_compiled(const PreparedTransferBundle &bundle, const PreparedExrEmitPlan &plan, ExrTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled EXR emit plan.

EmitTransferResult emit_prepared_bundle_bmff_compiled(const PreparedTransferBundle &bundle, const PreparedBmffEmitPlan &plan, BmffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled ISO-BMFF metadata emit plan.

EmitTransferResult compile_prepared_bundle_jpeg(const PreparedTransferBundle &bundle, PreparedJpegEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Compile a reusable JPEG emit plan from a prepared bundle.

This maps route strings to marker codes once for high-throughput “prepare once, emit many” workflows.

EmitTransferResult emit_prepared_bundle_jpeg_compiled(const PreparedTransferBundle &bundle, const PreparedJpegEmitPlan &plan, JpegTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Emit a prepared bundle using a precompiled JPEG emit plan.

EmitTransferResult write_prepared_bundle_jpeg(const PreparedTransferBundle &bundle, TransferByteWriter &writer, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶

Write prepared JPEG metadata marker bytes directly to a byte sink.

This emits serialized APP/COM marker records only. It does not write SOI, SOS/image data, or EOI.

EmitTransferResult write_prepared_bundle_jpeg_compiled(const PreparedTransferBundle &bundle, const PreparedJpegEmitPlan &plan, TransferByteWriter &writer, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Write prepared JPEG metadata marker bytes using a precompiled plan.

ReadTransferSourceSnapshotFileResult read_transfer_source_snapshot_file(const char *path, const ReadTransferSourceSnapshotFileOptions &options = ReadTransferSourceSnapshotFileOptions{}) noexcept¶

Read a file into a reusable decoded source snapshot.

This helper hides the scratch-buffer management needed by simple_meta_read and returns an owned TransferSourceSnapshot that can be reused later with prepare_metadata_for_target_snapshot without reopening the source file.

Current snapshot contract is decoded-store-backed. Raw carrier provenance and payload bytes are preserved only when read options request them; transfer execution still uses decoded re-emission.

API Stability: Experimental host-facing API.

ReadTransferSourceSnapshotBytesResult read_transfer_source_snapshot_bytes(std::span<const std::byte> bytes, const ReadTransferSourceSnapshotOptions &options = ReadTransferSourceSnapshotOptions{}) noexcept¶

Read host-owned bytes into a reusable decoded source snapshot.

This is the in-memory counterpart to read_transfer_source_snapshot_file for hosts that already own the source bytes and do not want a file-path API.

Current snapshot contract is decoded-store-backed. Raw carrier provenance and payload bytes are preserved only when read options request them; transfer execution still uses decoded re-emission.

API Stability: Experimental host-facing API.

PrepareTransferFileResult prepare_metadata_for_target_file(const char *path, const PrepareTransferFileOptions &options = PrepareTransferFileOptions{}) noexcept¶

High-level helper: read file, decode metadata, and prepare transfer bundle.

This helper is intended for thin wrappers (CLI/Python) that need read -> prepare with consistent resource policies.

TransferStatus build_prepared_c2pa_sign_request(const PreparedTransferBundle &bundle, PreparedTransferC2paSignRequest *out_request) noexcept¶

Derive an external signer request from a prepared C2PA rewrite bundle.

The returned request is preparation-only. It does not build a manifest or perform signing. For supported targets, it exposes the deterministic rewrite-without-C2PA byte sequence as preserved source ranges plus prepared target carrier chunks.

TransferStatus build_prepared_c2pa_handoff_package(const PreparedTransferBundle &bundle, std::span<const std::byte> target_input, PreparedTransferC2paHandoffPackage *out_package) noexcept¶

Build a structured external-signer handoff package.

This wraps build_prepared_c2pa_sign_request and build_prepared_c2pa_sign_request_binding into one reusable core result.

TransferStatus build_prepared_c2pa_signed_package(const PreparedTransferBundle &bundle, const PreparedTransferC2paSignerInput &input, PreparedTransferC2paSignedPackage *out_package) noexcept¶

Build a persistable signed-result package from a prepared bundle.

This wraps build_prepared_c2pa_sign_request and copies the external signer material into one reusable core object.

EmitTransferResult apply_prepared_c2pa_sign_result(PreparedTransferBundle *bundle, const PreparedTransferC2paSignRequest &request, const PreparedTransferC2paSignerInput &input) noexcept¶

Stage externally signed C2PA rewrite output into a prepared bundle.

This consumes the request built by build_prepared_c2pa_sign_request and replaces prepared target C2PA carrier blocks with the external signed logical payload. OpenMeta does not perform signing here; it only validates the input contract and re-packs the logical payload into the prepared target carrier.

EmitTransferResult apply_prepared_c2pa_signed_package(PreparedTransferBundle *bundle, const PreparedTransferC2paSignedPackage &package) noexcept¶: Stage one persisted signed C2PA package into a prepared bundle.

BuildPreparedC2paBindingResult build_prepared_c2pa_sign_request_binding(const PreparedTransferBundle &bundle, std::span<const std::byte> target_input, const PreparedTransferC2paSignRequest &request, std::vector<std::byte> *out_bytes) noexcept¶

Materialize the exact content-binding byte stream for a C2PA sign request.

This reconstructs the deterministic rewrite-without-C2PA byte sequence described by request by combining preserved source ranges from target_input with prepared target carrier chunks from bundle.

ValidatePreparedC2paSignResult validate_prepared_c2pa_sign_result(const PreparedTransferBundle &bundle, const PreparedTransferC2paSignRequest &request, const PreparedTransferC2paSignerInput &input) noexcept¶

Validate one externally signed C2PA payload before staging it.

This performs the same input and payload checks used by apply_prepared_c2pa_sign_result, but does not mutate bundle.

ValidatePreparedC2paSignResult validate_prepared_c2pa_signed_package(const PreparedTransferBundle &bundle, const PreparedTransferC2paSignedPackage &package) noexcept¶: Validate one persisted signed C2PA package before staging it.

PreparedTransferC2paPackageIoResult serialize_prepared_c2pa_handoff_package(const PreparedTransferC2paHandoffPackage &package, std::vector<std::byte> *out_bytes) noexcept¶: Serialize one C2PA handoff package into a stable binary transport.

PreparedTransferC2paPackageIoResult deserialize_prepared_c2pa_handoff_package(std::span<const std::byte> bytes, PreparedTransferC2paHandoffPackage *out_package) noexcept¶: Parse one serialized C2PA handoff package.

PreparedTransferC2paPackageIoResult serialize_prepared_c2pa_signed_package(const PreparedTransferC2paSignedPackage &package, std::vector<std::byte> *out_bytes) noexcept¶: Serialize one persisted signed C2PA package into a stable binary transport.

PreparedTransferC2paPackageIoResult deserialize_prepared_c2pa_signed_package(std::span<const std::byte> bytes, PreparedTransferC2paSignedPackage *out_package) noexcept¶: Parse one serialized signed C2PA package.

EmitTransferResult compile_prepared_transfer_execution(const PreparedTransferBundle &bundle, const EmitTransferOptions &options, PreparedTransferExecutionPlan *out_plan) noexcept¶

Compile a reusable execution plan for execute_prepared_transfer_compiled.

This performs route-to-backend compilation once and stores the selected emit options inside the plan for repeated runtime execution.

EmitTransferResult build_prepared_transfer_adapter_view(const PreparedTransferBundle &bundle, PreparedTransferAdapterView *out_view, const EmitTransferOptions &options = {}) noexcept¶

Build one target-neutral adapter view over prepared transfer ops.

This compiles the same target-specific route mappings used by emit execution, then flattens them into one explicit operation list for host integrations that want to consume prepared blocks without parsing routes.

API Stability: Experimental host-facing API.

EmitTransferResult emit_prepared_transfer_adapter_view(const PreparedTransferBundle &bundle, const PreparedTransferAdapterView &view, TransferAdapterSink &sink) noexcept¶

Emit one prepared adapter view into a generic host-side sink.

This lets host integrations consume the flattened adapter operation list without re-parsing routes or target-specific dispatch tokens.

API Stability: Experimental host-facing API.

ApplyTimePatchResult apply_time_patches(PreparedTransferBundle *bundle, std::span<const TimePatchUpdate> updates, const ApplyTimePatchOptions &options = ApplyTimePatchOptions{}) noexcept¶

Apply fixed-width time patch updates in-place on a prepared bundle.

Patches are applied to byte ranges listed in bundle.time_patch_map (typically filled for EXIF APP1 during prepare).

ApplyTimePatchResult apply_time_patches_view(PreparedTransferBundle *bundle, std::span<const TimePatchView> updates, const ApplyTimePatchOptions &options = ApplyTimePatchOptions{}) noexcept¶

Apply fixed-width time patch views in-place on a prepared bundle.

This overload avoids owned patch buffers and is intended for high-throughput prepare once -> compile once -> patch/emit many integrations.

ExecutePreparedTransferResult execute_prepared_transfer(PreparedTransferBundle *bundle, std::span<const std::byte> edit_input = {}, const ExecutePreparedTransferOptions &options = ExecutePreparedTransferOptions{}) noexcept¶

Execute the high-level transfer flow on a prepared bundle.

This helper applies optional time patches, compiles/emits prepared blocks, and optionally plans/applies a target-stream edit using edit_input. It is intended for thin wrappers and high-throughput “prepare once, reuse” integrations.

ExecutePreparedTransferResult execute_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, std::span<const std::byte> edit_input = {}, const ExecutePreparedTransferOptions &options = ExecutePreparedTransferOptions{}) noexcept¶

Execute the transfer flow using a precompiled execution plan.

This is intended for high-throughput integrations that want prepare once -> compile once -> patch/emit many.

ExecutePreparedTransferResult write_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, TransferByteWriter &writer, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶

Hot-path helper: apply non-owning time patches and stream emit bytes.

This is a thin encoder-integration helper for prepare once -> compile once -> patch -> write workflows. It reuses execute_prepared_transfer_compiled for plan validation and emission, but accepts non-owning patch views to avoid per-call owned patch buffers.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, JpegTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶

Hot-path helper: apply non-owning time patches and emit through a JPEG backend.

This is the direct backend-emitter path for prepare once -> compile once -> patch -> emit integrations that already own a JPEG encoder/backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, TiffTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶

Hot-path helper: apply non-owning time patches and emit through a TIFF backend.

TIFF intentionally uses backend-emitter or rewrite/edit paths instead of a metadata-only byte-writer emit contract.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, JxlTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶: Hot-path helper: apply non-owning time patches and emit through a JPEG XL backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, WebpTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶: Hot-path helper: apply non-owning time patches and emit through a WebP backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, PngTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶: Hot-path helper: apply non-owning time patches and emit through a PNG backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, Jp2TransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶: Hot-path helper: apply non-owning time patches and emit through a JP2 backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, ExrTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶: Hot-path helper: apply non-owning time patches and emit through an EXR backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, BmffTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept¶: Hot-path helper: apply non-owning time patches and emit through an ISO-BMFF metadata backend.

ExecutePreparedTransferFileResult execute_prepared_transfer_file(const char *path, const ExecutePreparedTransferFileOptions &options = ExecutePreparedTransferFileOptions{}) noexcept¶

High-level helper: read file, prepare a bundle, then execute transfer.

This wraps prepare_metadata_for_target_file plus execute_prepared_transfer for CLI/Python entry points that want a single file-based execution path.

ExecutePreparedTransferFileResult execute_prepared_transfer_snapshot(const TransferSourceSnapshot &snapshot, const ExecutePreparedTransferSnapshotOptions &options = ExecutePreparedTransferSnapshotOptions{}) noexcept¶

High-level helper: prepare from a decoded source snapshot, then execute transfer.

This mirrors execute_prepared_transfer_file for hosts that already keep a reusable decoded source snapshot from an earlier read.

The input snapshot is not mutated. The helper copies the decoded store into a fresh local bundle-preparation state, so the same snapshot can be reused safely by concurrent callers that do not share the returned result object.

Current snapshot contract is decoded-store-backed. Raw carrier provenance and payload bytes are preserved only when read options request them; transfer execution still uses decoded re-emission.

API Stability: Experimental host-facing API.

ExecutePreparedTransferFileResult execute_prepared_transfer_snapshot(const TransferSourceSnapshot &snapshot, std::span<const std::byte> target_bytes, const ExecutePreparedTransferSnapshotOptions &options = ExecutePreparedTransferSnapshotOptions{}) noexcept¶

High-level helper: prepare from a decoded source snapshot, then edit a host-owned target byte buffer.

This is the fileless destination counterpart to execute_prepared_transfer_snapshot for hosts that already own the target bytes in memory and do not want OpenMeta to reopen the destination file.

The input snapshot and target byte span are not mutated. The helper copies decoded source state into a fresh local preparation store before executing the edit path.

API Stability: Experimental host-facing API.

ExecutePreparedTransferFileResult execute_prepared_transfer_bundle(const PreparedTransferBundle &bundle, std::span<const std::byte> target_bytes, const ExecutePreparedTransferBundleOptions &options = ExecutePreparedTransferBundleOptions{}) noexcept¶

High-level helper: execute a previously prepared bundle against host-owned target bytes.

This wraps execute_prepared_transfer with the same bounded sidecar and cleanup contract used by the file/snapshot helpers, but it starts from an already prepared bundle instead of rebuilding source state first.

API Stability: Experimental host-facing API. Treat the bundle as an immutable prepared input unless using documented patch helpers.

JpegEditPlan plan_prepared_bundle_jpeg_edit(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const PlanJpegEditOptions &options = PlanJpegEditOptions{}) noexcept¶

Plan JPEG metadata injection/edit strategy for a prepared bundle.

Auto selects InPlace when all emitted payloads can replace existing leading JPEG metadata segments with exact size match; otherwise it selects MetadataRewrite.

EmitTransferResult apply_prepared_bundle_jpeg_edit(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const JpegEditPlan &plan, std::vector<std::byte> *out_jpeg) noexcept¶

Apply a planned JPEG metadata edit and produce edited output bytes.

For InPlace, this replaces matched existing segment payload bytes in a copy of the input stream. For MetadataRewrite, this rewrites leading metadata segments and preserves the remaining codestream bytes unchanged.

EmitTransferResult write_prepared_bundle_jpeg_edit(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const JpegEditPlan &plan, TransferByteWriter &writer) noexcept¶: Apply a planned JPEG metadata edit and stream output bytes to a writer.

TiffEditPlan plan_prepared_bundle_tiff_edit(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const PlanTiffEditOptions &options = PlanTiffEditOptions{}) noexcept¶

Plan TIFF metadata rewrite for a prepared bundle.

This computes the expected output size and validates that TIFF-applicable prepared blocks can be materialized on the target stream.

EmitTransferResult apply_prepared_bundle_tiff_edit(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const TiffEditPlan &plan, std::vector<std::byte> *out_tiff) noexcept¶: Apply a planned TIFF metadata rewrite and produce edited output bytes.

EmitTransferResult write_prepared_bundle_tiff_edit(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const TiffEditPlan &plan, TransferByteWriter &writer) noexcept¶

Apply a planned TIFF metadata rewrite and stream output bytes to a writer.

Current implementation uses the same rewrite path as apply_prepared_bundle_tiff_edit and then writes the final bytes to the supplied sink.

EmitTransferResult build_prepared_transfer_emit_package(const PreparedTransferBundle &bundle, PreparedTransferPackagePlan *out_plan, const EmitTransferOptions &options = {}) noexcept¶

Build one deterministic direct-emit package plan for a prepared bundle.

Current implementation supports direct JPEG marker, JXL/WebP/PNG/JP2 carrier, and BMFF item/property payload packaging without requiring an input container byte stream.

EmitTransferResult build_prepared_bundle_jpeg_package(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const JpegEditPlan &plan, PreparedTransferPackagePlan *out_plan) noexcept¶

EmitTransferResult build_prepared_bundle_tiff_package(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const TiffEditPlan &plan, PreparedTransferPackagePlan *out_plan) noexcept¶

EmitTransferResult write_prepared_transfer_package(std::span<const std::byte> input, const PreparedTransferBundle &bundle, const PreparedTransferPackagePlan &plan, TransferByteWriter &writer) noexcept¶

EmitTransferResult build_prepared_transfer_package_batch(std::span<const std::byte> input, const PreparedTransferBundle &bundle, const PreparedTransferPackagePlan &plan, PreparedTransferPackageBatch *out_batch) noexcept¶

EmitTransferResult write_prepared_transfer_package_batch(const PreparedTransferPackageBatch &batch, TransferByteWriter &writer) noexcept¶

TransferSemanticKind classify_transfer_route_semantic_kind(std::string_view route) noexcept¶: Classifies one prepared transfer route into a target-neutral semantic kind.

std::string_view transfer_semantic_name(TransferSemanticKind kind) noexcept¶: Stable display name for one semantic transfer kind.

std::string_view prepared_transfer_artifact_kind_name(PreparedTransferArtifactKind kind) noexcept¶: Stable display name for one persisted transfer artifact kind.

EmitTransferResult collect_prepared_transfer_payload_views(const PreparedTransferBundle &bundle, std::vector<PreparedTransferPayloadView> *out, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Builds zero-copy semantic payload views over one prepared transfer bundle.

EmitTransferResult collect_prepared_transfer_payload_views(const PreparedTransferPayloadBatch &batch, std::vector<PreparedTransferPayloadView> *out) noexcept¶: Builds zero-copy semantic payload views over one persisted payload batch.

EmitTransferResult build_prepared_transfer_payload_batch(const PreparedTransferBundle &bundle, PreparedTransferPayloadBatch *out, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept¶: Builds one owned semantic payload batch from one prepared transfer bundle.

PreparedTransferPayloadIoResult serialize_prepared_transfer_payload_batch(const PreparedTransferPayloadBatch &batch, std::vector<std::byte> *out_bytes) noexcept¶

PreparedTransferArtifactIoResult inspect_prepared_transfer_artifact(std::span<const std::byte> bytes, PreparedTransferArtifactInfo *out_info) noexcept¶

PreparedTransferPayloadIoResult deserialize_prepared_transfer_payload_batch(std::span<const std::byte> bytes, PreparedTransferPayloadBatch *out_batch) noexcept¶

PreparedTransferPayloadReplayResult replay_prepared_transfer_payload_batch(const PreparedTransferPayloadBatch &batch, const PreparedTransferPayloadReplayCallbacks &callbacks) noexcept¶

EmitTransferResult collect_prepared_transfer_package_views(const PreparedTransferPackageBatch &batch, std::vector<PreparedTransferPackageView> *out) noexcept¶: Builds zero-copy semantic package views over one persisted package batch.

PreparedTransferPackageReplayResult replay_prepared_transfer_package_batch(const PreparedTransferPackageBatch &batch, const PreparedTransferPackageReplayCallbacks &callbacks) noexcept¶

PreparedTransferPackageIoResult serialize_prepared_transfer_package_batch(const PreparedTransferPackageBatch &batch, std::vector<std::byte> *out_bytes) noexcept¶

PreparedTransferPackageIoResult deserialize_prepared_transfer_package_batch(std::span<const std::byte> bytes, PreparedTransferPackageBatch *out_batch) noexcept¶

void build_ocio_metadata_tree(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterOptions &options) noexcept¶

Builds a deterministic metadata tree for OCIO-style consumers.

Mapping rules:

Item names with a prefix:name form become namespace nodes (prefix) with leaf children (name=value).
Other names are added as direct leaves under the root.

InteropSafetyStatus build_ocio_metadata_tree_safe(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterOptions &options, InteropSafetyError *error) noexcept¶

Strict safe export for OCIO-style metadata tree.

Unlike build_ocio_metadata_tree, this API fails when unsafe payloads are encountered (for example raw bytes or invalid/unsafe text sequences).

OcioAdapterOptions make_ocio_adapter_options(const OcioAdapterRequest &request) noexcept¶: Converts OcioAdapterRequest into OcioAdapterOptions.

void build_ocio_metadata_tree(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterRequest &request) noexcept¶: Builds metadata tree via the stable request model.

InteropSafetyStatus build_ocio_metadata_tree_safe(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterRequest &request, InteropSafetyError *error) noexcept¶: Request-based strict safe export for OCIO-style metadata tree.

bool exif_orientation_is_valid(uint16_t orientation) noexcept¶

bool exif_orientation_is_mirrored(uint16_t orientation) noexcept¶

bool exif_orientation_swaps_width_height(uint16_t orientation) noexcept¶

uint16_t exif_orientation_rotation_degrees_cw(uint16_t orientation, bool *out_valid = nullptr) noexcept¶

Returns the clockwise rotation component for a standard EXIF/TIFF orientation value.

Mirrored values keep the same decomposition used by common metadata tools. For example, orientation 5 reports mirror + 270 degrees clockwise. Invalid values return 0 and set out_valid to false when provided.

uint16_t exif_orientation_rotation_only(uint16_t orientation) noexcept¶

Returns the nearest rotation-only orientation.

Valid non-mirrored values are returned unchanged. Mirrored values are mapped to the closest non-mirrored rotation: 2 -> 1, 4 -> 3, 5 -> 8, 7 -> 6. Invalid values return 0.

const char *exif_orientation_name(uint16_t orientation) noexcept¶

ExifOrientationInterpretation interpret_exif_orientation(uint16_t orientation) noexcept¶

PhaseOneRawGeometryResult phaseone_raw_geometry_from_values(uint32_t sensor_width, uint32_t sensor_height, uint32_t sensor_left_margin, uint32_t sensor_top_margin, uint32_t image_width, uint32_t image_height) noexcept¶

PhaseOneRawGeometryResult phaseone_raw_geometry_from_store(const MetaStore &store) noexcept¶

PhaseOneRawProcessingResult phaseone_raw_processing_from_store(const MetaStore &store) noexcept¶

const char *phaseone_raw_geometry_status_name(PhaseOneRawGeometryStatus status) noexcept¶

const char *phaseone_raw_processing_status_name(PhaseOneRawProcessingStatus status) noexcept¶

PhotoshopIrbDecodeResult decode_photoshop_irb(std::span<const std::byte> irb_bytes, MetaStore &store, const PhotoshopIrbDecodeOptions &options = PhotoshopIrbDecodeOptions{}) noexcept¶

Decodes a Photoshop IRB stream and appends resources into store.

Each resource becomes one Entry with:

MetaKeyKind::PhotoshopIrb (resource id)
MetaValueKind::Bytes (raw resource payload)

A bounded interpreted subset is additionally emitted as MetaKeyKind::PhotoshopIrbField entries for fixed-layout and descriptor-header resources:

ResolutionInfo (0x03ED)
AlphaChannelsNames (0x03EE)
DisplayInfo (0x03EF)
PStringCaption (0x03F0)
BorderInformation (0x03F1)
BackgroundColor (0x03F2)
VersionInfo (0x0421)
PrintFlags (0x03F3)
EffectiveBW (0x03FB)
QuickMaskInfo (0x03FE)
TargetLayerID (0x0400)
LayersGroupInfo (0x0402)
JPEG_Quality (0x0406)
GridGuidesInfo (0x0408)
PhotoshopBGRThumbnail / PhotoshopThumbnail header fields (0x0409/0x040C)
CopyrightFlag (0x040A)
URL (0x040B)
GlobalAngle (0x040D)
ColorSamplersResource / ColorSamplersResource2 headers and records (0x040E/0x0431)
Watermark (0x0410)
ICC_Untagged (0x0411)
EffectsVisible (0x0412)
IDsBaseValue (0x0414)
UnicodeAlphaNames (0x0415)
IndexedColorTableCount (0x0416)
TransparentIndex (0x0417)
GlobalAltitude (0x0419)
SliceInfo (0x041A)
WorkflowURL (0x041B)
AlphaIdentifiers (0x041D)
URL_List (0x041E)
ICC_Profile byte count (0x040F)
EXIFInfo byte count (0x0422)
ExifInfo2 byte count (0x0423)
XMP byte count (0x0424)
IPTCDigest (0x0425)
PrintScaleInfo (0x0426)
PixelInfo / PixelAspectRatio (0x0428)
Descriptor-backed resource headers for LayerComps, MeasurementScale, TimelineInfo, SheetDisclosure, OnionSkins, CountInfo, PrintInfo2, PrintStyle, PathSelectionState, and OriginPathInfo
LayerSelectionIDs (0x042D)
LayerGroupsEnabledID (0x0430)
ChannelOptions (0x0435)
PrintFlagsInfo (0x2710)
ClippingPathName (0x0BB7)

If enabled, embedded IPTC-IIM, XMP, and ICC payloads are additionally decoded from resource ids 0x0404, 0x0424, and 0x040F into their regular OpenMeta entry families. IPTC-IIM and XMP entries are marked as EntryFlags::Derived.

PhotoshopIrbDecodeResult measure_photoshop_irb(std::span<const std::byte> irb_bytes, const PhotoshopIrbDecodeOptions &options = PhotoshopIrbDecodeOptions{}) noexcept¶: Estimates Photoshop IRB decode counts using the same limits/options.

std::string_view photoshop_irb_resource_name(uint16_t resource_id) noexcept¶

PreviewScanResult find_preview_candidates(std::span<const std::byte> file_bytes, std::span<const ContainerBlockRef> blocks, std::span<PreviewCandidate> out, const PreviewScanOptions &options) noexcept¶

Finds preview candidates from already scanned blocks.

This function currently analyzes EXIF/TIFF blocks and discovers:

JPEGInterchangeFormat/JPEGInterchangeFormatLength pairs
JpgFromRaw and JpgFromRaw2 byte blobs
Canon CR3 PRVW UUID stream preview JPEGs

Candidates are file-relative (file_offset + size) and can be copied with extract_preview_candidate.

PreviewScanResult scan_preview_candidates(std::span<const std::byte> file_bytes, std::span<ContainerBlockRef> blocks_scratch, std::span<PreviewCandidate> out, const PreviewScanOptions &options) noexcept¶: Convenience wrapper that runs scan_auto first, then find_preview_candidates.

PreviewExtractResult extract_preview_candidate(std::span<const std::byte> file_bytes, const PreviewCandidate &candidate, std::span<std::byte> out, const PreviewExtractOptions &options) noexcept¶: Extracts bytes for one preview candidate into out.

PrintImDecodeResult decode_printim(std::span<const std::byte> bytes, MetaStore &store, const PrintImDecodeLimits &limits) noexcept¶

Decodes a PrintIM block and appends fields into store.

On success, this creates a new block in store containing MetaKeyKind::PrintImField entries. The original EXIF tag should still be preserved separately by the EXIF/TIFF decoder.

Field naming:

version for the header version (ASCII, 4 bytes)
0xNNNN for each 16-bit entry id

inline void normalize_resource_policy(OpenMetaResourcePolicy *policy) noexcept¶

Normalizes traversal/recursion-related limits to safe defaults.

OpenMeta design goal: recursion/traversal limits should never become “unlimited” through a zero value in user policy. This helper keeps decode paths bounded for untrusted metadata.

inline OpenMetaResourcePolicy recommended_resource_policy() noexcept¶

inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, ExifDecodeOptions *exif, PayloadOptions *payload) noexcept¶

inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, XmpDecodeOptions *xmp, ExrDecodeOptions *exr, JumbfDecodeOptions *jumbf, IccDecodeOptions *icc, IptcIimDecodeOptions *iptc, PhotoshopIrbDecodeOptions *irb) noexcept¶

inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, XmpDecodeOptions *xmp, ExrDecodeOptions *exr, IccDecodeOptions *icc, IptcIimDecodeOptions *iptc, PhotoshopIrbDecodeOptions *irb) noexcept¶

inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, PreviewScanOptions *scan, PreviewExtractOptions *extract) noexcept¶

inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, XmpSidecarRequest *request) noexcept¶

SimpleMetaResult simple_meta_read(std::span<const std::byte> file_bytes, MetaStore &store, std::span<ContainerBlockRef> out_blocks, std::span<ExifIfdRef> out_ifds, std::span<std::byte> payload, std::span<uint32_t> payload_scratch_indices, const SimpleMetaDecodeOptions &options) noexcept¶

Scans a file container and decodes supported metadata payloads.

Current decode support:

EXIF/TIFF-IFD tags (decode_exif_tiff) from:
- JPEG/PNG/WebP/etc. EXIF blocks
- TIFF/DNG containers (whole file treated as a TIFF-IFD stream)
- ISO-BMFF containers (HEIF/AVIF/CR3) Exif items
ICC profiles (decode_icc_profile)
Photoshop IRB / 8BIM resources (decode_photoshop_irb)
IPTC-IIM dataset streams (decode_iptc_iim)
OpenEXR header attributes (decode_exr_header)
JUMBF / C2PA payloads (decode_jumbf_payload)
XMP packets (decode_xmp_packet)

Caller provides the scratch buffers (blocks + decoded IFD list) to keep the data flow explicit and allocation-free.

Parameters:

file_bytes – Full file bytes in memory.
store – Destination MetaStore (entries are appended).
out_blocks – Scratch buffer for block scanning results.
out_ifds – Scratch buffer for decoded IFD references.
payload – Scratch buffer for reassembled EXIF payload bytes.
payload_scratch_indices – Scratch buffer for payload part indices.
options – Full decode option set (EXIF/payload/XMP/EXR/JUMBF/ICC/IPTC/IRB).

SimpleMetaResult simple_meta_read(std::span<const std::byte> file_bytes, MetaStore &store, std::span<ContainerBlockRef> out_blocks, std::span<ExifIfdRef> out_ifds, std::span<std::byte> payload, std::span<uint32_t> payload_scratch_indices, const ExifDecodeOptions &exif_options, const PayloadOptions &payload_options) noexcept¶: Backward-compatible overload using EXIF and payload options only.

ValidateResult validate_file(const char *path, const ValidateOptions &options = ValidateOptions{}) noexcept¶

Validate one file using normal OpenMeta decode + CCM checks.

Validation covers:

decoder status health (scan/payload/exif/xmp/exr/jumbf/c2pa)
optional sidecar XMP read status (--xmp-sidecar equivalent)
DNG/CCM query/validation issues (collect_dng_ccm_fields)

VendorRawProcessingGroup classify_vendor_raw_processing_field(std::string_view ifd, std::string_view name, uint16_t tag) noexcept¶

VendorRawProcessingSummary vendor_raw_processing_from_store(const MetaStore &store, VendorRawProcessingFamily family) noexcept¶

bool vendor_raw_processing_group_has(VendorRawProcessingGroup groups, VendorRawProcessingGroup group) noexcept¶

const char *vendor_raw_processing_family_name(VendorRawProcessingFamily family) noexcept¶

const char *vendor_raw_processing_group_name(VendorRawProcessingGroup group) noexcept¶

XmpDecodeResult decode_xmp_packet(std::span<const std::byte> xmp_bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const XmpDecodeOptions &options = XmpDecodeOptions{}) noexcept¶

Decodes an XMP packet and appends properties into store.

The decoder emits one Entry per decoded property value with:

MetaKeyKind::XmpProperty (schema_ns URI + property_path)
MetaValueKind::Text (UTF-8)

Duplicate properties are preserved.

XmpDecodeResult measure_xmp_packet(std::span<const std::byte> xmp_bytes, const XmpDecodeOptions &options = XmpDecodeOptions{}) noexcept¶

Estimates XMP decode counts using the same limits/options.

This function performs a bounded decode pass into an internal scratch store and returns the same status/counter model as decode_xmp_packet.

XmpDumpResult dump_xmp_lossless(const MetaStore &store, std::span<std::byte> out, const XmpDumpOptions &options) noexcept¶

Emits a lossless OpenMeta dump as a valid XMP RDF/XML packet.

The output is safe-by-default:

Text fields are XML-escaped and additionally restricted to a safe ASCII subset.
Binary payloads (bytes/text/arrays/scalars) are stored as base64.

This dump is intended as a storage-agnostic sidecar format for debugging and offline workflows. It uses a private namespace (urn:openmeta:dump:1.0) and is not meant to replace standard, interoperable XMP mappings.

XmpDumpResult dump_xmp_portable(const MetaStore &store, std::span<std::byte> out, const XmpPortableOptions &options) noexcept¶

Emits a portable XMP sidecar packet (standard XMP schemas).

The output is safe-by-default:

XML reserved characters are escaped.
Invalid control bytes are emitted as deterministic ASCII escapes.

This mode is intended for interoperability (e.g. XMP sidecars alongside RAW/JPEG files). It emits a best-effort mapping from decoded EXIF/TIFF/GPS/IPTC-IIM fields to standard XMP properties (e.g. tiff:Make, exif:ExposureTime, xmp:ModifyDate, xmp:CreateDate, exif:GPSLatitude, dc:subject, photoshop:City, Iptc4xmpCore:Location).

XmpDumpResult dump_xmp_sidecar(const MetaStore &store, std::vector<std::byte> *out, const XmpSidecarOptions &options) noexcept¶

Emits an XMP sidecar into a resizable byte buffer.

This is a high-level wrapper around dump_xmp_lossless and dump_xmp_portable that:

selects format via XmpSidecarOptions::format,
grows output buffer automatically on XmpDumpStatus::OutputTruncated,
returns final bytes in out (trimmed to XmpDumpResult::written on success).

XmpSidecarOptions make_xmp_sidecar_options(const XmpSidecarRequest &request) noexcept¶

Converts XmpSidecarRequest into XmpSidecarOptions.

Useful for wrappers and adapters that expose one flattened option model.

XmpDumpResult dump_xmp_sidecar(const MetaStore &store, std::vector<std::byte> *out, const XmpSidecarRequest &request) noexcept¶: Emits an XMP sidecar using the stable XmpSidecarRequest model.

Variables

constexpr uint32_t kCompatibilityDumpContractVersion = 1U¶: Stable compatibility dump contract version.

constexpr uint32_t kExrCanonicalEncodingVersion = 1U¶: Stable EXR canonical value encoding contract version.

constexpr uint32_t kInteropExportContractVersion = 1U¶: Stable interop export naming contract version.

constexpr uint32_t kFlatHostExportContractVersion = 1U¶: Stable FlatHost naming contract version.

static constexpr BlockId kInvalidBlockId = 0xffffffffU¶

static constexpr EntryId kInvalidEntryId = 0xffffffffU¶

constexpr uint32_t kMetadataCapabilitiesContractVersion = 1U¶: Stable metadata capability contract version.

constexpr uint32_t kMetadataTransferContractVersion = 1U¶: Stable metadata transfer contract version.

constexpr uint16_t kTransferTargetImageSpecMaxSamples = 8U¶: Maximum channel/sample count represented by TransferTargetImageSpec.

file api_stability.md

file compatibility_dump.md

file exr_canonical_value_encoding.md

file development.md

file doxygen.md

file flat_host_mapping.md

file host_integration.md

file interpretation_status.md

file metadata_backend_matrix.md

file metadata_support.md

file metadata_transfer_plan.md

file quick_start.md

file raw_read_parity_plan.md

file openexr_metadata_fit.md

file writer_target_contract.md

file xmp_sync_policy.md

file README.md

file build_info.h: #include <string>

#include <string_view>

Runtime information about how OpenMeta was built.

file byte_arena.h: #include <cstddef>

#include <cstdint>

#include 

#include <string_view>

#include <vector>

Append-only byte arena used to store metadata payloads and strings.

file ccm_query.h: #include “openmeta/meta_store.h”

#include <cstdint>

#include <string>

#include <vector>

Query helpers for normalized DNG/RAW color matrix metadata.

file compatibility_dump.h

#include “openmeta/interop_export.h”

#include “openmeta/metadata_transfer.h”

#include <cstdint>

#include <string>

Deterministic text dumps for host compatibility tests.

API Stability: Stable host-facing v1 dump contract.

file console_format.h: #include <cstddef>

#include <cstdint>

#include 

#include <string>

#include <string_view>

file container_payload.h: #include “openmeta/container_scan.h”

#include <cstddef>

#include <cstdint>

#include 

Reassembles and optionally decompresses logical metadata payloads.

file container_scan.h: #include <cstddef>

#include <cstdint>

#include 

Container scanners that locate metadata blocks within file bytes.

file dng_sdk_adapter.h: #include “openmeta/metadata_transfer.h”

#include <cstdint>

#include <string>

Optional Adobe DNG SDK bridge for prepared OpenMeta DNG transfers.

file exif_tag_names.h: #include <cstdint>

#include <string_view>

Human-readable names for common EXIF/TIFF tags.

file exif_tiff_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

#include <string_view>

Decoder for TIFF-IFD tag streams (used by EXIF and TIFF/DNG).

file exif_value_names.h: #include <cstdint>

#include <string_view>

Human-readable names for common EXIF/TIFF/DNG numeric values and selected bounded MakerNote contexts.

file exr_adapter.h: #include “openmeta/exr_decode.h”

#include “openmeta/meta_store.h”

#include “openmeta/metadata_transfer.h”

#include <cstddef>

#include <cstdint>

#include <limits>

#include <string>

#include <vector>

EXR-native attribute bridge for OpenEXR-style host integrations.

file exr_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

Decoder for OpenEXR header attributes.

file geotiff_key_names.h: #include <cstdint>

#include <string_view>

GeoTIFF GeoKey name lookup.

file icc_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

Decoder for ICC profile blobs (header + tag table).

file icc_interpret.h: #include <cstddef>

#include <cstdint>

#include 

#include <string>

#include <string_view>

#include <vector>

Selected ICC tag-name and tag-payload interpretation helpers.

file interop_export.h: #include “openmeta/meta_store.h”

#include <cstdint>

#include <string>

#include <string_view>

Metadata export traversal API for interop adapters.

file iptc_iim_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

Decoder for IPTC-IIM dataset streams.

file jumbf_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

Decoder for JUMBF/C2PA payload blocks.

file libraw_adapter.h: #include “openmeta/mapped_file.h”

#include “openmeta/meta_store.h”

#include “openmeta/simple_meta.h”

#include <cstdint>

Explicit orientation bridge for LibRaw-facing host integrations.

file mapped_file.h: #include <cstddef>

#include <cstdint>

#include 

Read-only file mapping helper.

file meta_edit.h: #include “openmeta/meta_store.h”

#include 

#include <vector>

Batch edit operations for MetaStore (append/set/tombstone).

file meta_flags.h: #include <cstdint>

Flags attached to metadata entries.

file meta_key.h: #include “openmeta/byte_arena.h”

#include <cstdint>

#include <string_view>

Normalized key identifiers for EXIF/IPTC/XMP/etc. metadata entries.

file meta_store.h: #include “openmeta/byte_arena.h”

#include “openmeta/meta_flags.h”

#include “openmeta/meta_key.h”

#include “openmeta/meta_value.h”

#include <cstdint>

#include 

#include <vector>

In-memory representation of decoded metadata (keys/values + provenance).

file meta_value.h: #include “openmeta/byte_arena.h”

#include <cstdint>

#include 

#include <string_view>

Typed metadata value representation (scalar/array/bytes/text).

file metadata_capabilities.h

#include “openmeta/metadata_transfer.h”

#include <cstdint>

Runtime capability query API for host integrations.

API Stability: Stable host-facing v1 query contract.

file metadata_concepts.h: #include “openmeta/meta_store.h”

#include “openmeta/metadata_query.h”

#include <cstdint>

#include <string>

#include <vector>

Experimental cross-family metadata concept resolution.

file metadata_interpretation.h: #include “openmeta/meta_store.h”

#include “openmeta/metadata_query.h”

#include <cstdint>

#include <vector>

Structured metadata interpretation records built from semantic query candidates.

file metadata_query.h: #include “openmeta/meta_key.h”

#include “openmeta/meta_store.h”

#include <cstdint>

#include <string>

#include <vector>

Experimental semantic metadata query helpers.

file metadata_transfer.h

#include “openmeta/meta_store.h”

#include “openmeta/metadata_concepts.h”

#include “openmeta/resource_policy.h”

#include “openmeta/simple_meta.h”

#include “openmeta/vendor_raw_processing.h”

#include “openmeta/xmp_dump.h”

#include <array>

#include <cstddef>

#include <cstdint>

#include <cstring>

#include 

#include <string>

#include <string_view>

#include <vector>

Draft metadata transfer bundle and backend emitter contracts.

This header defines a stable draft contract for “prepare once, emit many” metadata transfer workflows.

file ocio_adapter.h: #include “openmeta/interop_export.h”

#include <cstdint>

#include <string>

#include <vector>

Adapter helpers for OCIO-style metadata trees.

file orientation.h: #include <cstdint>

Helpers for interpreting EXIF/TIFF orientation values.

file phaseone_geometry.h: #include “openmeta/meta_store.h”

#include <cstdint>

Normalized helpers for Phase One/Leaf RAW sensor geometry and processing tags.

file photoshop_irb_decode.h: #include “openmeta/icc_decode.h”

#include “openmeta/iptc_iim_decode.h”

#include “openmeta/meta_store.h”

#include “openmeta/xmp_decode.h”

#include <cstddef>

#include <cstdint>

#include 

#include <string_view>

Decoder for Photoshop Image Resource Blocks (IRB / 8BIM resources).

file preview_extract.h: #include “openmeta/container_scan.h”

#include <cstddef>

#include <cstdint>

#include 

Read-only preview/thumbnail candidate discovery and extraction.

file printim_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

Decoder for the EXIF PrintIM (0xC4A5) embedded block.

file resource_policy.h: #include “openmeta/container_payload.h”

#include “openmeta/exif_tiff_decode.h”

#include “openmeta/exr_decode.h”

#include “openmeta/icc_decode.h”

#include “openmeta/iptc_iim_decode.h”

#include “openmeta/jumbf_decode.h”

#include “openmeta/photoshop_irb_decode.h”

#include “openmeta/preview_extract.h”

#include “openmeta/xmp_decode.h”

#include “openmeta/xmp_dump.h”

#include <cstdint>

Draft resource-budget policy for OpenMeta read/dump workflows.

file simple_meta.h: #include “openmeta/container_payload.h”

#include “openmeta/container_scan.h”

#include “openmeta/exif_tiff_decode.h”

#include “openmeta/exr_decode.h”

#include “openmeta/icc_decode.h”

#include “openmeta/iptc_iim_decode.h”

#include “openmeta/jumbf_decode.h”

#include “openmeta/meta_store.h”

#include “openmeta/photoshop_irb_decode.h”

#include “openmeta/xmp_decode.h”

#include <cstddef>

#include 

High-level “read” helper for scanning containers and decoding metadata.

file validate.h: #include “openmeta/ccm_query.h”

#include “openmeta/jumbf_decode.h”

#include “openmeta/resource_policy.h”

#include “openmeta/simple_meta.h”

#include <cstdint>

#include <string>

#include <vector>

High-level metadata validation API (decode health + DNG/CCM checks).

file vendor_raw_processing.h: #include “openmeta/meta_store.h”

#include <cstdint>

#include <string_view>

Conservative vendor RAW-processing metadata classification helpers.

file xmp_decode.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

Decoder for XMP packets (RDF/XML).

file xmp_dump.h: #include “openmeta/meta_store.h”

#include <cstddef>

#include <cstdint>

#include 

#include <vector>

XMP sidecar generation for a decoded MetaStore.

page API Stability

This page defines the adoption status for public OpenMeta APIs. Python bindings mirror these labels unless a Python wrapper documents a different status.

Stability Levels¶

Level	Meaning
Stable	Intended for downstream use. Breaking changes require a new contract version, a compatibility path, or a documented migration.
Experimental	Public and tested, but the exact shape or semantics may still evolve while the surrounding workflow is being hardened.
Internal	Publicly visible only because it is part of a lower-level implementation surface. Do not build new downstream integrations on it unless another doc names it as supported.

Host-Facing API Map¶

API surface	Header	Stability	Notes
Runtime capability query: `metadata_capability(...)`	`openmeta/metadata_capabilities.h`	Stable	v1 query contract for read, structured decode, transfer preparation, target edit, and raw-preservation status by format/family.
Compatibility dumps: `dump_metadata_compatibility(...)`, `dump_transfer_compatibility(...)`	`openmeta/compatibility_dump.h`	Stable	Stable v1 line-oriented compatibility dump contract. See compatibility_dump.md.
XMP sync and writeback policy enums: `XmpConflictPolicy`, existing-carrier precedence enums, `XmpWritebackMode`, destination carrier modes	`openmeta/xmp_dump.h`, `openmeta/metadata_transfer.h`	Stable	Stable bounded writer policy for generated portable XMP. See xmp_sync_policy.md.
Generic metadata traversal: `visit_metadata(...)`, `MetadataSink`, `ExportOptions`, `ExportItem`	`openmeta/interop_export.h`	Stable	v1 traversal contract. Borrowed names are valid only during `MetadataSink::on_item(...)`.
`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.
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/mode, metering mode, light source, flash, color space, white balance, scene capture type, gain control, CFA layout, and DNG calibration illuminants, plus selected bounded Canon/Nikon MakerNote contexts. 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/color-sampler headers, path-record summaries, descriptor-header summaries, `XMLData` and ImageReady ASCII text resources, legacy halftone/transfer/duotone/EPS byte 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/mode, gain, and raw exposure-adjustment roles across standard EXIF/DNG/XMP evidence and selected decoded vendor/MakerNote exposure names; standard EXIF exposure program/mode and gain-control values, selected Canon MakerNote exposure-mode/flash-metering values, and selected Nikon MakerNote flash/metering/focus/multiple-exposure 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.
Transfer concept diagnostics: `transfer_concept_diagnostics_from_store(...)`, `transfer_concept_diagnostic_message(...)`	`openmeta/metadata_transfer.h`	Experimental	Preflight view over concept candidates for `TransferSafetyMode`. Each diagnostic reports concept kind/role, transfer hint, keep/drop/requires-target-image-spec action, reason token, severity token, default message text, conflict flag, source entries, compatible/rendered safety booleans, and GPS altitude-reference presentation fields. Rendered-transfer drop messages distinguish source color transforms, white balance, lens-correction records, and computational/thermal/stitch source-processing drops from generic source-processing metadata. Intended for UI previews and host policy messages before calling `prepare_metadata_for_target(...)`; it does not replace the actual transfer filter. Python `Document` and `TransferSourceSnapshot` expose `transfer_concept_diagnostics(...)` dictionaries with `severity_name` and `message` fields.
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, pixel-shift/multi-shot/composite/auto-lighting/source-style processing, and FLIR radiometric/raw-value buckets. Long-tail aliases cover source color/style, camera-to-XYZ/RGB matrix, white-balance gain, optical/lens correction, dynamic-range, and raw-development terms. Direct field classification also recognizes decoded Phase One/Leaf RAW-processing tags; use the dedicated Phase One/Leaf helpers for normalized geometry and processing summaries. 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.
Source snapshot type and read helpers: `TransferSourceSnapshot`, `read_transfer_source_snapshot_file(...)`, `read_transfer_source_snapshot_bytes(...)`, `build_transfer_source_snapshot(...)`	`openmeta/metadata_transfer.h`	Experimental	Current snapshots are decoded-store-backed by default. Opt-in raw carriers preserve bounded source payload/provenance records and snapshot-local decoded entry ids for host diagnostics and bounded passthrough decisions. Const reuse is safe when callers do not mutate the snapshot and do not share returned result objects across writers.
Fileless preparation: `prepare_metadata_for_target_snapshot(...)`	`openmeta/metadata_transfer.h`	Experimental	Intended for hosts that already decoded metadata and want to prepare transfer artifacts without reopening the source file. `TransferRawCarrierPassthroughMode::WhenSafe` is an opt-in snapshot mode; the current writer path only reuses eligible non-C2PA JUMBF and draft unsigned C2PA invalidation carriers for JPEG, JXL, and BMFF targets, plus draft unsigned C2PA invalidation carriers for WebP.
Snapshot execution: `execute_prepared_transfer_snapshot(...)`	`openmeta/metadata_transfer.h`	Experimental	Intended for deferred save/writeback from a reusable decoded source snapshot.
Bundle execution: `execute_prepared_transfer_bundle(...)`	`openmeta/metadata_transfer.h`	Experimental	Intended for hosts that already own a prepared bundle and destination bytes. Treat bundles as immutable except through documented patch helpers.
Adapter-view execution: `build_prepared_transfer_adapter_view(...)`, `emit_prepared_transfer_adapter_view(...)`	`openmeta/metadata_transfer.h`	Experimental	Target-neutral operation view for host-owned encoders and writers. Route and dispatch details may still evolve.
Generated transfer payload internals, route strings, low-level package chunks, and diagnostic counters not documented by a stable API page	`openmeta/metadata_transfer.h`	Internal	These fields may be useful for tests and diagnostics, but they are not a compatibility contract for downstream integrations.

Practical Guidance¶

Use stable APIs for normal application integrations. Use experimental APIs when they match a real workflow and the integration can track OpenMeta releases. Avoid internal surfaces unless you are contributing to OpenMeta itself or writing a test that is intentionally tied to implementation details.

page Compatibility Dump Contract

OpenMeta exposes a deterministic text dump for downstream compatibility tests. The goal is to let host projects compare names, value shapes, origins, and transfer decisions without keeping binary metadata packet baselines.

Contract constant:

openmeta::kCompatibilityDumpContractVersion == 1

Python exposes the same version as:

openmeta.COMPATIBILITY_DUMP_CONTRACT_VERSION == 1

Metadata Dump¶

Use dump_metadata_compatibility(...) for C++:

#include "openmeta/compatibility_dump.h"

openmeta::MetadataCompatibilityDumpOptions options;
options.style = openmeta::ExportNameStyle::FlatHost;

std::string out;
openmeta::dump_metadata_compatibility(store, options, &out);

Python Document and TransferSourceSnapshot expose the same metadata dump:

doc = openmeta.read("source.jpg")
text = doc.compatibility_dump()

The v1 metadata dump is line-oriented ASCII text:

openmeta.compat.metadata version=1 ...
entry index=0 name="Make" key_kind="exif_tag" value_kind="text" ...

Each emitted entry is based on visit_metadata(...), so ordering, duplicate handling, and naming follow the selected ExportNameStyle. By default the dump uses the stable FlatHost contract.

Metadata entry lines include:

exported name
key family
value kind
scalar or array element type
text encoding
count
optional safe value text
optional origin block/order/wire fields
optional per-entry flags

Text and byte values are escaped with the same terminal-safe ASCII rules used by other OpenMeta diagnostic output. Large values are bounded by max_value_bytes.

Transfer Dump¶

Use dump_transfer_compatibility(...) for C++ transfer/writeback decisions:

std::string out;
openmeta::TransferCompatibilityDumpOptions options;
openmeta::dump_transfer_compatibility(result, persisted_or_null, options, &out);

The v1 transfer dump is line-oriented ASCII text:

openmeta.compat.transfer version=1 target_format="png" ...
policy index=0 subject="xmp_iptc_projection" ...
block index=0 kind="xmp" route="png:itxt-xmp" ...
execute edit_requested=true ...
writeback xmp_sidecar_requested=true ...
persist status="ok" ...

Transfer dump lines include:

target format and high-level read/prepare status
prepared policy decisions
prepared block kind, route, order, and payload size
execute/edit status and output sizes
XMP sidecar request, output, and cleanup decisions
optional persisted file/sidecar/cleanup result

The dump intentionally records decisions and sizes, not full binary payloads. This keeps downstream tests stable across equivalent packet serialization changes.

Stability¶

This is a stable v1 contract. Future releases may add fields or lines, but existing v1 field names and meanings should not change without a new contract version or a documented compatibility path.

page Canonical EXR Value Encoding in OpenMeta

Status: baseline contract (v1)

Scope¶

This defines how OpenEXR attribute values should be represented in MetaValue and Origin/WireType so decode/edit/write logic stays deterministic and lossless.

Keying is handled separately by MetaKeyKind::ExrAttribute with:

part_index (EXR part id)
name (attribute name)

Wire Type Contract¶

Origin::wire_type.family = WireFamily::Other
Origin::wire_type.code = exr_attribute_type_t numeric value
Origin::wire_count stores raw attribute byte size (current implementation)

For unknown/user-defined EXR attribute types, preserve:

raw payload bytes in MetaValueKind::Bytes
type string in Origin::wire_type_name (optional decode behavior)

Canonical Mapping Table¶

EXR_ATTR_INT -> Scalar + I32
EXR_ATTR_FLOAT -> Scalar + F32
EXR_ATTR_DOUBLE -> Scalar + F64
EXR_ATTR_RATIONAL -> Scalar + SRational (num, denom)
EXR_ATTR_STRING -> Text + Utf8 (best effort, fallback Unknown)
EXR_ATTR_STRING_VECTOR -> Bytes (current), planned structured helper API for element iteration
EXR_ATTR_V2I/V3I -> Array + I32 (count 2/3)
EXR_ATTR_V2F/V3F -> Array + F32 (count 2/3)
EXR_ATTR_V2D/V3D -> Array + F64 (count 2/3)
EXR_ATTR_M33F -> Array + F32 (count 9, row-major)
EXR_ATTR_M33D -> Array + F64 (count 9, row-major)
EXR_ATTR_M44F -> Array + F32 (count 16, row-major)
EXR_ATTR_M44D -> Array + F64 (count 16, row-major)
EXR_ATTR_BOX2I -> Array + I32 (count 4: min.x,min.y,max.x,max.y)
EXR_ATTR_BOX2F -> Array + F32 (count 4: min.x,min.y,max.x,max.y)
Enum-like attrs (compression, lineorder, envmap, deepImageState) -> Scalar + U8
Struct/blob attrs (chlist, preview, bytes, opaque) -> Bytes for lossless core storage; typed helper decode APIs should be layered on top.
Current decode additionally normalizes:
- EXR_ATTR_TIMECODE -> Array + U32 (2 values)
- EXR_ATTR_KEYCODE -> Array + I32 (7 values)
- EXR_ATTR_TILEDESC -> Array + U8 (9 raw bytes)

Rationale¶

Keep MetaStore compact and storage-agnostic.
Guarantee lossless round-trip for all EXR attributes, including unknown ones.
Avoid hard-coding large per-type structs in core until a stable EXR read/write adapter lands.

Open Questions¶

Whether string_vector should become first-class Array + Text rather than a packed-bytes representation.
Where to attach EXR type_name for unknown/custom attrs without bloating all entries.
Whether chlist should get a dedicated typed view API in v1 or remain bytes in core with helper parsing only.

page Development

See also: docs/metadata_support.md for current container/block/decode support and docs/interpretation_status.md for the semantic interpretation matrix. If you are looking for the shortest practical entry path, start with docs/quick_start.md before this file.

If you already have a host encoder, SDK, or container API, use docs/host_integration.md after the quick start.

OpenMeta Structure¶

OpenMeta’s public architecture is organized around a small set of user-facing capabilities. Internally some of these split into more stages, but the public 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 brand/item-property associations, item semantic counts, and primary item properties, JUMBF labels, Photoshop IRB embedded carriers plus fixed-layout, XML/text, path-record, byte-count, 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%.
Transfer	Move metadata between files using explicit compatible-file or rendered-image safety policies.	Medium-high, about 80-85%.
Translation	Project metadata between families, mainly bounded EXIF/IPTC/XMP portable mappings.	Medium, about 60-70%.
Writing	Serialize metadata and write or rewrite it into target containers.	Medium, about 65-75%.
Adapters	Thin integration layers for host APIs or format-specific ecosystems such as EXR, DNG SDK, LibRaw orientation mapping, and flat host exports.	Medium, about 60-70%.
Utilities	Small standalone helpers such as capability queries, compatibility dumps, safety audits, tag-name lookup, and orientation conversion.	Medium, about 65-75%.

Query results should expose both inspection-level matches and interpreted candidates. A crop query, for example, may match separate DefaultCropOrigin and DefaultCropSize tags, an ActiveArea rectangle, vendor margin fields, or a raw integer array. OpenMeta should return the source entries, confidence, value shape, match provenance, and any normalized interpretation rather than hiding ambiguity behind a single value.

The first experimental C++ query surface is openmeta/metadata_query.h. It returns both raw matches and normalized candidates for crop/active-area, exposure/gain, white balance, color/profile, lens correction, orientation, descriptive, and RAW-processing queries. Crop queries include DNG crop tags, ActiveArea, Phase One/Leaf raw geometry, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Nikon Capture crop bounds, Sony panorama crop margins, 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, 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. Color queries expose a distinct color_profile semantic for EXIF color-space evidence, ICC header/tag entries, XMP ICC/profile/color-space fields, and PNG profile text carriers. Vendor-classified MakerNote/RAW fields can also form per-family grouped candidates for white balance, color, raw-storage, sensor, computational, thermal, stitch/panorama, and source-processing records. RAW-processing queries add conservative groups for black/white levels, linearization tables, CFA/sensor layout, source geometry, raw-storage identifiers, and source-private processing buckets. Exposure/gain concept resolution promotes exposure time, aperture, ISO, exposure bias, exposure program/mode, gain, and raw exposure-adjustment records into host-visible roles, with raw exposure adjustments kept unsafe for rendered targets. Standard EXIF exposure program/mode and gain-control values and selected Canon/Nikon MakerNote exposure-adjacent print conversions are exposed as bounded labels when a stable enum mapping is available. Current source-private aliases include camera-to-XYZ/RGB matrices, creative and picture styles, film simulation, dynamic-range processing, optical/lens correction, white-balance gains, and raw-development terms. Grouped candidates use matrix_set, vector_set, and table value shapes. Color matrix sets, white-balance vector sets, and lens-correction tables are promoted only when the numeric payloads meet conservative minimum shapes; other records stay visible as per-entry matches/candidates. 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, fuzzy_match, and fuzzy_score so UI code can distinguish exact tag/name 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, exposure/gain, color/profile, GPS, geometry, lens-correction, and RAW-processing 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, normalized exposure values, full normalized value vectors for grouped matrix/vector/table records, transfer hints, compatible and rendered safety booleans, 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
A C++20 compiler (Clang is recommended; fuzzing requires Clang)
Optional: Ninja (-G Ninja)

OpenMeta discovers optional dependencies via find_package(...). If you install deps into a custom prefix, pass it via CMAKE_PREFIX_PATH (example: -DCMAKE_PREFIX_PATH=/mnt/f/UBSd).

Optional Dependencies (Why They Exist)¶

OpenMeta’s core scanning and EXIF/TIFF decoding do not require third-party libraries. Some metadata payloads are compressed or structured; these optional dependencies let OpenMeta decode more content:

Expat (OPENMETA_WITH_EXPAT): parses XMP RDF/XML packets (embedded blocks and .xmp sidecars). Expat is used as a streaming parser so OpenMeta can enforce strict limits and avoid building a full XML DOM from untrusted input.
RapidFuzz (OPENMETA_ENABLE_RAPIDFUZZ): opt-in semantic-query name matching for inspection/search UI. It is disabled by default; when enabled, CMake requires either a rapidfuzz::rapidfuzz package target or OPENMETA_RAPIDFUZZ_INCLUDE_DIR pointing at headers containing rapidfuzz/fuzz.hpp.
zlib (OPENMETA_WITH_ZLIB): inflates Deflate-compressed payloads, including PNG iCCP (ICC profiles) and compressed text/XMP chunks (iTXt, zTXt).
Brotli (OPENMETA_WITH_BROTLI): decompresses JPEG XL brob
”compressed

metadata” boxes so wrapped metadata payloads can be decoded.
Draft C2PA verify scaffold (OPENMETA_ENABLE_C2PA_VERIFY, OPENMETA_C2PA_VERIFY_BACKEND): enables backend selection/reporting fields (none|auto|native|openssl) and draft verification flow. Native backend availability is platform-based (Windows/macOS), while OpenSSL availability is discovered via find_package(OpenSSL) when needed. By default this reports cryptographic signature status and trust-chain detail separately; use --c2pa-verify-require-trusted-chain when validation must fail for an untrusted or missing certificate chain.

If you link against dependencies that were built with libc++ (common when using Clang), configure OpenMeta with:

-DOPENMETA_USE_LIBCXX=ON

When CTest launches external validation tools from the same dependency prefix, those tools must also be able to find their matching C++ runtime libraries. If the runtime is not discoverable through the system loader, pass an explicit runtime directory:

-DOPENMETA_TEST_RUNTIME_LIBRARY_PATH=/path/to/runtime-libs

Versioning¶

VERSION is the single source of truth for the project version:

CMake reads VERSION and sets PROJECT_VERSION.
The Python wheel version is derived from VERSION (via scikit-build-core metadata).

CLI Tools¶

metavalidate checks decode-status health and DNG/CCM validation:

#Basic validation
./build/metavalidate input.dng

#Strict mode : warnings fail the file
./build/metavalidate --strict input.dng

#Machine - readable JSON output
./build/metavalidate --json input.dng

#Validate with sidecar + MakerNotes + C2PA verify status
./build/metavalidate --xmp-sidecar --makernotes --c2pa-verify input.jpg

#Require C2PA signature verification and a trusted certificate chain
./build/metavalidate --c2pa-verify --c2pa-verify-require-trusted-chain input.jpg

metavalidate CLI is a thin wrapper over openmeta::validate_file(...). Machine-readable JSON output includes issue codes suitable for gating, for example xmp/output_truncated and xmp/invalid_or_malformed_xml_text.

metadump is the general dump/save tool:

#Lossless sidecar
./build/metadump --format lossless input.jpg output.xmp

#Portable sidecar
./build/metadump --format portable --portable-include-existing-xmp input.jpg output.xmp

#Portable sidecar with ExifTool GPS time alias compatibility
./build/metadump --format portable --portable-exiftool-gpsdatetime-alias input.jpg output.xmp

#Portable sidecar + draft C2PA verify scaffold status reporting
./build/metadump --format portable --c2pa-verify --c2pa-verify-backend auto input.jpg output.xmp

#Portable sidecar with trusted-chain C2PA verification required
./build/metadump --format portable --c2pa-verify --c2pa-verify-require-trusted-chain input.jpg output.xmp

#Explicit input / output form
./build/metadump -i input.jpg -o output.xmp

#Extract first embedded preview
./build/metadump --extract-preview --first-only input.jpg preview.jpg

#If multiple previews exist, --out gets auto - suffixed:
#preview_1.jpg, preview_2.jpg, ...
./build/metadump --extract-preview input.arq preview.jpg

Portable sidecar note:

exif:GPSTimeStamp is emitted as XMP date-time text (YYYY-MM-DDThh:mm:ssZ) only when GPSDateStamp is available; otherwise it is skipped.
Compatibility mode --portable-exiftool-gpsdatetime-alias emits exif:GPSDateTime instead of exif:GPSTimeStamp.
Portable IPTC-IIM mapping covers dc:* plus selected photoshop:* and Iptc4xmpCore:* fields (for example city/state/country/headline/credit and location/country-code).

metatransfer is a transfer smoke tool for JPEG/TIFF packaging:

#read -> prepare -> emit simulation
./build/metatransfer input.jpg

#Portable vs lossless transfer-prepared XMP block
./build/metatransfer --format portable input.jpg
./build/metatransfer --format lossless input.jpg

#Write prepared payload bytes for inspection
./build/metatransfer --unsafe-write-payloads --out-dir payloads input.jpg

#Prepare once, emit many times (same bundle)
./build/metatransfer --emit-repeat 100 input.jpg

#Patch prepared EXIF time fields before emit
./build/metatransfer --time-patch DateTimeOriginal="2026:03:06 12:34:56" input.jpg

#Select explicit transfer policy for raw-sensitive families
./build/metatransfer --makernote-policy keep --jumbf-policy drop --c2pa-policy drop input.jpg

#Emit a draft unsigned C2PA invalidation payload for JPEG output
./build/metatransfer --no-exif --no-xmp --no-icc --no-iptc \
  --c2pa-policy invalidate input_with_c2pa.jpg

#Append one logical raw JUMBF payload into a prepared JPEG bundle
./build/metatransfer --no-exif --no-xmp --no-icc --no-iptc \
  --jpeg-jumbf payload.jumbf input.jpg

#Stage externally signed logical C2PA into a JPEG rewrite flow
./build/metatransfer --no-exif --no-xmp --no-icc --no-iptc \
  --jpeg-c2pa-signed signed_c2pa.jumb \
  --c2pa-manifest-output manifest.bin \
  --c2pa-certificate-chain chain.bin \
  --c2pa-key-ref signer-key \
  --c2pa-signing-time 2026-03-09T00:00:00Z \
  -o output.jpg input_with_c2pa.jpg

#Persist the semantic transfer payload batch for cross-process handoff
./build/metatransfer --dump-transfer-payload-batch payloads.omtpld input.jpg

#Load and inspect one persisted semantic transfer payload batch
./build/metatransfer --load-transfer-payload-batch payloads.omtpld

#Persist one final transfer package batch
./build/metatransfer --dump-transfer-package-batch package.omtpkg input.jpg

#Load and inspect one persisted final transfer package batch
./build/metatransfer --load-transfer-package-batch package.omtpkg

#Plan edit strategy without writing output
./build/metatransfer --mode auto --dry-run input.jpg

#Write edited JPEG output (metadata rewrite mode)
./build/metatransfer --mode metadata_rewrite -o output.jpg input.jpg

#Use separate metadata source and JPEG target stream
./build/metatransfer \
  --source-meta source.tif \
  --target-jpeg target.jpg \
  --mode metadata_rewrite \
  -o injected.jpg

#Use separate metadata source and TIFF target stream
./build/metatransfer \
  --source-meta source.jpg \
  --target-tiff target.tif \
  -o injected.tif

#Inject target-owned image facts when source and output pixels differ
./build/metatransfer \
  --target-jpeg target.jpg \
  --target-width 320 --target-height 240 \
  --target-samples-per-pixel 3 --target-bits-per-sample 8 \
  --target-photometric 2 --target-exif-color-space 1 \
  -o injected.jpg source.jpg

metatransfer is a thin CLI wrapper over the public transfer APIs. It uses prepare_metadata_for_target_file(...) for source read/decode plus execute_prepared_transfer(...) for time patching, route compile/emit, and optional JPEG/TIFF edit plan/apply. When --jpeg-jumbf is used, the CLI also calls append_prepared_bundle_jpeg_jumbf(...) before execute. The core also exposes compile_prepared_transfer_execution(...) plus execute_prepared_transfer_compiled(...) for prepare once -> compile once -> patch/emit many workflows. When -o is used, the CLI passes a TransferByteWriter sink into the shared execution path so edited output can stream directly to disk instead of always materializing a full output buffer. The --target-width, --target-height, --target-orientation, --target-samples-per-pixel, --target-bits-per-sample, --target-sample-format, --target-photometric, --target-planar-configuration, --target-compression, and --target-exif-color-space flags populate PrepareTransferRequest::target_image_spec. Current v1 behavior is:

JPEG edit output is streamed directly from the shared core path.
JPEG metadata-only emit can also stream marker bytes directly through the shared core API.
- TIFF edit output uses the same sink API and only buffers the appended metadata tail; it no longer materializes a second full-file output buffer.
- JPEG XL prepare/emit now shares the same transfer contract for backend emitter use:
 - prepare_metadata_for_target(..., TransferTargetFormat::Jxl, ...) currently builds Exif, xml, and bounded jumb box payloads plus the encoder ICC profile from MetaStore
 - compile_prepared_bundle_jxl(...) and emit_prepared_bundle_jxl_compiled(...) provide the same prepare once -> compile once -> emit many shape as JPEG/TIFF
 - execute_prepared_transfer(...) and emit_prepared_transfer_compiled(..., JxlTransferEmitter&) now accept JXL bundles
 - jxl:icc-profile is emitted through JxlTransferEmitter::set_icc_profile(...) and stays separate from the JXL box path
 - file-based prepare can preserve source generic JUMBF payloads and raw OpenMeta draft C2PA invalidation payloads as JXL boxes
 - store-only prepare can project decoded non-C2PA JumbfCborKey roots into generic JXL jumb boxes when no raw source payload is available
 - IPTC requested for JXL is projected into the existing xml XMP box; OpenMeta does not create a raw IPTC-IIM JXL carrier
 - build_prepared_jxl_encoder_handoff_view(...) is the explicit encoder-side ICC handoff contract for JXL, and build_prepared_jxl_encoder_handoff(...) / serialize_prepared_jxl_encoder_handoff(...) add an owned persisted handoff object for cross-process reuse: at most one prepared jxl:icc-profile payload plus the remaining JXL box counts
 - inspect_prepared_transfer_artifact(...) is now the shared inspect entry point across persisted transfer artifacts: payload batches, package batches, persisted C2PA handoff/signed packages, and persisted JXL encoder handoffs
 - the JXL compile/emit path now rejects multiple prepared ICC profiles so the encoder handoff and backend execution contracts match
 - build_prepared_transfer_emit_package(...) plus write_prepared_transfer_package(...) can serialize direct JXL box bytes from prepared bundles, and build_prepared_transfer_package_batch(...) can materialize those bytes into one owned replay batch
 - bounded JXL file edit now uses the same package layer: it preserves the signature and non-managed top-level boxes, replaces only the metadata families present in the prepared bundle, and appends the prepared JXL boxes to an existing JXL container file
 - unrelated source JXL metadata boxes are preserved, and uncompressed source jumb boxes are distinguished as generic JUMBF vs C2PA for that replacement decision
 - when Brotli support is available, the same distinction is applied to compressed brob(realtype=jumb) source boxes before deciding whether to preserve or replace them
 - the package writer remains box-only, so it still rejects jxl:icc-profile; ICC remains encoder-only on JXL
 - CLI/Python metatransfer wrappers now expose this bounded edit path through --target-jxl ... --source-meta ... --output ... when the prepared bundle does not require jxl:icc-profile
 - JXL transfer now supports generated draft C2PA invalidation for content-bound source payloads, plus the bounded external-signer path: sign-request derivation, binding-byte materialization, signed-payload validation, staged jxl:box-jumb apply, and bounded file-helper edit execution
- WebP prepare/emit now uses the same bounded transfer contract:
 - prepare_metadata_for_target(..., TransferTargetFormat::Webp, ...) currently builds EXIF, XMP, ICCP, and bounded C2PA RIFF metadata chunks from MetaStore
 - WebP EXIF chunk payloads contain direct TIFF bytes and intentionally omit the JPEG APP1 Exif\0\0 preamble
 - compile_prepared_bundle_webp(...) and emit_prepared_bundle_webp_compiled(...) provide the same prepare once -> compile once -> emit many shape as JPEG/TIFF/JXL
 - execute_prepared_transfer(...) and emit_prepared_transfer_compiled(..., WebpTransferEmitter&) now accept WebP bundles
 - IPTC requested for WebP is projected into the existing XMP chunk; OpenMeta does not create a raw IPTC-IIM WebP carrier
 - draft OpenMeta invalidation payloads and generated invalidation output use the C2PA RIFF chunk path
 - build_prepared_transfer_emit_package(...) plus write_prepared_transfer_package(...) can serialize direct WebP chunk bytes from prepared bundles, and build_prepared_transfer_package_batch(...) can materialize those bytes into one owned replay batch
 - full WebP signed C2PA rewrite remains follow-up work
- ISO-BMFF metadata-item transfer now uses the same bounded contract for HEIF / AVIF / CR3 targets:
 - prepare_metadata_for_target(..., TransferTargetFormat::{Heif,Avif,Cr3}, ...) currently builds bmff:item-exif, bmff:item-xmp, bounded bmff:item-jumb, bounded bmff:item-c2pa, and bmff:property-colr-icc payloads
 - EXIF is prepared as a BMFF item payload with the 4-byte big-endian TIFF-offset prefix plus full Exif\0\0 bytes
 - IPTC requested for BMFF is projected into bmff:item-xmp; OpenMeta does not create a raw IPTC-IIM BMFF carrier
 - ICC requested for BMFF uses the bounded property path: bmff:property-colr-icc carries u32be(‘prof) + <icc-profile>as the payload bytes for acolrproperty, not a BMFF metadata item
 - file-based prepare can preserve source generic JUMBF payloads and raw OpenMeta draft C2PA invalidation payloads as BMFF metadata items
 - store-only prepare can project decoded non-C2PAJumbfCborKeyroots intobmff:item-jumbwhen no raw source payload is available -compile_prepared_bundle_bmff(…), emit_prepared_bundle_bmff(…), emit_prepared_bundle_bmff_compiled(…), and emit_prepared_transfer_compiled(…, BmffTransferEmitter&)provide the reusable item/property-emitter path
 - the shared package-batch persistence/replay layer can own and hand off those stable BMFF item and property payload bytes
 - OpenMeta also supports a bounded BMFF edit path for targets without a foreign top-levelmetabox, or with a prior OpenMeta-authored metadata-onlymetabox from the same bounded contract. It preserves non-metatop-level BMFF boxes and replaces the OpenMeta-authored metadata-onlymetabox with the prepared BMFF items/properties.
 - For targets with a parseable foreign top-levelmetabox, OpenMeta can merge, replace, or strip bounded Exif/XMP/JUMBF/C2PA items by extending iinf,iloc,idat, andirefwithcdscreferences to the primary item. This path requires a single parseableiinf,ilocversion 0/1/2,pitm, and at most oneidat. Inserted item IDs can use the 32-bit item-id space: supportedilocversion 0/1 graphs are upgraded to outputilocversion 2 when needed, and OpenMeta emits wider infe/irefrecords for inserted items that exceed 16 bits. Retained foreign item locations support construction method 0 file offsets and construction method 1idatextents with data reference index 0. Retained construction method 2 item-reference extents are supported when irefilocreferences are parseable by explicit extent index or reference order and referenced items are also retained with supported local locations; missing references, removed referenced items, external data references, and other construction methods fail safely. Bounded ICC transfer removes prior ICCcolr/profandcolr/rICC properties fromiprp/ipco, compacts/remaps existingipma associations, appends the transferredcolr/profproperty, and associates it with the primary item and any retained item that previously referenced a replaced ICC property while preserving the prior essential association bit. Arbitrary BMFF scene/property graph rewrite remains unsupported.
 - CLI/Pythonmetatransferwrappers expose both BMFF summaries and this bounded edit path;—target-heif,—target-avif, and—target-cr3 now accept—source-meta PATHplus—output PATHfor metadata transfer onto an existing BMFF target file
 - the same bounded BMFF edit contract now also participates in the core / file-helper C2PA signer path: build_prepared_c2pa_sign_request(…), build_prepared_c2pa_sign_request_binding(…), validate_prepared_c2pa_sign_result(…), and apply_prepared_c2pa_sign_result(…)can reconstruct rewrite binding from preserved source ranges plus one prepared metadata-onlymetabox and can stage validated signed logical C2PA back asbmff:item-c2pa before bounded BMFF edit
 - CLI/Python signer-input options now support JPEG, JXL, and bounded BMFF targets; the legacy option name—jpeg-c2pa-signedis kept for compatibility even when the target is JXL or BMFF -TransferProfilenow uses explicitTransferPolicyActionvalues for makernote,jumbf, andc2pa. -PreparedTransferBundle::policy_decisionsrecords the resolved per-family transfer decision during prepare.
- CLI and Python transfer probes now expose those resolved policy decisions directly, and JPEG edit plans report how many existing APP11 JUMBF/C2PA segments will be removed during rewrite.
- C2PA decisions now expose three explicit fields: -TransferC2paMode -TransferC2paSourceKind -TransferC2paPreparedOutput so callers can tell whether prepare saw decoded-only C2PA, content-bound raw C2PA, or a raw draft invalidation payload, and whether the prepared output was dropped, preserved raw, or generated as a draft invalidation. -PreparedTransferBundle::c2pa_rewriteis the future-facing signer contract forc2pa=rewrite.

Resource Budgets (Draft)¶

Code Organization (EXIF + MakerNotes)¶

Tests (GoogleTest)¶

libFuzzer Targets¶

Corpus runs (seed corpora)¶

FuzzTest¶

Python (nanobind)¶

Python Wheel¶

Interop Surfaces¶

Doxygen (Optional)¶

Sphinx Docs (Optional)¶

page Documentation

OpenMeta uses Doxygen for API extraction. For the published site docs, we render Doxygen XML via Sphinx + Breathe.

Requirements¶

doxygen (optional: graphviz for diagrams)
For Sphinx docs: Python packages listed in docs/requirements.txt

Generate API docs (CMake)¶

Enable docs and build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DOPENMETA_BUILD_DOCS=ON
cmake --build build --target openmeta_docs

Output goes to build/docs/doxygen/html/index.html inside the build directory.

When OPENMETA_BUILD_DOCS=ON, docs are also generated during install:

cmake --build build --target install

Generate site docs (Sphinx)¶

Enable Sphinx docs and build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DOPENMETA_BUILD_SPHINX_DOCS=ON
cmake --build build --target openmeta_docs_sphinx

Output goes to build/docs/html/index.html. Doxygen XML goes to build/docs/doxygen/xml/index.xml.

Publish on GitHub Pages¶

The repository includes a GitHub Actions workflow at .github/workflows/docs-pages.yml that builds the Sphinx site and publishes it to GitHub Pages.

Recommended setup:

In the repository settings, set Pages to GitHub Actions as the source. This is a one-time repository setting.
Pull requests build the docs but do not deploy.
Pushes to main and tag pushes build and deploy the site.

The workflow only runs when docs inputs change: docs/**, src/include/**, README.md, SECURITY.md, NOTICE.md, CMakeLists.txt, or the workflow itself.

Generate API docs (manual)¶

From the OpenMeta/ repo root:

doxygen docs/Doxyfile

Output goes to build/docs/doxygen/html/index.html.

What gets documented¶

Markdown: README.md is used as the main page.
Public API: everything under src/include/openmeta/.

If you add new public headers or APIs, prefer documenting at the header or type/function level so the docs stay accurate as code moves.

page FlatHost Mapping Contract

ExportNameStyle::FlatHost is the stable v1 naming contract for host-owned metadata object models that prefer flat attribute names over OpenMeta’s native key shapes.

Contract constant:

openmeta::kFlatHostExportContractVersion == 1

Scope¶

The contract covers names emitted by:

openmeta::visit_metadata(store, options, sink)

with:

options.style = openmeta::ExportNameStyle::FlatHost;

Python mirrors this name contract through:

doc.export_names(style=openmeta.ExportNameStyle.FlatHost)

The C++ traversal exposes ExportItem::entry, so C++ hosts can project values from the original Entry::value. Python export_names(...) is name-only.

Ordering And Duplicates¶

Entries are emitted in MetaStore::entries() order.
Deleted entries are skipped.
Duplicate names are preserved and emitted separately.
OpenMeta does not merge, reconcile, or suffix duplicate FlatHost names.
If a host requires unique keys, it must apply its own deterministic collision policy after traversal.

Value Projection¶

FlatHost is a naming contract, not a value-conversion contract.

C++ receives the original Entry through ExportItem::entry.
Entry::value.kind, elem_type, count, and storage are unchanged.
Text encoding remains the original decoded TextEncoding.
Byte payloads remain byte payloads; unsafe text conversion is not performed by visit_metadata(...).
Hosts that need a text-only export should use a safe formatting layer on top of Entry::value.

Namespace Behavior¶

FlatHost intentionally keeps common camera-style names short while preserving namespace prefixes where ambiguity matters.

Source family	FlatHost rule
TIFF root and preview IFD tags	Use the known tag alias without a prefix, for example `Make`, `ModifyDate`, `ImageWidth`.
EXIF and interoperability IFD tags	Prefix with `Exif:`, for example `Exif:ExposureTime`, `Exif:ISO`, `Exif:CreateDate`.
GPS IFD tags	Prefix with `GPS:`, for example `GPS:GPSLatitude`.
MakerNote IFDs	Emit only when `include_makernotes` is true, using `MakerNote:<ifd>:<tag-name-or-hex>`.
XMP simple properties	Emit selected known namespaces as `XMP:`, `TIFF:`, `Exif:`, or `DC:` plus the simple property name.
ICC header fields and tags	Emit `ICC:<field>` or `ICC:tag:<signature>`.
EXR part 0 known aliases	Map selected standard attributes to common host names, for example `owner -> Copyright`, `capDate -> DateTime`, `expTime -> ExposureTime`.
EXR part 0 unknown attributes	Emit `openexr:<name>`.
EXR non-zero parts	Emit `openexr:part:<index>:<name>`.
Unsupported key families	Fall back to the canonical OpenMeta name when one exists.

Complex XMP paths are not flattened. XMP properties are emitted only when the property path is a simple token containing letters, digits, _, or -; paths with /, [, ], or other punctuation are skipped by FlatHost.

Name Policy¶

ExportOptions::name_policy controls tag aliasing:

ExportNamePolicy::ExifToolAlias is the default and uses OpenMeta’s ExifTool-compatible aliases where OpenMeta has a clean-room mapping.
ExportNamePolicy::Spec preserves native/spec-style tag names where available and uses Tag_0x.... for unknown EXIF tags.

The policy does not change ordering, duplicate preservation, or value projection.

Filtering¶

FlatHost skips:

deleted entries
EXIF pointer tags under the default alias policy
embedded metadata blob tags such as EXIF-stored XMP, ICC, IPTC, Photoshop IRB, and MakerNote blob tags under the default alias policy
MakerNote IFDs when include_makernotes is false
complex XMP paths and unknown XMP namespaces
selected structural EXR header attributes that are not useful as host metadata attributes, such as channels, compression, and data windows

Stability¶

This is a stable v1 naming contract. Future OpenMeta releases may add mappings for newly decoded metadata families, but existing v1 names should not change without a new contract version or a documented compatibility path.

page Host Integration

This guide is for applications that already own the image/container side and want OpenMeta to handle metadata.

OpenMeta is not an image encoder. The usual pattern is:

decode metadata from one source file
query or edit it in MetaStore
hand prepared metadata to your own writer, encoder, or SDK

If you want the shortest end-to-end examples first, start with quick_start.md. For public API adoption status, see api_stability.md. For the stable flat host naming contract, see flat_host_mapping.md. For deterministic host compatibility baselines, see compatibility_dump.md. For generated XMP merge and writeback precedence, see xmp_sync_policy.md. For per-target writer preserve/replace guarantees, see writer_target_contract.md.

Pick The Integration Path¶

Use the narrowest public API that matches your host:

Host owns	Use
Existing target file or template	`execute_prepared_transfer_file(...)` + `persist_prepared_transfer_file_result(...)`
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 and selected MakerNote 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`

For inspection/search UI, prefer the experimental semantic query helpers before 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, exposure/gain, color/profile, GPS, geometry, lens-correction, and RAW-processing candidates with source families, preferred entries, and same-role conflict flags. Exposure candidates expose capture facts such as exposure time, aperture, ISO, exposure bias, exposure program, and gain as safe transfer facts, while raw/DNG exposure adjustment fields remain unsafe for rendered-image transfer. Geometry candidates expose crop, active-area, border, and sensor-geometry roles with canonical origin, size, rect, and margin fields when available, including known DNG, Phase One/Leaf, Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns. Color/white balance, lens-correction, and RAW-processing candidates expose full normalized value vectors for grouped matrix/vector/table records when the source payloads satisfy conservative numeric shape checks. Malformed or text-only source records remain visible as individual metadata, but they are not promoted into normalized grouped color, white-balance, or lens-correction candidates. 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; use metadata_concept_gps_altitude_reference_name(...) for a stable display token. 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. 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 previews, transfer_concept_diagnostics_from_store(...) converts those hints into keep/drop/requires-target-image-spec actions for a selected TransferSafetyMode, plus stable severity tokens and default message text for host UI. Rendered-transfer drop messages distinguish source color transforms, white balance, lens correction, source-bound RAW processing, and target-owned image properties. Hosts can localize or replace the wording, but they do not need to invent the basic safe/drop/rewrite reasons.

Adapter Classes¶

OpenMeta splits host integration surfaces deliberately:

export-only naming/traversal surface: visit_metadata(...) for host-owned metadata mapping layers
export-only adapter: build_ocio_metadata_tree(...) for OCIO-style metadata trees
host-apply adapter: build_exr_attribute_batch(...) for EXR/OpenEXR header workflows
direct bridge: dng_sdk_adapter.h for applications that already use Adobe DNG SDK objects
narrow translator: libraw_adapter.h for orientation mapping into LibRaw flip space
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 and selected bounded Canon/Nikon MakerNote 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, exposure/gain, GPS, geometry, lens-correction, and RAW-processing conflict inspection

1. Read Into <tt>MetaStore</tt>¶

#include "openmeta/simple_meta.h"

#include <array>
#include <cstddef>
#include <span>
#include <vector>

std::vector<std::byte> file_bytes = load_file_somehow("input.jpg");

openmeta::MetaStore store;
std::array<openmeta::ContainerBlockRef, 256> blocks {};
std::array<openmeta::ExifIfdRef, 512> ifds {};
std::vector<std::byte> payload(1 << 20);
std::array<uint32_t, 1024> payload_indices {};

openmeta::SimpleMetaDecodeOptions options;
openmeta::SimpleMetaResult result = openmeta::simple_meta_read(
    std::span<const std::byte>(file_bytes.data(), file_bytes.size()),
    store,
    blocks,
    ifds,
    payload,
    payload_indices,
    options);

store.finalize();

The caller owns the scratch buffers. That is deliberate: the API stays deterministic and easy to reuse in hot paths.

2. Query By Exact Key¶

#include "openmeta/meta_key.h"

openmeta::MetaKeyView key;
key.kind = openmeta::MetaKeyKind::ExifTag;
key.data.exif_tag.ifd = "ifd0";
key.data.exif_tag.tag = 0x010F;  // Make

for (openmeta::EntryId id : store.find_all(key)) {
    const openmeta::Entry& entry = store.entry(id);
    // Inspect entry.value and entry.origin.
}

Use exact lookup for deterministic key access. For inspection/search UI, prefer openmeta/metadata_query.h before building a separate layer. It returns source entries, confidence, value shape, and normalized candidates. The default matcher uses built-in tags and conservative substring/name rules; builds configured with -DOPENMETA_ENABLE_RAPIDFUZZ=ON add RapidFuzz-backed near-miss XMP/path matching. Raw matches include exact_match, fuzzy_match, and fuzzy_score fields; metadata_query_fuzzy_search_available() reports whether the stronger matcher is compiled in.

3. Generic Host Metadata Traversal¶

Use the traversal API when your application owns the metadata object model and needs deterministic exported names plus the original Entry.

#include "openmeta/interop_export.h"

class MyMetadataSink final : public openmeta::MetadataSink {
public:
    void on_item(const openmeta::ExportItem& item) noexcept override
    {
        // Map item.name + item.entry into your host metadata object.
    }
};

openmeta::ExportOptions options;
options.style              = openmeta::ExportNameStyle::FlatHost;
options.name_policy        = openmeta::ExportNamePolicy::ExifToolAlias;
options.include_makernotes = true;

MyMetadataSink sink;
openmeta::visit_metadata(store, options, sink);

This keeps host-specific object ownership and write behavior outside OpenMeta.

4. Build An EXR Attribute Batch¶

This is the cleanest host-adapter path in OpenMeta today.

#include "openmeta/exr_adapter.h"

openmeta::ExrAdapterBatch batch;
openmeta::BuildExrAttributeBatchFileOptions options;

openmeta::BuildExrAttributeBatchFileResult result =
    openmeta::build_exr_attribute_batch_from_file(
        "source.jpg", &batch, options);

for (const openmeta::ExrAdapterAttribute& attr : batch.attributes) {
    // Forward attr.name, attr.type_name, and attr.value to your EXR writer.
}

OpenMeta does not need OpenEXR headers for this path. It exports a neutral batch of EXR-style attributes that your host can apply through OpenEXR or its own EXR writer.

5. Feed A Host-Owned JPEG Or JXL Encoder¶

There are two public patterns for encoder-owned output:

implement a backend emitter such as JpegTransferEmitter or JxlTransferEmitter
build an adapter view and consume one normalized list of operations

Adapter-View Pattern¶

Use this when you want one target-neutral operation list.

#include "openmeta/metadata_transfer.h"

class MySink final : public openmeta::TransferAdapterSink {
public:
    openmeta::TransferStatus
    emit_op(const openmeta::PreparedTransferAdapterOp& op,
            std::span<const std::byte> payload) noexcept override
    {
        // Dispatch on op.kind and forward payload into your backend.
        return openmeta::TransferStatus::Ok;
    }
};

openmeta::PrepareTransferFileOptions prepare;
prepare.prepare.target_format = openmeta::TransferTargetFormat::Jxl;

openmeta::PrepareTransferFileResult prepared =
    openmeta::prepare_metadata_for_target_file("source.jpg", prepare);

openmeta::PreparedTransferAdapterView view;
openmeta::build_prepared_transfer_adapter_view(
    prepared.bundle, &view, openmeta::EmitTransferOptions {});

MySink sink;
openmeta::emit_prepared_transfer_adapter_view(prepared.bundle, view, sink);

This is a good fit when your host already has its own abstraction for “metadata op + bytes”.

Backend-Emitter Pattern¶

Use this when your host already looks like one OpenMeta backend.

#include "openmeta/metadata_transfer.h"

class MyJpegEmitter final : public openmeta::JpegTransferEmitter {
public:
    openmeta::TransferStatus
    write_app_marker(uint8_t marker_code,
                     std::span<const std::byte> payload) noexcept override
    {
        // Write one APPn marker into your JPEG output path.
        return openmeta::TransferStatus::Ok;
    }
};

openmeta::PrepareTransferFileOptions prepare;
prepare.prepare.target_format = openmeta::TransferTargetFormat::Jpeg;

openmeta::PrepareTransferFileResult prepared =
    openmeta::prepare_metadata_for_target_file("source.jpg", prepare);

openmeta::PreparedTransferExecutionPlan plan;
openmeta::compile_prepared_transfer_execution(
    prepared.bundle, openmeta::EmitTransferOptions {}, &plan);

MyJpegEmitter emitter;
openmeta::emit_prepared_transfer_compiled(prepared.bundle, plan, emitter);

For JXL, implement JxlTransferEmitter::set_icc_profile(...), add_box(...), and close_boxes(...).

OpenMeta does not ship a TurboJPEG-specific wrapper yet. The intended integration path is still through JpegTransferEmitter or the adapter view.

6. Edit An Existing Target File¶

If your host already has a target file or template on disk, use the file helper instead of building your own writer path.

#include "openmeta/metadata_transfer.h"

openmeta::ExecutePreparedTransferFileOptions exec_options;
exec_options.prepare.prepare.target_format =
    openmeta::TransferTargetFormat::Tiff;
exec_options.edit_target_path = "rendered.tif";

openmeta::ExecutePreparedTransferFileResult exec =
    openmeta::execute_prepared_transfer_file("source.jpg", exec_options);

openmeta::PersistPreparedTransferFileOptions persist;
persist.output_path = "rendered_with_meta.tif";
persist.overwrite_output = true;

openmeta::PersistPreparedTransferFileResult saved =
    openmeta::persist_prepared_transfer_file_result(exec, persist);

This path is usually simpler than a custom adapter when the container already exists.

Read Once, Save Later¶

If your host already decoded source metadata during the initial load, keep a decoded source snapshot and execute the later save without reopening the source file:

#include "openmeta/metadata_transfer.h"

const openmeta::ReadTransferSourceSnapshotFileResult snapshot =
    openmeta::read_transfer_source_snapshot_file("source.jpg");

openmeta::ExecutePreparedTransferSnapshotOptions options;
options.prepare.target_format = openmeta::TransferTargetFormat::Tiff;
options.edit_target_path      = "target.tif";
options.execute.edit_apply    = true;

openmeta::ExecutePreparedTransferFileResult result =
    openmeta::execute_prepared_transfer_snapshot(
        snapshot.snapshot, options);

Python mirrors that same host-facing snapshot flow:

from pathlib import Path

import openmeta

snapshot_info = openmeta.read_transfer_source_snapshot_file("source.jpg")
snapshot = snapshot_info["snapshot"]

result = openmeta.transfer_snapshot_file(
    snapshot,
    target_format=openmeta.TransferTargetFormat.Tiff,
    edit_target_path="target.tif",
    target_bytes=Path("target.tif").read_bytes(),
    output_path="edited.tif",
)

Current source snapshots are decoded-store-backed by default. They are intended for the normal EXIF/XMP/ICC/IPTC transfer flow, where OpenMeta re-emits decoded metadata after applying the selected safety policy. If a host needs source carrier provenance for diagnostics or a later passthrough policy decision, enable ReadTransferSourceSnapshotFileOptions::preserve_raw_carriers or pass ReadTransferSourceSnapshotBytesOptions with preserve_raw_carriers set. Each raw carrier records its route, semantic kind, payload bytes, and snapshot-local decoded entry ids attributed to that carrier. Call raw_carrier_passthrough_audit_from_snapshot(...) before any host-owned passthrough decision. The audit 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. Python exposes the same check as snapshot.raw_carrier_passthrough_audit(...). Snapshot preparation defaults to decoded re-emission. Hosts that need bounded raw reuse can set PrepareTransferRequest::raw_carrier_passthrough_mode to TransferRawCarrierPassthroughMode::WhenSafe, or pass raw_carrier_passthrough_mode=openmeta.TransferRawCarrierPassthroughMode.WhenSafe to Python snapshot transfer helpers. The current passthrough path is limited to eligible non-C2PA JUMBF and OpenMeta draft unsigned C2PA invalidation carriers for JPEG, JXL, and BMFF targets, plus draft unsigned C2PA invalidation carriers for WebP. EXIF/XMP/ICC/IPTC remain decoded re-emitted. For hosts that still own the bundle/execution split, the lower-level prepare_metadata_for_target_snapshot(...) entry point remains available. If the host already has a decoded MetaStore, build a reusable snapshot with build_transfer_source_snapshot(store). If it already owns the source bytes in memory, use read_transfer_source_snapshot_bytes(bytes) instead of the file-path reader. In Python, a previously decoded Document can be turned into a reusable snapshot through doc.build_transfer_source_snapshot() or openmeta.build_transfer_source_snapshot(doc). If it also owns the destination bytes in memory, call the overload execute_prepared_transfer_snapshot(snapshot, target_bytes, options). If it already holds a prepared bundle, use execute_prepared_transfer_bundle(bundle, target_bytes, options) instead. Snapshot execution supports the same existing-sidecar merge and destination carrier-precedence controls as the file helper; when loading an existing sidecar it defaults to edit_target_path unless xmp_existing_sidecar_base_path is set explicitly. For embedded-only writeback with sidecar cleanup and no filesystem path, set xmp_existing_destination_sidecar_state explicitly so OpenMeta can return a cleanup decision without guessing a sidecar location. Python now exposes those same split path/state controls directly: xmp_existing_sidecar_base_path, xmp_sidecar_base_path, xmp_existing_destination_embedded_path, and xmp_existing_destination_sidecar_state.

The CLI and Python command-line wrapper do not implement their own transfer semantics. They map flags onto the same file-helper contract:

--output is the sidecar base for sidecar and embedded_and_sidecar writeback, so the generated sidecar is output-stem.xmp.
--xmp-writeback sidecar suppresses generated embedded XMP.
--xmp-writeback embedded_and_sidecar writes generated XMP to both the edited output and the generated sidecar.
embedded-only writeback preserves an existing destination sidecar unless --xmp-destination-sidecar strip_existing is selected.
sidecar-only writeback preserves existing destination embedded XMP unless --xmp-destination-embedded strip_existing is selected.
--force maps to the C++ persistence overwrite flags for the primary output and generated sidecar.

7. Query Runtime Capabilities¶

Hosts can ask OpenMeta what the current build supports before wiring format menus, warnings, or integration feature flags.

#include "openmeta/metadata_capabilities.h"

openmeta::MetadataCapability cap = openmeta::metadata_capability(
    openmeta::TransferTargetFormat::Avif,
    openmeta::MetadataCapabilityFamily::Xmp);

if (openmeta::metadata_capability_available(cap.target_edit)) {
    // The current build can edit AVIF XMP within the reported support level.
}

Each operation reports one of unsupported, supported, bounded, or disabled. bounded means the capability exists within OpenMeta’s documented contract, not that it is arbitrary metadata-editor parity. disabled is used for compile-time-disabled support such as XMP decode when XML support is not available.

Python exposes the same query:

cap = openmeta.metadata_capability(
    openmeta.TransferTargetFormat.Avif,
    openmeta.MetadataCapabilityFamily.Xmp,
)
print(cap["target_edit_name"])

8. Use The Optional Adobe DNG SDK Bridge¶

If OpenMeta was built with OPENMETA_WITH_DNG_SDK_ADAPTER=ON, you can use the optional SDK bridge in two ways.

Update An Existing DNG File¶

#include "openmeta/dng_sdk_adapter.h"

openmeta::ApplyDngSdkMetadataFileResult result =
    openmeta::update_dng_sdk_file_from_file("source.jpg", "target.dng");

Apply Onto Existing SDK Objects¶

#include "openmeta/dng_sdk_adapter.h"
#include "openmeta/metadata_transfer.h"

openmeta::PrepareTransferFileOptions prepare;
prepare.prepare.target_format = openmeta::TransferTargetFormat::Dng;

openmeta::PrepareTransferFileResult prepared =
    openmeta::prepare_metadata_for_target_file("source.jpg", prepare);

openmeta::DngSdkAdapterOptions adapter;
openmeta::apply_prepared_dng_sdk_metadata(
    prepared.bundle, host, negative, adapter);

This bridge is for applications that already use the Adobe DNG SDK. OpenMeta still does not encode pixels or invent raw-image structure.

Host-Owned Image Specs¶

If a transfer target is produced from a different image buffer than the source, the host writer owns the target image facts: dimensions, channel count, sample type, compression, orientation, colorspace, ICC profile, and TIFF strip/tile storage. OpenMeta does not infer those values from copied metadata. During prepared transfer it filters source EXIF/XMP image-layout fields so stale source properties are not written into a different output image.

Host code that encodes pixels should keep those fields from the target container or inject values derived from the actual output buffer. Enable source ICC transfer only when the host has verified that the profile matches the target pixel buffer; otherwise preserve or write the target profile.

Use TransferProfile::safety for the broad source/destination relationship:

Mode	Use when	Transfer policy
`CompatibleFile`	Metadata is repackaged or recompressed into a compatible file/pixel representation	Preserve source camera, color, ICC, and camera-specific data except target-owned image-layout fields
`RenderedImage`	Pixels may have changed, especially RAW-to-JPEG/PNG/WebP/JXL/HEIF/AVIF export	Keep general/time/GPS/IPTC/portable XMP; drop source raw color calibration, profile/gain tables, raw digests/storage identifiers, linearization/crop/correction metadata, vendor RAW/source-processing geometry/color/correction/thermal/computational/private/stitch fields, camera raw settings XMP, source ICC, opaque MakerNotes, and non-C2PA JUMBF

See writer_target_contract.md for the detailed per-group transfer matrix.

openmeta::PrepareTransferRequest request;
request.target_format = openmeta::TransferTargetFormat::Jpeg;
request.profile.safety = openmeta::TransferSafetyMode::RenderedImage;

request.target_image_spec.has_dimensions = true;
request.target_image_spec.width = encoded_width;
request.target_image_spec.height = encoded_height;

request.target_image_spec.has_samples_per_pixel = true;
request.target_image_spec.samples_per_pixel = 3;
request.target_image_spec.bits_per_sample_count = 1;
request.target_image_spec.bits_per_sample[0] = 8;
request.target_image_spec.has_photometric_interpretation = true;
request.target_image_spec.photometric_interpretation = 2; // RGB
request.target_image_spec.has_exif_color_space = true;
request.target_image_spec.exif_color_space = 1; // sRGB

Python exposes the same structure as openmeta.TransferTargetImageSpec and the command-line wrappers pass it through without a separate policy layer:

spec = openmeta.TransferTargetImageSpec()
spec.has_dimensions = True
spec.width = encoded_width
spec.height = encoded_height
spec.has_samples_per_pixel = True
spec.samples_per_pixel = 3
spec.bits_per_sample = [8]
spec.has_photometric_interpretation = True
spec.photometric_interpretation = 2
spec.has_exif_color_space = True
spec.exif_color_space = 1

For smoke testing the file-helper path, metatransfer and python -m openmeta.python.metatransfer expose equivalent flags:

metatransfer --target-jpeg target.jpg -o output.jpg \
  --target-width 320 --target-height 240 \
  --target-samples-per-pixel 3 --target-bits-per-sample 8 \
  --target-photometric 2 --target-exif-color-space 1 \
  source.jpg

9. Query Phase One RAW Processing Metadata¶

After decoding MakerNotes, hosts can query Phase One/Leaf RAW processing data without depending on private MakerNote tag layout. The helper reports presence and normalized values for color matrices, WB RGB levels, black level, sensor temperatures, raw-data/storage byte counts, and sensor-calibration summaries. These values are source-RAW processing metadata; do not write them into rendered outputs unless the destination is a compatible RAW-style target.

#include "openmeta/phaseone_geometry.h"

openmeta::PhaseOneRawGeometryResult geometry =
    openmeta::phaseone_raw_geometry_from_store(store);
openmeta::PhaseOneRawProcessingResult raw =
    openmeta::phaseone_raw_processing_from_store(store);

if (raw.status == openmeta::PhaseOneRawProcessingStatus::Ok &&
    raw.info.has_color_matrix1) {
    const double m00 = raw.info.color_matrix1[0];
    (void)m00;
}

Python exposes the same normalized queries on decoded documents and reusable transfer snapshots:

doc = openmeta.read("source.iiq", decode_makernote=True)
geometry = doc.phaseone_raw_geometry()
raw = doc.phaseone_raw_processing()

if (raw["status"] == openmeta.PhaseOneRawProcessingStatus.Ok and
        raw["has_color_matrix1"]):
    m00 = raw["color_matrix1"][0]

The metaread command prints compact phaseone_raw_geometry=... and phaseone_raw_processing=... summaries when those decoded fields are present.

10. Query Vendor RAW Processing Metadata¶

For 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, OpenMeta exposes a conservative grouped summary instead of vendor-specific decoded values. The helper reports whether decoded MakerNote fields look like source RAW color/WB, geometry/storage, lens correction, raw-data, sensor-calibration, computational, thermal, preview/face geometry, stitch/panorama geometry, or vendor-private table metadata. Use it to audit transfer safety decisions and host UI, not as a rendered-output write source. The same classification feeds semantic query and interpretation records as per-family grouped table/vector candidates when multiple related vendor fields are present.

#include "openmeta/vendor_raw_processing.h"

openmeta::VendorRawProcessingSummary sony =
    openmeta::vendor_raw_processing_from_store(
        store, openmeta::VendorRawProcessingFamily::Sony);

if (sony.fields_seen > 0) {
    const uint32_t unsafe_for_rendered = sony.color_fields +
        sony.white_balance_fields + sony.lens_correction_fields;
    (void)unsafe_for_rendered;
}

openmeta::TransferSafetyAudit audit =
    openmeta::transfer_safety_audit_from_store(
        store, openmeta::TransferSafetyMode::RenderedImage);

if (audit.filtered_raw_color_calibration > 0 ||
    audit.filtered_icc_profiles > 0 ||
    audit.filtered_makernotes > 0) {
    // Show the host/user which source-bound metadata will not be transferred.
}

openmeta::TransferConceptDiagnostics diagnostics =
    openmeta::transfer_concept_diagnostics_from_store(
        store, openmeta::TransferSafetyMode::RenderedImage);

for (size_t i = 0U; i < diagnostics.diagnostics.size(); ++i) {
    const openmeta::TransferConceptDiagnostic& item =
        diagnostics.diagnostics[i];
    const char* action =
        openmeta::transfer_concept_diagnostic_action_name(item.action);
    const char* reason =
        openmeta::transfer_concept_diagnostic_reason_name(item.reason);
    const char* severity =
        openmeta::transfer_concept_diagnostic_severity_name(item.severity);
    const char* message =
        openmeta::transfer_concept_diagnostic_message(item);
    (void)action;
    (void)reason;
    (void)severity;
    (void)message;
}

Python uses the same family enum:

summary = doc.vendor_raw_processing(openmeta.VendorRawProcessingFamily.Nikon)
if summary["fields_seen"]:
    print(summary["lens_correction_fields"])

audit = doc.transfer_safety_audit(openmeta.TransferSafetyMode.RenderedImage)
print(audit["filtered_raw_color_calibration"])

diagnostics = doc.transfer_concept_diagnostics(
    openmeta.TransferSafetyMode.RenderedImage
)
for item in diagnostics["diagnostics"]:
    print(
        item["kind_name"],
        item["role_name"],
        item["action_name"],
        item["severity_name"],
        item["message"],
    )

11. Build <tt>MetaStore</tt> Yourself¶

If your application creates metadata directly, build the store first and then reuse the same export and transfer APIs.

#include "openmeta/meta_key.h"
#include "openmeta/meta_store.h"
#include "openmeta/meta_value.h"

openmeta::MetaStore store;
const openmeta::BlockId block = store.add_block(openmeta::BlockInfo {});

openmeta::Entry entry;
entry.key = openmeta::make_exif_tag_key(store.arena(), "ifd0", 0x010F);
entry.value = openmeta::make_text(
    store.arena(), "Vendor", openmeta::TextEncoding::Ascii);
entry.origin.block = block;
entry.origin.order_in_block = 0;

store.add_entry(entry);
store.finalize();

page Interpretation Status

This page tracks how far OpenMeta has moved beyond raw metadata decoding into meaningful interpretation. Interpretation means that decoded entries have stable names, typed values, semantic groups, query shapes, and transfer-safety classification that host applications can use directly.

Current overall status: medium-high, about 90% for the public target scope. This is intentionally lower than decode coverage. Decode parity only proves that metadata carriers and entries are visible; interpretation also requires human-readable meaning and safe cross-format behavior.

100% Acceptance Gates¶

For the declared target scope, an entry counts as covered when it has one explicit outcome:

Gate	Requirement
Decoded	The carrier and entry are visible in `MetaStore`, or the decoder reports an explicit unsupported/limit/malformed reason.
Named	The entry has a stable public name, or it is deliberately exposed as an unknown numeric/private field.
Typed	The raw value shape is preserved as scalar, vector, matrix, table, bytes, text, or opaque blob.
Interpreted	Known enum-like values, orientation states, geometry, exposure/gain, color, white-balance, lens-correction, RAW-processing, and source-private meanings are projected into public helpers or query candidates.
Classified	Source-bound data is classified as portable, target-owned, source RAW-specific, vendor-private, computational, thermal, preview/face/stitch metadata, or opaque/lossless.
Queryable	Host/UI workflows can find the interpreted meaning through focused query helpers with source entries, confidence, value shape, and normalized fields where available.
Structured	Host code can consume query-backed interpretation records without reassembling raw query candidates manually.
Conflict-aware	Duplicated cross-family concepts either have a documented precedence rule or surface enough source information for host conflict handling.

Coverage Matrix¶

Area	Current coverage	Readiness	Main remaining gap
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, and common EXIF/TIFF/DNG numeric value-name helpers are available. Exposure time, aperture, ISO sensitivity, exposure bias, exposure program/mode, gain, and raw exposure-adjustment records now flow into concept candidates.	High, about 92-95%.	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, and keywords/subject are queryable with source-entry provenance.	Medium-high, about 78-86%.	Full MWG-style reconciliation of duplicated EXIF/XMP/IPTC concepts remains 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, selected Canon MakerNote exposure/flash-metering values, and selected Nikon MakerNote flash/metering/focus/multiple-exposure values carry human-readable labels in concept candidates. Capture exposure facts are marked safe, while raw/DNG exposure adjustments are marked unsafe for rendered-image transfer.	Medium-high, about 89-92%.	More vendor MakerNote exposure print conversions and richer per-vendor exposure/gain labels.
Color, white balance, profiles, and matrices	DNG color/calibration/reduction/forward matrix groups, white-balance vector groups, EXIF color-space evidence, ICC header/tag entries, XMP ICC/profile fields, PNG profile text carriers, 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. ICC/profile and color-space records have a distinct `color_profile` semantic role, while camera RAW profile/look/tone-curve/style fields and vendor source color tables have a separate `source_color_transform` role marked unsafe for rendered-image transfer. Matrix/vector groups require numeric payloads with conservative minimum shapes before promotion.	Medium-high, about 85-92%.	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, 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 selected Canon/Nikon print conversions expose bounded human-readable labels for exposure-related UI.	Medium-high, about 85-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, brand-name fields, item-info rows, item type/semantic labels and semantic aggregate counters 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 70-80%.	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 Photoshop 2 info/color-table summaries, resolution/version/print data, print-flag bytes, border/background/effective-BW data, display info, grid/guide info, color sampler headers/records, descriptor-header summaries, path record summaries, alpha names/identifiers, captions, QuickMask info, URL/list data, autosave strings, `XMLData`, ImageReady XML text, thumbnail headers, channel options, clipping-path names, legacy halftone/transfer/duotone/EPS byte summaries, embedded ICC/XMP/EXIF resource byte counts, and embedded IPTC/XMP/ICC payload decode where enabled.	Medium, about 75-84%.	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.

Competitor Position¶

ExifTool remains the practical reference for long-tail tag names, MakerNote tables, and human-readable print conversions. OpenMeta is now close on decode visibility for the current target scope, but interpretation still trails ExifTool in per-model private meanings.

Exiv2 is strong for common EXIF/IPTC/XMP workflows. OpenMeta’s differentiator is the explicit safe-transfer and host-query model: it classifies whether data is portable, target-owned, source RAW-specific, or unsafe to move into rendered outputs.

Next Interpretation Priorities¶

Deepen BMFF/CR3/HEIF/AVIF item graph semantics beyond primary item properties only where hosts can use the result safely.
Expand Photoshop IRB resource-specific interpretation beyond current fixed layouts and embedded metadata carriers.
Deepen transfer diagnostics with optional host localization/formatting hooks for GUI workflows.
Expand GPS policy beyond current coordinate tolerance, altitude-reference display, and EXIF timestamp assembly into broader cross-family reconciliation.
Expand MakerNote meaning depth in vendor order: Nikon, Canon, Sony, Fujifilm, Phase One/Leaf, then remaining active vendors.
Keep transfer-safety classification conservative when interpretation is incomplete.

page Metadata Backend Matrix (Draft)

Date: March 5, 2026

Goal¶

Define one OpenMeta write/transfer contract that can target multiple container backends without per-backend metadata logic duplication.

For the public per-target preserve/replace guarantees, see writer_target_contract.md.

Capability Matrix¶

Backend	Native metadata write primitives	Best use in OpenMeta
libjpeg-turbo	`jpeg_write_marker`, `jpeg_write_m_header`, `jpeg_write_m_byte`, `jpeg_write_icc_profile`	Primary JPEG metadata emitter (APP1/APP2/APP13 direct control)
libtiff	`TIFFSetField`, `TIFFCreateEXIFDirectory`, `TIFFCreateGPSDirectory`, `TIFFWriteCustomDirectory`, `TIFFMergeFieldInfo`	Primary TIFF metadata emitter (native tag and IFD path)
libjxl	`JxlEncoderUseBoxes`, `JxlEncoderAddBox`, `JxlEncoderCloseBoxes`, `JxlEncoderSetICCProfile`	Primary JXL metadata emitter (`Exif`, `xml`, `jumb`, optional `brob`) plus encoder ICC profile
OpenEXR	`Header::insert`, typed attributes, `OpaqueAttribute` for unknown attr types	EXR header attribute path (not EXIF block packaging)

Container-Level Notes¶

JPEG (libjpeg-turbo)¶

Write EXIF as APP1 (Exif\\0\\0 + TIFF payload).
Write XMP as APP1 (\\0 + packet).
Write IPTC/IRB as APP13 (Photoshop 3.0 resource block layout).
Write ICC as APP2 chunk chain (ICC_PROFILE header + sequence index/count).
OpenMeta should own marker ordering policy and payload splitting limits.

TIFF (libtiff)¶

EXIF/GPS should be written as directories and linked from root IFD pointers.
XMP uses TIFFTAG_XMLPACKET (700).
IPTC uses TIFFTAG_RICHTIFFIPTC / TIFFTAG_EP_IPTC_NAA (33723 alias).
Photoshop IRB uses TIFFTAG_PHOTOSHOP (34377).
ICC uses TIFFTAG_ICCPROFILE (34675).
OpenMeta should own EXIF serializer policy before TIFFSetField.
Public OpenMeta fast path is backend-emitter or rewrite/edit based: emit_prepared_transfer_compiled(..., TiffTransferEmitter&) or write_prepared_bundle_tiff_edit(...).
TIFF intentionally does not expose a metadata-only byte-writer emit API.

JXL (libjxl)¶

Metadata requires container boxes enabled.
Add Exif, xml, jumb boxes through JxlEncoderAddBox.
Set ICC through JxlEncoderSetICCProfile; ICC is not a JXL metadata box.
Exif box content must include the 4-byte TIFF header offset prefix.
Optional Brotli-compressed box storage (brob) is backend-controlled.
OpenMeta should prepare box payloads once and reuse in emit path.
Current OpenMeta transfer support on this path is intentionally bounded: EXIF/XMP are prepared and emitted through JxlTransferEmitter, ICC is prepared as jxl:icc-profile and emitted through the encoder ICC path, file-based prepare can preserve source generic JUMBF payloads and raw OpenMeta draft C2PA invalidation payloads as JXL boxes, can generate a draft unsigned invalidation payload for content-bound source C2PA, and store-only prepare can project decoded non-C2PA JumbfCborKey roots into generic JXL jumb boxes. IPTC requested for JXL is projected into the xml XMP box; there is no raw IPTC-IIM JXL route. build_prepared_jxl_encoder_handoff_view(...) is the explicit OpenMeta encoder-side ICC contract for JXL, and build_prepared_jxl_encoder_handoff(...) / serialize_prepared_jxl_encoder_handoff(...) add the owned persisted form of that handoff: one optional jxl:icc-profile payload plus the remaining JXL box counts. The JXL compile/emit path rejects multiple prepared ICC profiles so that handoff contract matches backend execution. inspect_prepared_transfer_artifact(...) is the shared persisted-artifact inspect path across payload batches, package batches, persisted C2PA handoff/signed packages, and persisted JXL encoder handoffs. build_prepared_transfer_emit_package(...) plus write_prepared_transfer_package(...) can also serialize direct JXL box bytes from prepared bundles, and execute_prepared_transfer(...) can use that same box-only serializer through emit_output_writer. OpenMeta also supports a bounded file-level JXL edit path that preserves the signature and non-managed top-level boxes, replaces only the metadata families present in the prepared bundle, and appends the prepared JXL boxes to an existing container file. Unrelated source JXL metadata boxes are preserved, and uncompressed source jumb boxes are distinguished as generic JUMBF vs C2PA for that replacement decision. When Brotli support is available, the same family check also covers compressed brob(realtype=jumb) source boxes. The byte-writer/file-edit path still does not serialize jxl:icc-profile; ICC remains encoder-only. The bounded external-signer path now also supports JXL jumb staging for content-bound C2PA rewrite on top of that edit path; full in-process re-sign remains out of scope.

WebP (RIFF metadata chunks)¶

Metadata is carried as RIFF chunks, not TIFF tags or BMFF boxes.
Standard chunk carriers:
- EXIF
- XMP
- ICCP
- bounded C2PA
The prepared EXIF chunk payload is the TIFF byte stream only. It does not include the JPEG APP1 Exif\0\0 preamble.
OpenMeta now has a bounded WebP transfer path on the core transfer API: prepare_metadata_for_target(..., TransferTargetFormat::Webp, ...), compile_prepared_bundle_webp(...), emit_prepared_bundle_webp(...), emit_prepared_bundle_webp_compiled(...), and emit_prepared_transfer_compiled(..., WebpTransferEmitter&).
IPTC requested for WebP is projected into the existing XMP chunk; OpenMeta does not create a raw IPTC-IIM WebP carrier.
build_prepared_transfer_emit_package(...) plus write_prepared_transfer_package(...) can serialize direct WebP chunk bytes from prepared bundles, and the owned package batch/replay path can persist or hand off those bytes without keeping the source bundle alive.
The file edit path rewrites managed metadata chunks and patches existing VP8X feature bits. It does not synthesize a missing VP8X chunk.
Full WebP signed C2PA rewrite/re-sign is still outside the current WebP transfer contract.

ISO-BMFF metadata items (HEIF / AVIF / CR3)¶

This bounded transfer path is metadata-item/property oriented. OpenMeta also supports a bounded BMFF metadata edit path over an existing BMFF target file.
Current prepared item routes:
- bmff:item-exif
- bmff:item-xmp
- bmff:item-jumb
- bmff:item-c2pa
Current prepared property routes:
- bmff:property-colr-icc
EXIF item payloads use the BMFF Exif item shape:
- 4-byte big-endian TIFF offset prefix
- followed by full Exif\0\0 bytes
IPTC requested for BMFF is projected into bmff:item-xmp; OpenMeta does not create a raw IPTC-IIM BMFF carrier.
ICC requested for BMFF uses the bounded property path:
- bmff:property-colr-icc
- payload bytes are u32be(‘prof) + <icc-profile>
- this is acolrproperty payload, not a metadata item
File-based prepare can preserve source generic JUMBF payloads and raw OpenMeta draft C2PA invalidation payloads as BMFF metadata items.
Store-only prepare can project decoded non-C2PAJumbfCborKeyroots into bmff:item-jumbwhen no raw source payload is available.
Core emitter surface: -compile_prepared_bundle_bmff(…) -emit_prepared_bundle_bmff(…) -emit_prepared_bundle_bmff_compiled(…) -emit_prepared_transfer_compiled(…, BmffTransferEmitter&) -build_prepared_transfer_emit_package(…)plus write_prepared_transfer_package(…)can serialize direct BMFF item and property payload bytes from prepared bundles. This is a host/adapter payload handoff, not a standalone BMFF file rewrite.
The shared package-batch persistence/replay layer can own and hand off stable BMFF item and property payload bytes. -metatransfer/openmeta.transfer_probe(…)expose BMFF summaries, includingbmff_item mime/xmp …andbmff_property colr/prof …. -metatransfer —target-heif|—target-avif|—target-cr3 —source-meta … -o … performs bounded metadata edits for targets with no foreign top-levelmeta box, with a prior OpenMeta-authored metadata-onlymetabox from the same bounded contract, or with a parseable foreign top-levelmetaitem graph. The foreign-metapath merges, replaces, or strips bounded Exif/XMP/JUMBF/C2PA metadata items by extendingiinf,iloc,idat, and irefwithcdscreferences to the primary item. It requires a single parseableiinf,ilocversion 0/1/2,pitm, and at most oneidat. Inserted item IDs can use the 32-bit item-id space: supportedilocversion 0/1 graphs are upgraded to outputilocversion 2 when needed, and OpenMeta emits widerinfe/irefrecords for inserted items that exceed 16 bits. Newly inserted metadata item records keepilocconstruction method 0 and use absolute file-offset extents for broad reader compatibility. When retained self-contained records can be represented that way, the rebuiltilocalso compacts the base-offset field width to zero. Retained foreign item locations are supported for construction method 0 file-offset extents and construction method 1 extents into an existing idat, with data reference index 0. Construction method 2 is supported only when the retained item has parseableirefilocreferences, using explicit extent indexes or reference order, and every referenced item is also retained with a supported local location. External data references, missing method-2 references, removed referenced items, and other construction methods fail safely.
Foreign-metaICC property merge is bounded to bmff:property-colr-icc. OpenMeta removes prior ICCcolr/profand colr/rICCproperties fromiprp/ipco, compacts/remaps existingipma associations, appends the transferredcolr/profproperty, and associates it with the primary item and any retained item that previously referenced a replaced ICC property while preserving the prior essential association bit. Broader non-ICC property replacement and arbitrary scene/property-graph rewrites remain out of scope for the current contract.
Embedded-XMP strip mode removes XMP from OpenMeta-authored metadatameta boxes and from parseable foreign top-levelmetaitem graphs that satisfy the same bounded merge contract. Foreign graphs without a primary item relationship (pitm) or outside the supportediinf/iloc/idat/iref` shape still fail explicitly instead of silently claiming removal.
The same bounded BMFF edit contract now also participates in the core / file-helper C2PA signer path:
- sign-request derivation
- binding-byte materialization
- signed-payload validation
- staged bmff:item-c2pa apply before bounded metadata-only edit
Out of scope for the current BMFF contract:
- thin CLI/Python signer-input exposure for BMFF
- arbitrary rewrite of foreign top-level BMFF scene/property graphs
- full BMFF signed rewrite/re-sign beyond the bounded metadata-only edit path

EXR (OpenEXR)¶

EXR metadata is typed header attributes, not EXIF/TIFF IFD blocks.
Use typed attributes for semantic fields.
Unknown attribute types can be preserved as opaque attributes.
OpenMeta EXR path should remain an attribute adapter, not block repackaging.
Current public EXR bridge:
- build_exr_attribute_batch(...) exports one owned per-part attribute list from MetaStore
- build_exr_attribute_part_spans(...) groups that batch into contiguous per-part spans
- build_exr_attribute_part_views(...) exposes zero-copy grouped per-part views over the same batch
- replay_exr_attribute_batch(...) replays the grouped batch through explicit host callbacks
- known scalar/vector EXR types are re-encoded into deterministic EXR attribute bytes
- unknown/custom attrs are preserved as opaque raw bytes when Origin::wire_type_name is available
- ambiguous attrs without a stable wire-type contract fail closed or can be skipped explicitly

Unified Workaround (Single Contract)¶

Use one two-phase pipeline for all backends:

prepare_metadata_for_target(source_store, target_format, profile)
- Build target-ready block payloads once.
- Build deterministic write order.
- Build optional fixed-size patch map for per-frame time fields.
emit_prepared_bundle(bundle, writer_target, frame_patch)
- Emit prebuilt payloads through backend-specific write calls.
- Apply optional fixed-width time patch before final write.

This keeps heavy work out of hot per-frame loops.

Backend Interface Shape (Draft)¶

Define narrow backend interfaces:

JpegWriterBackend::write_app_block(app_marker, bytes)
TiffWriterBackend::set_tag(tag_id, bytes_or_scalar) plus commit_exif_directory(offset_ref)
JxlWriterBackend::add_box(type4cc, bytes, compress)
ExrWriterBackend::set_attribute(name, typed_or_opaque_value)

OpenMeta core emits backend-neutral prepared payloads. Backends only perform container call mapping.

Policy Defaults (Draft)¶

No-edits transfer mode: preserve payloads when legal for target container.
EXIF pointer tags are regenerated for target container layout.
MakerNote and C2PA/JUMBF transfer policy is explicit and deterministic.
Current JPEG/TIFF prepare behavior:
- MakerNote: Keep default, Drop supported, Invalidate currently resolves to Drop, Rewrite currently resolves to raw-preserve.
- JUMBF: file-based JPEG prepare can preserve source payloads by repacking them into APP11 segments; store-only JPEG prepare can project decoded non-C2PA JumbfCborKey roots into generic APP11 JUMBF payloads; explicit raw JUMBF -> JPEG APP11 append is available through append_prepared_bundle_jpeg_jumbf(...); and JPEG rewrite/edit removes existing APP11 JUMBF when the resolved policy is Drop. Ambiguous numeric map keys and decoded-CBOR bool/simple/sentinel/large-negative fallback forms in projected JUMBF are rejected; tagged CBOR values are preserved.
- C2PA: Invalidate on JPEG now emits a draft unsigned APP11 C2PA invalidation payload.
  - PreparedTransferPolicyDecision exposes mode, source_kind, and prepared_output so adapters can branch without parsing free-form messages.
  - PreparedTransferBundle::c2pa_rewrite exposes the separate rewrite-prerequisites contract for future signing flows: current rewrite state, source kind, existing carrier segment count, and whether manifest builder, content binding, certificate chain, private key, and signing time are still required.
  - For JPEG it exposes content_binding_chunks as preserved source ranges plus prepared JPEG segments; for the bounded BMFF edit path it uses preserved source ranges plus one prepared metadata-only meta box.
  - build_prepared_c2pa_sign_request(...) derives the external signer view from that same data without changing the bundle contract.
  - build_prepared_c2pa_sign_request_binding(...) materializes the exact content-binding bytes from that request and the target container input. Current bounded targets are JPEG and BMFF.
  - build_prepared_c2pa_handoff_package(...) combines the signer request and exact binding bytes into one public handoff object.
  - serialize_prepared_c2pa_handoff_package(...) and deserialize_prepared_c2pa_handoff_package(...) persist that object.
  - build_prepared_c2pa_signed_package(...) combines the sign request and signer-returned material into one persisted signed package.
  - serialize_prepared_c2pa_signed_package(...) and deserialize_prepared_c2pa_signed_package(...) persist that package.
  - Thin wrappers expose that as CLI dump output and Python unsafe raw bytes for JPEG without duplicating the reconstruction logic. BMFF uses the same core helper without separate wrapper flags yet.
  - validate_prepared_c2pa_sign_result(...) validates a returned signed logical C2PA payload before bundle mutation and reports staged carrier size and segment count.
  - Current JPEG validation also checks semantic manifest/claim/signature consistency, resolved explicit references, request-aware manifest count / claim_generator requirements, decoded-assertion presence when content binding is required, the primary signature linking back to the prepared primary claim under that same content-binding contract, no primary-signature explicit-reference ambiguity under that same request, no multi-signature drift where the primary claim is referenced by more than one signature under the current sign request, and no extra linked signatures beyond the prepared sign request, manifest/claim/signature projection shape under the prepared manifest contract, exact primary manifest-CBOR equality against manifest_builder_output, staged APP11 sequence order, and exact logical-payload reconstruction. Final JPEG emit/write also rejects prepared APP11 C2PA carriers with non-contiguous sequence numbers, inconsistent repeated headers, invalid logical root type, or BMFF declared-size drift before backend bytes are written.
  - Final JPEG emit/write also rejects prepared APP11 C2PA carriers that violate the resolved bundle contract: missing required carriers, draft-invalidated carriers under a signed rewrite contract, signed-rewrite carriers under a draft contract, and Ready rewrite state without SignedRewrite prepared output.
  - apply_prepared_c2pa_sign_result(...) accepts the external signer output and stages a content-bound logical C2PA payload back into prepared JPEG APP11 blocks, JXL jumb boxes, or bounded BMFF bmff:item-c2pa items after strict request validation.
  - The file-level execution helper can now validate that stage step, apply it, and continue into normal JPEG emit/edit, bounded JXL edit, or bounded BMFF edit flow. Thin CLI/Python signer-input wrappers now cover JPEG, JXL, and bounded BMFF targets. The option name --jpeg-c2pa-signed remains for compatibility.
  - PreparedTransferPackagePlan now provides the shared final-output package contract for current JPEG/TIFF rewrite paths plus direct JPEG/JXL emit packaging: deterministic source ranges, prepared direct blocks, prepared JPEG segments, and inline generated bytes can be written through one generic package writer.
  - PreparedTransferPackageBatch is the owned replay form of that same contract: each package chunk is materialized into stable bytes so the final metadata package can be cached or handed off without the original input stream or prepared bundle storage.
  - serialize_prepared_transfer_package_batch(...) and deserialize_prepared_transfer_package_batch(...) persist that owned batch so host layers can move it across process or integration boundaries without reopening the source file or rebuilding the bundle.
  - collect_prepared_transfer_payload_views(...) and build_prepared_transfer_payload_batch(...) now provide the matching target-neutral semantic payload surface directly over prepared bundles.
  - serialize_prepared_transfer_payload_batch(...) and deserialize_prepared_transfer_payload_batch(...) persist that earlier semantic payload batch for cross-process or cross-layer handoff before final package materialization.
  - collect_prepared_transfer_package_views(...) is the target-neutral semantic package surface above that persisted batch.
  - replay_prepared_transfer_package_batch(...) is the target-neutral callback replay surface above that same persisted batch.
  - OpenMeta no longer ships an in-library host-specific payload/package bridge above these target-neutral package views and replay APIs.
  - build_prepared_transfer_adapter_view(...) now provides the parallel target-neutral adapter view for JPEG/TIFF/JXL host integrations that want explicit compiled operations without route parsing.
  - emit_prepared_transfer_adapter_view(...) replays that compiled view through one generic host sink.
  - replay_prepared_transfer_payload_batch(...) now reuses that same earlier persisted semantic payload stage directly, before final package materialization.
  - File-based JPEG prepare can preserve an existing OpenMeta draft invalidation payload as raw APP11 C2PA (TransferC2paMode::PreserveRaw).
  - Content-bound Keep still resolves to Drop.
  - Rewrite resolves to Drop with explicit SignedRewriteUnavailable until re-sign support exists, but externally signed payload staging is now available once a signer has consumed the request.
  - JPEG content-changing rewrite/edit removes existing APP11 C2PA from the target before inserting the new prepared payload.
Safety limits are enforced before backend calls (size, truncation, malformed).

Recommended Integration Order¶

JPEG and TIFF direct backends (highest transfer value).
JXL box emitter parity for EXIF/XMP plus bounded JUMBF/C2PA preserve or projection.
If a future host-specific bridge needs persistence or replay formats, build that on top of the target-neutral package and adapter surfaces rather than adding a host-specific wrapper inside OpenMeta.
Extend the current EXR attribute batch bridge if host-side replay or persistence formats are needed.

This order aligns with fast transfer requirements and minimal overhead in high-FPS pipelines.

page Metadata Support Matrix (Draft)

This document summarizes the current read-path coverage in OpenMeta.

It is meant to answer four basic questions:

which containers are scanned
which metadata families are decoded into MetaStore
where display-name mapping exists
what can be dumped or exported today

Status Labels¶

Yes: supported in current code
Partial: supported, but still bounded or best-effort
No: not supported yet

Host integrations can query the same kind of runtime support information with openmeta/metadata_capabilities.h. That API reports read, structured decode, transfer preparation, target edit, and raw-preservation support by target format and metadata family.

For the public camera RAW read-depth plan against ExifTool-style coverage, see raw_read_parity_plan.md.

Coverage Snapshot¶

Current tracked-gate status:

EXIF tag-id compare gates are passing on tracked HEIC/HEIF, CR3, and mixed RAW corpora.
Standalone EXIF/TIFF payload recovery is covered for files with a short non-TIFF prefix or a malformed JPEG prefix before the Exif preamble.
EXR header metadata compare is passing for the documented name/type/value-class contract.
Sidecar export paths (lossless and portable) are covered by baseline and smoke tests.
MakerNote coverage is tracked by baseline gates with broad vendor support; unknown vendor tags are preserved as raw metadata for lossless workflows.
Decoded vendor MakerNote sub-IFDs are interpreted/query metadata. Writers do not reconstruct MakerNote blobs from those decoded fields; they preserve the original raw MakerNote payload when it is present.
Metadata-family presence gates for XMP, ICC, IPTC-IIM, Photoshop IRB, and JUMBF/C2PA are clean on the tracked still-image corpus. Current read coverage includes EXIF/TIFF-carried ICC/IPTC payloads, bare JPEG APP1 XMP packets, and XMP packets using alternate xmpmeta namespace prefixes.
BMFF edge-path tests include iloc construction-method-2 relation variants and safe-skip handling for invalid references.

Container Coverage¶

Container / input type	Block discovery	Structured decode in `simple_meta_read(...)`	Notes
JPEG	Yes	Yes	EXIF, standard and bare APP1 XMP, extended XMP, ICC, MPF, Photoshop IRB, comments, vendor APP blocks, and bounded JUMBF/C2PA
PNG	Yes	Yes	EXIF, XMP, ICC, structured PNG text, and bounded JUMBF/C2PA
WebP	Yes	Yes	EXIF, XMP, ICC, and bounded JUMBF/C2PA
GIF	Yes	Partial	XMP, ICC, and structured comments
TIFF / DNG / TIFF-based RAW	Yes	Yes	EXIF, MakerNote, XMP, IPTC, Photoshop IRB, ICC, GeoTIFF, and bounded JUMBF/C2PA
CRW / CIFF	Yes	Partial	Recursive CIFF directories, stable scalar/subtable decode, derived EXIF bridge, and bounded native Canon CIFF naming/projection
RAF / X3F	Partial	Partial	RAF includes header-declared preview-JPEG EXIF/XMP discovery, FujiIFD/TIFF follow path, native RAF header/directory geometry tags, RAFData geometry projection, and standalone XMP fallback; X3F includes header fields, known PROP properties, section-directory JPEG metadata follow path, and legacy embedded-EXIF fallback
JP2	Yes	Yes	EXIF, XMP, IPTC, ICC, and GeoTIFF
JXL	Yes	Yes	EXIF, XMP, and bounded JUMBF/C2PA; supported `brob` wrapped metadata is decoded
HEIF / AVIF / CR3	Yes	Partial	EXIF, XMP, ICC, CR3 maker blocks, BMFF derived fields, and bounded JUMBF/C2PA
EXR	n/a via `scan_auto(...)`	Yes	Header attributes only; no pixel decode

Metadata Family Coverage¶

Metadata family	Decode	Name mapping	Dump / export	Notes
EXIF (`MetaKeyKind::ExifTag`)	Yes	Yes	Yes	Standard EXIF plus pointer IFDs
MakerNote	Partial / Yes	Partial / Yes	Lossless yes; portable limited	Broad vendor coverage; unknown tags may remain raw
XMP (`MetaKeyKind::XmpProperty`)	Yes	Native schema/path	Yes	Requires Expat at build time
ICC (`IccHeaderField`, `IccTag`)	Yes	Yes	Yes	Header fields plus tag table; raw tag payload preserved
IPTC-IIM (`IptcDataset`)	Yes	Yes	Yes	Raw dataset bytes preserved
Photoshop IRB (`PhotoshopIrb`)	Yes	Partial / Yes	Yes	Raw resources preserved, bounded interpreted subset, fixed-layout and descriptor-header summaries, embedded IPTC/XMP/ICC decode
MPF	Yes	Yes	Yes	Basic TIFF-IFD decode
GeoTIFF (`GeotiffKey`)	Yes	Yes	Yes	GeoKeyDirectoryTag decode
BMFF derived fields (`BmffField`)	Yes	Yes	Yes	`ftyp`, item-info, `ipma`, `iref`, graph summaries, aux semantics, primary item properties, and bounded primary-linked image roles
JUMBF / C2PA (`JumbfField`, `JumbfCborKey`)	Partial	Yes	Yes	Draft structural and semantic layer with box labels; not full conformance
EXR attributes (`ExrAttribute`)	Yes	Native names	Yes	Header attributes only

Important Bounded Areas¶

CRW / CIFF¶

OpenMeta now does more than a pure derived-EXIF bridge:

common native CIFF tags are named
a bounded set of native subtables is projected
stable scalar native CIFF fields are decoded where the layout is clear

It is still a partial lane compared to the deepest legacy Canon tooling.

RAF¶

OpenMeta now follows both RAF metadata carriers that matter for common camera files:

the header-declared preview JPEG is scanned for standard EXIF/XMP-style metadata
the header-declared FujiIFD/TIFF area is scanned for native RAF/raw fields
native RAF header, directory, and RAFData-derived fields are classified as source-specific metadata for rendered-transfer safety

Deeper model-specific RAF sections remain a partial lane.

X3F¶

OpenMeta now has a bounded native Sigma X3F lane:

common X3F header fields are decoded as x3f_header
stable header-extension adjustment fields are decoded as x3f_header_ext
known PROP properties are decoded as x3f_prop
section-directory JPEG metadata is followed for embedded EXIF/XMP-style metadata blocks, with the older embedded-EXIF scan kept as fallback

Deeper image-processing/compression sections remain partial and should only be promoted when fields can be typed, named, and safety-classified.

Photoshop IRB¶

OpenMeta preserves raw IRB resources and also decodes a bounded interpreted subset. That subset includes common fixed-layout resources and descriptor-header summaries such as:

Photoshop2Info
Photoshop2ColorTable
ResolutionInfo
AlphaChannelsNames
DisplayInfo
PStringCaption
BorderInformation
BackgroundColor
VersionInfo
PrintFlags
print-flag byte fields
EffectiveBW
QuickMaskInfo
RawImageMode
JPEG_Quality
GridGuidesInfo
legacy halftone, transfer-function, duotone-image, and EPS byte summaries
PhotoshopBGRThumbnail / PhotoshopThumbnail headers
SpotHalftone
UnicodeAlphaNames
AlphaIdentifiers
JumpToXPEP
PrintScaleInfo
PixelInfo
AutoSaveFilePath
AutoSaveFormat
XMLData
ImageReadyVariables
ImageReadyDataSets
ColorSamplersResource / ColorSamplersResource2 headers and records
WorkingPath and numbered path resources as record counts/selectors
descriptor-header summaries for resources such as LayerComps, MeasurementScale, TimelineInfo, SheetDisclosure, OnionSkins, CountInfo, PrintInfo2, PrintStyle, PathSelectionState, and OriginPathInfo
ChannelOptions
PrintFlagsInfo
ClippingPathName
embedded ICC, EXIF, EXIF2, and XMP resource byte counts

When enabled, embedded IPTC-IIM, XMP, and ICC payloads in IRB resources are also decoded into their regular OpenMeta entry families.

Current Photoshop IRB interpretation status:

Resource area	Status	Notes
Raw IRB resources	Preserved	Every accepted resource keeps a lossless `PhotoshopIrb` raw entry.
Embedded IPTC/XMP/ICC/EXIF carriers	Interpreted where enabled	Payload bytes remain preserved; enabled decoders also emit regular family entries.
Fixed-layout scalar/string resources	Interpreted	Resolution, alpha/caption strings, version, print flags, quick mask, JPEG quality, URL/list, pixel info, autosave strings, `XMLData`, and similar bounded fields.
Geometry/display/color-sampler/path headers	Interpreted / record-summary	Display/grid/thumbnail/color-sampler headers are decoded; path resources expose record counts and selectors without interpreting Bezier payloads.
Descriptor-backed Photoshop resources	Descriptor-header only	Descriptor version and remaining byte count are emitted; descriptor body parsing remains out of scope for this subset.
Legacy halftone/transfer/duotone/EPS resources	Header / byte-count only	OpenMeta emits byte counts and first header words where safe, without claiming full Photoshop semantics.
Proprietary, obsolete, or OS-specific resources	Raw-only	Kept losslessly until a bounded public layout is implemented.

This is useful, but it is still not full Photoshop-resource parity.

BMFF (<tt>HEIF</tt> / <tt>AVIF</tt> / <tt>CR3</tt>)¶

OpenMeta now has a bounded semantic model on top of raw item discovery:

ftyp.*, including brand names and compatible-brand counts
primary item properties
ipma item-property association rows with item ids, property indices, essential flags, and known property type names
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
aggregate item semantic counters for known, metadata, image, EXIF, XMP, JUMBF, C2PA, ICC profile, auxiliary, derived, thumbnail, content-description, URI, and JSON roles
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
primary pasp, pixi, and clap item-property summaries for pixel aspect ratio, pixel component bit depth, and clean aperture

This is intentionally smaller than a full QuickTime/BMFF semantic model.

JXL¶

OpenMeta decodes:

direct Exif
direct xml
direct jumb
direct c2pa
wrapped brob forms for those same realtypes

Other brob realtypes are still out of scope.

JUMBF / C2PA¶

Current support is intentionally draft:

structural BMFF box decode
JUMBF box labels from parsed jumd boxes
bounded CBOR traversal
draft c2pa.semantic.* projection
draft verify scaffolding with opt-in trusted certificate-chain enforcement

What this means in practice:

OpenMeta can expose useful manifest / claim / signature / ingredient shape information
OpenMeta can report signature verification and certificate-chain trust as separate signals, or fail verification when verify_require_trusted_chain / --c2pa-verify-require-trusted-chain is set
OpenMeta does not yet claim full C2PA manifest semantics or full policy validation

Tool-Level Behavior¶

Tool	Purpose	Current state
`metaread`	Human-readable metadata listing	Shows decoded entries with mapped names where available
`metavalidate`	Metadata validation	Reports decode-status and validation issues with machine-readable issue codes
`metadump`	Sidecar and preview dump tool	Supports `lossless` and `portable` sidecar output plus preview extraction
`thumdump`	Preview extractor	Extracts embedded preview candidates
`metatransfer`	Transfer/edit smoke tool	Exercises the transfer core for supported target families

Main Current Gaps¶

HEIF/AVIF scene semantics beyond the current bounded primary-linked role surface
additional JXL brob realtypes beyond Exif, xml, jumb, and c2pa
full JUMBF/C2PA semantics and policy validation
deeper RAF model-specific native tables and X3F image-processing sections beyond the current bounded carrier/header/property lanes
broader Photoshop IRB interpretation beyond the current bounded subset

Related Docs¶

metadata_transfer_plan.md
development.md

page Metadata Transfer Plan (Draft)

Date: March 5, 2026

quick_start.md
host_integration.md
metadata_backend_matrix.md

Goal¶

The transfer core is for metadata-only workflows:

source: camera RAW and other supported inputs
target: export-oriented container metadata
scope: prepare once, then emit or edit many times

Pixel transcoding is out of scope.

Design Rule¶

Transfer should not bottleneck high-throughput pipelines.

The core rule is:

do the expensive work once during prepare
reuse prebuilt metadata payloads during compile and emit
keep per-frame work limited to optional time patching plus final container write calls

Current Status¶

Current planning estimate for this lane: about 80-85%.

Source-side readiness is already strong:

tracked EXIF read gates are green on HEIC/HEIF, CR3, and mixed RAW corpora
tracked MakerNote gates are green
portable XMP gates are green
EXR header interop gates are green

The main remaining work is now on the target side.

The first public write-side sync controls are also in place:

generated XMP can explicitly suppress EXIF-derived projection
generated XMP can explicitly suppress IPTC-derived projection
TransferProfile::safety can distinguish compatible metadata repackage/recompression from rendered-image export, so callers can select a safe coarse policy without hand-picking individual tags
prepared bundles record those resolved projection decisions alongside the existing preservation policies

Target Status Matrix¶

Target	Status	Current shape	Main limits
JPEG	First-class	Prepared bundle, compiled emit, byte-writer emit, edit planning/apply, file helper, bounded JUMBF/C2PA staging	Not a full arbitrary metadata editor yet
TIFF	First-class	Prepared bundle, compiled emit, classic-TIFF and BigTIFF edit planning/apply, bounded preview-page chain rewrite (`ifd1`, `ifd2`, and preserved downstream tails), bounded SubIFD rewrite with preserved downstream auxiliary tails and preserved trailing existing children when only the front subset is replaced, bounded `ExifIFD -> InteropIFD` preservation when a replaced ExifIFD omits its own interop child, file helper, streaming edit path	Broader TIFF rewrite coverage is still narrower than JPEG
DNG	First-class	Dedicated public target layered on the TIFF backend; prepared bundle, compiled emit, minimal `DNGVersion` synthesis when missing, bounded DNG preview/aux merge policy, read-backed file-helper roundtrip, and the same bounded `SubIFD`/preview-tail/interop preservation contract as TIFF	Not a full DNG-specific rewrite engine or broad DNG policy surface
PNG	Bounded but real	Prepared bundle, compiled emit, bounded chunk rewrite/edit, file-helper roundtrip	Not a general PNG chunk editor
WebP	Bounded but real	Prepared bundle, compiled emit, bounded chunk rewrite/edit, file-helper roundtrip	Not a general WebP chunk editor
JP2	Bounded but real	Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip	`jp2h` synthesis is still out of scope
JXL	Bounded but real	Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip	Still narrower than JPEG/TIFF
HEIF / AVIF / CR3	Bounded but real	Prepared bundle, compiled emit, OpenMeta-managed BMFF item/property edit, constrained foreign-`meta` item merge/replacement/strip plus bounded ICC property merge, file-helper roundtrip	Not broad BMFF writer parity; arbitrary foreign `meta` scene/property-graph rewrite is still unsupported
EXR	Bounded but real	Prepared bundle, compiled emit, direct backend attribute emit, prepared-bundle to `ExrAdapterBatch` bridge, CLI/Python transfer surface	No file rewrite/edit path yet; current transfer payload is safe string attributes only

What Is Already Implemented¶

Core API¶

The shared transfer core already provides:

prepare_metadata_for_target(...)
prepare_metadata_for_target_file(...)
compile_prepared_transfer_execution(...)
execute_prepared_transfer(...)
execute_prepared_transfer_compiled(...)
execute_prepared_transfer_file(...)

This supports both:

prepare -> compile -> emit
prepare -> compile -> patch -> emit/edit

Core Utility Layers¶

These support the public transfer flow:

TransferByteWriter
SpanTransferByteWriter
prepared payload and package batch persistence
adapter views for host integrations
explicit time-patch support for fixed-width EXIF date/time fields
transfer-policy decisions for MakerNote, JUMBF, C2PA, EXIF-to-XMP projection, and IPTC-to-XMP projection

Current File-Helper Regression Coverage¶

OpenMeta now has explicit end-to-end read-backed transfer tests for:

source JPEG -> JPEG edit/apply -> read-back
source JPEG -> TIFF edit/apply -> read-back
source JPEG -> DNG edit/apply -> read-back
source JPEG -> TIFF edit/apply with bounded preview-page chain -> read-back
source TIFF/BigTIFF with existing multi-page preview chain -> replace the front preview pages and preserve downstream tails
source DNG-like TIFF with subifd0 + ifd1 -> TIFF edit/apply -> read-back
source DNG-like TIFF with subifd0 + ifd1 -> BigTIFF edit/apply -> read-back
source DNG-like TIFF with subifd0 + ifd1 -> DNG edit/apply -> read-back
source TIFF/BigTIFF with existing subifd0 -> next auxiliary chain -> replace subifd0 -> preserve downstream auxiliary tail
source JPEG -> PNG edit/apply -> read-back
source JPEG -> WebP edit/apply -> read-back
source JPEG -> JP2 edit/apply -> read-back
source JPEG -> JXL edit/apply -> read-back
source JPEG -> bounded HEIF edit/apply -> read-back
source JPEG -> bounded AVIF edit/apply -> read-back
source JPEG -> bounded CR3 edit/apply -> read-back
source ICC -> bounded BMFF ICC property edit/apply -> read-back and external validation when local HEIF/AVIF/CR3 encoders can create usable targets
direct BMFF package planning/writing for prepared metadata items and bounded ICC colr/prof property payloads, plus owned package replay for constrained foreign-meta graph merges
source XMP -> bounded BMFF XMP item edit/apply -> read-back and external validation on configured HEIF/AVIF/CR3 targets where local tools expose the transferred XMP payload
source EXIF -> bounded BMFF Exif item edit/apply -> explicit ExifTool reader-layout regression check on configured HEIF/AVIF/CR3 targets

That does not make all targets equally mature, but it does mean the transfer core has real roundtrip regression gates across the primary supported export families.

The primary writer family is also covered by a deterministic compatibility-dump gate for JPEG, TIFF, DNG, PNG, WebP, JP2, JXL, and bounded HEIF, AVIF, and CR3 item metadata edits. That gate checks the prepared EXIF/XMP routes, edit/apply status, dual-write XMP writeback summary, and decoded metadata dump for the managed source fields. Additional compatibility-dump gates cover sidecar-only writeback with explicit sidecar-base overrides and embedded-only writeback with destination-sidecar cleanup through persisted output.

There is now also a named in-tree transfer release gate:

openmeta_gate_transfer_release
openmeta_transfer_release_gate

In a non-Python test tree it runs:

MetadataTransferApi.*
XmpDump.*
ExrAdapter.*
DngSdkAdapter.*
openmeta_cli_metatransfer_smoke

In a Python-enabled test tree it also runs:

openmeta_python_transfer_probe_smoke
openmeta_python_metatransfer_edit_smoke

The external image-usability gate can use optional configured HEIF, AVIF, and CR3 target files via CMake cache paths when local tools cannot create those formats. Configured BMFF targets exercise ICC property, XMP item, MakerNote, and EXIF image-property transfer/read-back routes. For real configured targets, the gate infers target-owned image dimensions, channel count, bit depth, sample format, and photometric layout before transfer, so OpenMeta does not write the synthetic fixture geometry into the destination metadata. ExifTool is used when available for BMFF EXIF/XMP/ICC reader compatibility checks.

Per-Target Notes¶

JPEG¶

Strongest current target.

Implemented:

EXIF as APP1
XMP as APP1
ICC as APP2
IPTC as APP13
edit planning and apply
byte-writer emit
bounded JUMBF/C2PA staging

TIFF¶

Also a first-class target.

Implemented:

EXIF, XMP, ICC, and IPTC transfer
edit planning and apply
classic-TIFF and BigTIFF rewrite support
bounded ifd1 chain rewrite support, including preserving an existing downstream page tail when ifd1 is replaced
bounded TIFF/DNG-style SubIFD rewrite support, including preserving an existing downstream auxiliary tail when subifdN is replaced
bounded front-subset SubIFD replacement that preserves trailing existing children from the target file
bounded ExifIFD replacement that preserves an existing target InteropIFD when the source replacement omits its own interop child
target-owned root image layout and target-local TIFF storage pointers: source EXIF cannot replace the active target root image width/height, sample layout, compression, orientation, strip/tile offsets, strip/tile byte counts, or JPEG interchange offsets; replaced preview/SubIFD structures also drop source-local storage offsets and preserve matching target-local storage fields where available
target-owned image-dependent metadata filtering across prepared transfer: EXIF/XMP image dimensions, channel/layout fields, source-local storage offsets, color-space aliases, and similar source image-buffer facts are omitted before packaging metadata for JPEG, TIFF/DNG, PNG, WebP, JP2, JXL, BMFF-family targets, and EXR string attributes. Host writers that change pixels must provide target image buffer specs and target-correct values instead of relying on copied source image properties. C++ callers can set PrepareTransferRequest::target_image_spec to inject target dimensions, orientation, samples-per-pixel, bit depth, sample format, photometric interpretation, planar configuration, compression, and EXIF color space after source image-layout fields have been filtered. The Python binding and both command-line transfer wrappers now expose the same target image spec surface for file-helper integration tests.
rendered-output safety mode: TransferProfile::safety = TransferSafetyMode::RenderedImage additionally drops source raw color calibration, profile/gain tables, raw digests/storage identifiers, linearization/crop/correction metadata, vendor RAW geometry/color/correction/thermal/computational/private/stitch fields, camera raw settings XMP, source ICC profiles, MakerNotes, and non-C2PA JUMBF data. It is intended for RAW-to-rendered or otherwise pixel-changing exports where host code must provide target-correct color/profile data.
safety regression coverage now checks both sides of that boundary: compatible-file mode keeps serializable source RAW/camera-specific metadata, while rendered-image mode drops the same source-specific data and injects host-provided target dimensions, channel count, bit depth, sample format, photometric interpretation, and orientation.
current writer limits still apply after safety filtering: some compatible source metadata can be retained in the decoded MetaStore and audit, but may not yet serialize through every target writer path. Adobe DNG XMP properties (dng:*) are now emitted by the portable XMP writer when retained by compatible-file safety. The remaining writer gap is mainly reconstructed vendor-private MakerNote sub-IFDs and unknown/custom XMP namespaces that do not have a declared portable writer contract. OpenMeta preserves the raw ExifIFD:MakerNote payload when it is present, but decoded-only vendor MakerNote sub-IFD fields are reported as non-serializable and are not used to synthesize a new MakerNote blob.
bounded DNG-style merge policy in the file-helper path: source-supplied preview/aux front structures replace the target front structures, while existing target page tails and trailing auxiliary children are preserved
file-based helper flow
streaming edit output

DNG¶

Implemented as a dedicated public target on top of the TIFF backend.

Implemented:

EXIF, XMP, ICC, and IPTC transfer through the TIFF-family backend
read-backed file-helper roundtrip for JPEG-source and DNG-like-source input
minimal DNGVersion synthesis when the source metadata lacks it
explicit public target modes:
- ExistingTarget
- TemplateTarget
- MinimalFreshScaffold
bounded preview-page chain rewrite/merge
bounded raw-image SubIFD rewrite/merge
preservation of existing target DNG core tags when a non-DNG source is merged into an existing DNG target
preserved downstream page tails and downstream auxiliary tails
preserved trailing existing auxiliary children when only the front subset is replaced
bounded ExifIFD replacement that preserves an existing target InteropIFD when the source replacement omits its own interop child

Current limits:

still a bounded DNG policy layer, not a full DNG-specific rewrite engine
broader arbitrary nested-IFD graph rewrite is still out of scope
in the file-helper path, ExistingTarget and TemplateTarget now require an explicit target path; only MinimalFreshScaffold keeps the metadata-only prepare/emit path available without a backing DNG container

Optional host bridge:

When OpenMeta is built with OPENMETA_WITH_DNG_SDK_ADAPTER=ON and a dng_sdk package is discoverable, openmeta/dng_sdk_adapter.h exposes a bounded Adobe DNG SDK bridge for:
- applying prepared OpenMeta DNG bundles onto dng_negative
- updating an existing dng_stream via the SDK’s metadata-update path
- a direct file-helper for source file -> existing DNG file in-place update
- a matching direct Python binding over that file-helper
- a thin CLI wrapper via metatransfer --update-dng-sdk-file
This adapter is optional. Core Dng transfer support remains available without the Adobe SDK.
The OpenMeta build must use a C++ runtime/standard library compatible with the discovered dng_sdk package.
Public automated CI intentionally excludes this SDK-backed lane because the Adobe DNG SDK is not part of the public dependency/distribution story. Treat it as a maintainer or release-validation path rather than a default GitHub Actions requirement.

PNG¶

Implemented as a bounded chunk target:

eXIf
XMP iTXt
iCCP
bounded rewrite/edit for managed metadata chunks

WebP¶

Implemented as a bounded RIFF metadata target:

EXIF
XMP
ICCP
bounded C2PA
bounded rewrite/edit for managed metadata chunks
EXIF chunk payloads use direct TIFF bytes, without the JPEG APP1 Exif\0\0 preamble

JP2¶

Implemented as a bounded box target:

Exif
xml
bounded jp2h / colr
bounded rewrite/edit for top-level managed metadata
replacement of managed colr in an existing jp2h

JXL¶

Implemented as a bounded box target:

Exif
xml
bounded jumb
bounded c2pa
encoder ICC handoff
bounded box-based edit path

HEIF / AVIF / CR3¶

Implemented as a bounded BMFF target family:

bmff:item-exif
bmff:item-xmp
bounded bmff:item-jumb
bounded bmff:item-c2pa
bounded bmff:property-colr-icc
bounded OpenMeta-managed metadata-only meta rewrite path
constrained foreign top-level meta item merge for parseable iinf, iloc version 0/1/2, pitm, optional single idat, and primary-item cdsc references
bounded 32-bit item-id insertion for foreign item graphs, including automatic iloc version 2 upgrade when an otherwise supported iloc version 0/1 graph exhausts the 16-bit item-id space
inserted metadata item records keep iloc construction method 0 and use absolute file-offset extents for broad reader compatibility
retained foreign item locations support construction method 0 file offsets and construction method 1 idat extents with data reference index 0
retained construction method 2 item-reference extents are supported when iref iloc references are parseable by explicit extent index or reference order and referenced items are also retained with supported local locations; missing references, removed referenced items, external data references, and other construction methods fail safely
rebuilt foreign iloc graphs compact foldable self-contained base offsets to a zero-width base-offset field when safe
bounded foreign top-level meta ICC property merge by replacing prior ICC colr/prof and colr/rICC properties, remapping ipma, and associating the transferred colr/prof property with the primary item and any retained item that previously referenced a replaced ICC property while preserving the prior essential association bit
bounded foreign top-level meta XMP replacement and strip support for parseable item graphs that satisfy the same primary-item contract
fail-safe rejection for unsupported foreign top-level meta shapes and broader BMFF item/property graph rewrite shapes outside the bounded contract

EXR¶

Implemented today as a bounded first-class target:

prepare_metadata_for_target(...)
prepare_metadata_for_target_file(...)
compile_prepared_transfer_execution(...)
emit_prepared_bundle_exr(...)
emit_prepared_transfer_compiled(...)
public CLI/Python --target-exr transfer surface

It still keeps the older integration bridge:

build_exr_attribute_batch(...)
build_exr_attribute_part_spans(...)
build_exr_attribute_part_views(...)
replay_exr_attribute_batch(...)

The transfer lane now also exposes:

build_prepared_exr_attribute_batch(...)
build_exr_attribute_batch_from_file(...)
Python build_exr_attribute_batch_from_file(...) for direct file-to-batch host-side inspection without going through the generic transfer probe
Python helper wrappers: openmeta.python.probe_exr_attribute_batch(...) and openmeta.python.get_exr_attribute_batch(...)

That keeps EXR host integrations on the transfer path: callers can prepare one TransferTargetFormat::Exr bundle, then materialize a native ExrAdapterBatch without re-projecting from the source MetaStore.

Current EXR transfer scope is intentionally conservative:

safe flattened string header attributes
backend emission through ExrTransferEmitter
no general file-based EXR metadata rewrite/edit path yet
no typed EXR attribute synthesis beyond the current safe string projection

Important user use case to keep visible:

A tile/region streaming EXR writer may know some metadata only after all pixel chunks are written, for example total_compute_time.
The practical fast path for that use case is not a general variable-length header rewrite. It is a fixed-size reservation/patch contract: declare a fixed-width attribute, such as a double, before opening the EXR writer, write pixel chunks normally, then patch only the reserved value bytes after close.
OpenMeta does not expose that late-bound EXR patch plan yet. If EXR depth is expanded, the first useful scope should be a bounded fixed-size patch API with offset discovery, type/size validation, and a decode-after-patch verification gate.

Transfer Policies¶

The public transfer contract now models five policy subjects:

MakerNote
JUMBF
C2PA
XMP EXIF projection
XMP IPTC projection

Each uses explicit TransferPolicyAction values:

Keep
Drop
Invalidate
Rewrite

Prepared bundles also record the resolved policy decisions and reasons so callers do not have to infer behavior from warning text alone.

For the XMP projection subjects, the current public knobs are intentionally simple:

EXIF-derived properties can be mirrored into generated XMP or suppressed
IPTC-derived properties can be mirrored into generated XMP or suppressed
generated portable XMP can choose how existing decoded XMP conflicts with generated EXIF/IPTC mappings

This gives callers stable write-side control over the most important projection behavior without forcing them to reverse-engineer the transfer output.

Write-Side Sync Controls¶

OpenMeta now has a bounded public sync-policy layer for generated XMP.

Current controls:

xmp_project_exif
xmp_project_iptc
xmp_existing_namespace_policy
- KnownPortableOnly
- PreserveCustom
xmp_conflict_policy
xmp_existing_sidecar_mode on the file-read/prepare path:
- Ignore
- MergeIfPresent
xmp_existing_sidecar_precedence on the file-read/prepare path:
- SidecarWins
- SourceWins
xmp_existing_destination_embedded_mode on the file-read/prepare and file-helper execution paths:
- Ignore
- MergeIfPresent
xmp_existing_destination_embedded_precedence on the file-read/prepare and file-helper execution paths:
- DestinationWins
- SourceWins
xmp_writeback_mode on the file-helper execution path:
- EmbeddedOnly
- SidecarOnly
- EmbeddedAndSidecar
xmp_destination_embedded_mode on the file-helper execution path:
- PreserveExisting
- StripExisting
CLI:
- --xmp-include-existing-sidecar
- --xmp-existing-sidecar-precedence <sidecar_wins|source_wins>
- --xmp-include-existing-destination-embedded
- --xmp-existing-destination-embedded-precedence <destination_wins|source_wins>
- --xmp-no-exif-projection
- --xmp-no-iptc-projection
- --xmp-conflict-policy <current|existing_wins|generated_wins>
- --xmp-writeback <embedded|sidecar|embedded_and_sidecar>
- --xmp-destination-embedded <preserve_existing|strip_existing>
- --xmp-destination-sidecar <preserve_existing|strip_existing>

Current bounded writeback contract:

`xmp_writeback_mode`	Edited file	Sibling `.xmp`	Default cleanup behavior
`EmbeddedOnly`	Keep generated XMP in the managed embedded carrier	No generated sidecar output	Preserve any existing sibling `.xmp` unless `xmp_destination_sidecar_mode=StripExisting`
`SidecarOnly`	Suppress generated embedded XMP carriers	Return generated sidecar output	Preserve existing embedded XMP unless `xmp_destination_embedded_mode=StripExisting`
`EmbeddedAndSidecar`	Keep generated XMP in the managed embedded carrier	Return the same generated XMP as sibling `.xmp` output	No sidecar cleanup path is requested

Current behavior:

existing XMP can still be included independently
EXIF payload emission stays independent from EXIF-to-XMP projection
IPTC native carrier emission stays independent from IPTC-to-XMP projection
portable generated XMP can keep the historical mixed order, prefer existing decoded XMP, or prefer generated EXIF/IPTC mappings when the same portable property would collide
existing sibling .xmp sidecars from the destination path can be merged into generated portable XMP before transfer packaging when explicitly requested
that sidecar merge path now has explicit precedence against source-embedded existing XMP instead of relying on implicit decode order
existing embedded XMP from the destination file can also be merged into generated portable XMP on the file-read/prepare path and on the file-helper path when explicitly requested
that destination-embedded merge path has its own explicit precedence against source-embedded existing XMP instead of relying on implicit decode order
some targets without a native IPTC carrier can still use XMP as the bounded fallback carrier when IPTC projection is enabled
file-helper export can now strip prepared embedded XMP blocks and return canonical sidecar output guidance instead
file-helper export can also keep generated embedded XMP while emitting the same generated packet as a sibling .xmp sidecar
the public metatransfer CLI and Python transfer wrapper can now persist that generated XMP as a sibling .xmp sidecar when sidecar or dual-write XMP writeback is selected
the public metatransfer CLI and Python transfer wrapper now also expose the bounded destination-embedded merge and precedence controls directly
sidecar-only writeback now has an explicit destination embedded-XMP policy:
- preserve existing embedded XMP by default
- strip existing embedded XMP for jpeg, tiff, png, webp, jp2, and jxl
embedded-only writeback now has an explicit destination sidecar policy:
- preserve an existing sibling .xmp by default
- strip an existing sibling .xmp when explicitly requested
the C++ API now also has a bounded persistence helper for execute_prepared_transfer_file(...) results, so applications can write the edited file, write the generated .xmp sidecar, and remove a stale sibling .xmp without reimplementing wrapper-side file logic
the Python binding now exposes the same persistence path through transfer_file(...) and unsafe_transfer_file(...), and the public Python wrapper uses that core helper instead of maintaining its own sidecar write and cleanup implementation
the Python binding now also exposes the reusable decoded-source path through read_transfer_source_snapshot_file(...), read_transfer_source_snapshot_bytes(...), Document.build_transfer_source_snapshot(), and transfer_snapshot_probe(...) / transfer_snapshot_file(...)
public API regression coverage now asserts dual-write roundtrip and persistence behavior across jpeg, tiff, dng, png, webp, jp2, jxl, heif, avif, and cr3

This is deliberately narrower than a full sync engine. It does not yet define:

full EXIF vs XMP precedence rules
MWG-style reconciliation
full destination embedded-vs-sidecar reconciliation policy beyond the current bounded merge, precedence, carrier-mode, and strip rules
namespace-wide deduplication and normalization rules beyond the current generated-XMP path

Time Patch Plan¶

Time patching is intentionally narrow and fixed-width.

Current model:

build EXIF payloads once
record patch slots in the bundle
patch only the affected bytes during execution

Primary fields:

DateTime
DateTimeOriginal
DateTimeDigitized
SubSecTime*
OffsetTime*

This is meant for fast repeated transfer, not general metadata editing.

Main Blockers¶

1. General edit UX¶

OpenMeta still does not present one fully mature, general-purpose metadata editor across all formats. The current transfer core is real, but still more bounded than ExifTool or Exiv2.

2. Broader EXIF / IPTC / XMP sync policy¶

This remains one of the biggest product gaps for writer adoption, even though the first public projection controls now exist.

Missing pieces include:

conflict resolution rules
broader sidecar vs embedded policy beyond the current bounded writeback mode
canonical writeback policy
broader namespace reconciliation behavior beyond the current bounded custom-namespace preservation control

3. MakerNote-safe rewrite expectations¶

Read parity is strong, but broad rewrite guarantees for vendor metadata are not yet at the level of mature editing tools.

4. EXR depth¶

The architectural question is now how far to deepen the current bounded EXR target:

keep EXR as a backend-emitter target plus bridge helpers, or
add a broader EXR file rewrite/edit path

Recommended Next Priorities¶

Keep transfer ahead of further read-breadth work.
Stabilize the current target family:
- JPEG
- TIFF
- PNG
- WebP
- JP2
- JXL
- bounded BMFF
Decide how deep EXR should go beyond the current bounded target.
Add more transfer-focused roundtrip and compare gates where they improve confidence for adopters.
Add an explicit EXIF / IPTC / XMP sync policy.

Three-Phase Writer Confidence Roadmap¶

This is the public roadmap for closing the main read/transfer/write gaps against mature metadata tools without expanding the project scope into full pixel editing or unbounded arbitrary metadata editing.

Working Rule¶

For the current milestone:

do not add broad new read families before the current writer target family is stable
every new writer behavior should ship with explicit roundtrip and compare gates
prefer one documented bounded contract per target over format-specific hidden behavior

Phase 1: Writer Confidence Baseline¶

Goal:

restore a fully green public tree
make current bounded writer behavior explicit and regression-gated
remove adoption risk caused by ambiguous sync and preservation behavior

Cross-cutting deliverables:

fix all public unit and regression failures before adding further writer breadth
publish one explicit EXIF / IPTC / XMP writeback policy for:
- source-embedded vs destination-embedded precedence
- source-embedded vs destination-sidecar precedence
- canonical generated-XMP writeback rules
- namespace preservation and canonicalization rules
add compare-backed release validation for the current primary target family
document unmanaged-metadata preservation rules for each writer target

Exit criteria:

public test tree is green
public release gates cover read-back plus compare-style validation for the primary target family
writer-side XMP behavior is explicit instead of implementation-defined

Phase 2: Stable First-Class Writer Set¶

Goal:

make the current target family feel consistent across C++, CLI, and Python
raise bounded edit paths into stable first-class writer contracts
improve rewrite safety for vendor metadata without claiming full arbitrary edit parity

Cross-cutting deliverables:

one stable user-facing edit/transfer surface across C++, CLI, and Python
one policy surface for MakerNote, JUMBF, C2PA, EXIF projection, IPTC projection, and XMP carrier behavior
stronger rewrite guarantees for preserve-vs-replace behavior on existing target metadata
compare and roundtrip gates promoted from smoke coverage into release-facing validation for the first-class target family

Exit criteria:

the first-class target family has documented write guarantees and matching regression gates
major host surfaces expose the same bounded policy controls
target maturity differences are reduced to known documented limits instead of accidental behavior

Phase 3: Deeper Parity and Read-Depth Follow-Through¶

Goal:

close the most visible remaining competitor gaps after the primary writer contract is stable
deepen read semantics only where they materially improve writer confidence or interop parity

Cross-cutting deliverables:

deeper modern-container semantics where current bounded projections are too small for parity workflows
long-tail read-depth work for formats that still rely mainly on embedded-TIFF follow paths
broader compare gates for newer target families and long-tail metadata structures

Exit criteria:

remaining gaps are mostly strategic out-of-scope items rather than missing baseline format behavior
OpenMeta can defend a clear public answer for which targets are first-class, bounded, or read-only

Per-Target Deliverables¶

Target family	Phase 1 deliverable	Phase 2 deliverable	Phase 3 follow-up
JPEG	Lock explicit sync/writeback defaults for APP1/APP2/APP13, add compare-backed read-back gates for edit/apply, and document unmanaged-marker preservation	Promote JPEG from strongest target to reference writer contract for other backends, including clearer preserve/replace guarantees for existing metadata carriers	Expand parity coverage for more mixed metadata bundles and signed/unsigned JUMBF handoff workflows where still bounded
TIFF	Lock rewrite guarantees for root IFD, `ExifIFD`, preview-page chains, and bounded `SubIFD` replacement; add compare-backed roundtrip gates for classic TIFF and BigTIFF	Raise current bounded rewrite behavior into a stable first-class contract, including clearer preserve/replace rules for existing auxiliary chains and downstream tails	Broaden nested-IFD graph handling only where it improves practical export parity without claiming arbitrary graph rewrite
DNG	Lock explicit behavior for `ExistingTarget`, `TemplateTarget`, and `MinimalFreshScaffold`; add compare-backed roundtrip gates for `DNGVersion`, preview chains, and raw `SubIFD` merge behavior	Stabilize the DNG policy layer so hosts can rely on predictable preserve/merge behavior without the Adobe SDK path	Decide whether any additional DNG-specific rewrite depth is worth public contract expansion beyond the TIFF-derived bounded model
PNG	Lock chunk replacement rules for `eXIf`, XMP `iTXt`, and `iCCP`; add compare-backed roundtrip gates for embedded-only, sidecar-only, and dual-carrier XMP flows where applicable	Promote the current bounded chunk path into a stable managed-metadata editor with explicit preservation rules for unrelated chunks	Add deeper parity only if compare workflows show recurring gaps against major tools
WebP	Lock replacement rules for `EXIF`, `XMP`, `ICCP`, and bounded `C2PA`; add compare-backed roundtrip gates	Promote the current bounded RIFF metadata path into a stable managed-metadata editor with explicit preservation guarantees for unrelated chunks	Extend only where public parity data shows material gaps for common WebP metadata workflows
JP2	Lock top-level managed-box rewrite rules and `colr` replacement behavior; add compare-backed roundtrip gates	Promote bounded box rewrite into a stable JP2 metadata contract with explicit preserve/replace guarantees for unmanaged boxes	Revisit `jp2h` synthesis only if it becomes necessary for common export parity
JXL	Lock current box rewrite rules for `Exif`, `xml`, `jumb`, bounded `c2pa`, and encoder-side ICC handoff; add compare-backed roundtrip gates for edit/apply paths	Promote JXL from bounded but real to a stable first-class metadata target with explicit unmanaged-box preservation rules and clearer encoder/file-edit split	Add more `brob` realtype coverage only after the current direct and bounded compressed routes are stable
HEIF / AVIF / CR3	Lock the bounded metadata-only `meta` edit contract, item/property preservation rules, and compare-backed roundtrip gates	Stabilize the bounded BMFF writer contract for metadata items, ICC property handling, and existing OpenMeta-authored `meta` replacement	Deepen BMFF scene semantics and relation modeling where current bounded fields are too small for parity workflows
EXR	Decide whether the public target remains an attribute-emitter contract or grows into a file rewrite/edit path; add compare-backed gates for the chosen contract	If EXR stays bounded, make that contract final and explicit across C++, CLI, and Python; if it grows, define one narrow first-class rewrite scope and gate it	Add depth only after the architectural choice is settled; avoid half-bounded expansion
RAF / X3F	Keep RAF header-declared preview-JPEG EXIF/XMP discovery, FujiIFD/TIFF follow path, RAF header/directory geometry decode, RAFData geometry projection, standalone XMP fallback, rendered-transfer dropping of native RAF source fields, and X3F header/PROP/section-JPEG reads stable with focused compare coverage	Only add read depth that directly improves downstream transfer/export confidence	Deepen remaining RAF model-specific tables and X3F image-processing sections if parity evidence shows real user-facing gaps
CRW / CIFF	Keep the current bounded native CIFF projection stable and well-gated	Improve only the parts that materially affect interop or transfer workflows	Revisit deeper native legacy coverage if it becomes a recurring parity blocker
Photoshop IRB	Keep raw preservation stable and add compare coverage for the current interpreted subset	Expand interpreted subset only where it improves practical writer parity	Revisit broader Photoshop-resource parity after the first-class writer set is stable
JUMBF / C2PA	Keep bounded preserve/invalidate behavior deterministic and regression-gated	Improve public signer-handoff and bounded rewrite workflows without claiming full trust-policy parity	Revisit deeper semantics and signed rewrite coverage after the main writer contract is stable

Phase Ordering Summary¶

Fix public regressions and lock the sync/writeback contract.
Turn the current target family into a stable first-class writer set.
Spend follow-up effort on deeper parity lanes only after the writer baseline is trustworthy.

Competitor Parity Checklist¶

This section is a practical tracking view for the remaining gap against general-purpose metadata competitors.

Estimated remaining work packages:

to reach normal still-image workflow parity close to Exiv2: about 8 major work packages
to reach broader overall parity closer to ExifTool: about 12-15 major work packages

These are not release-percentage numbers. They are rough planning counts for distinct parity workstreams that still matter after the current public writer contract work.

Package Status¶

Status legend:

Done: public contract and regression coverage are good enough that this is no longer a primary parity blocker
Partial: real support exists, but competitor-visible limits still remain
Missing: still a clear parity gap

Work package	Why it matters for parity	Status	Remaining package count	Main target families
Public writer contract for primary targets	Competitors feel predictable on preserve/replace behavior; OpenMeta still needs that same trust level across all first-class targets	`Partial`	`1`	`TIFF`, `DNG`, `PNG`, `WebP`, `JP2`, `JXL`, `HEIF/AVIF/CR3`
General EXIF / IPTC / XMP sync engine	One of the biggest remaining gaps for general editing adoption	`Partial`	`1-2`	Cross-cutting
Compare-backed release validation	Needed to defend parity claims with repeatable read-back and compare gates	`Partial`	`1`	Cross-cutting
MakerNote rewrite trust	Read parity is strong, but rewrite guarantees still trail mature tools	`Partial`	`1`	`JPEG`, `TIFF`, `DNG`, RAW-derived lanes
TIFF / DNG deeper rewrite guarantees	Important for serious export/edit trust on camera-originated files	`Partial`	`1`	`TIFF`, `DNG`
BMFF writer depth beyond current bounded contract	Needed for stronger `HEIF/AVIF/CR3` parity beyond the current metadata-only `meta` model	`Partial`	`1`	`HEIF`, `AVIF`, `CR3`
Modern container read-depth follow-through	Remaining visible read gaps are mostly here	`Partial`	`1`	`HEIF/AVIF`, `JXL`
Long-tail native format semantics	Matters more against `ExifTool` than against `Exiv2`	`Partial`	`2-3`	`RAF`, `X3F`, `CRW/CIFF`, `Photoshop IRB`
EXR target decision	Current EXR target is real but still architecturally bounded	`Partial`	`1`	`EXR`
JUMBF / C2PA deeper semantics	Current support is bounded and useful, but not full trust-policy parity	`Partial`	`1-2`	`JPEG`, `PNG`, `WebP`, `JXL`, `BMFF`
Full arbitrary metadata editing parity	Mature competitors expose a broader open-ended editor surface	`Missing`	Strategic / out of scope	Cross-cutting

Format-Family Gap Map¶

This map is intentionally coarse. It answers where the main remaining work still sits after the current public regression and writer-contract work.

Format family	Read parity	Transfer/write parity	Main remaining competitor gap
`JPEG`	`Strong`	`Strong`	needs continued compare-backed hardening and deeper mixed-bundle parity, not a new baseline writer
`TIFF`	`Strong`	`Partial`	deeper rewrite guarantees for more existing-graph and tail-preservation cases
`DNG`	`Strong`	`Partial`	more predictable preserve/merge behavior across target modes and raw `SubIFD` chains
`PNG`	`Strong`	`Partial`	stable unmanaged-chunk preservation contract and broader compare-backed validation
`WebP`	`Strong`	`Partial`	stable unrelated-chunk preservation contract and broader compare-backed validation
`JP2`	`Strong`	`Partial`	stronger managed-box preservation guarantees and more roundtrip validation
`JXL`	`Strong` on current lanes	`Partial`	more explicit box-preservation guarantees and deeper `brob` realtype follow-through
`HEIF / AVIF / CR3`	`Strong` on tracked lanes	`Partial`	BMFF writer depth and deeper scene/relation semantics beyond the bounded current model
`EXR`	`Bounded but real`	`Bounded but real`	still needs an explicit long-term decision between stable bounded target vs rewrite/edit path
`RAF / X3F`	`Partial`	not a main writer lane	deeper RAF model-specific native tables and X3F image-processing sections beyond current carrier/header/property lanes
`CRW / CIFF`	`Partial`	bounded	legacy native depth still trails mature tools
`Photoshop IRB`	`Partial`	bounded preservation	interpreted subset still smaller than mature tools
`JUMBF / C2PA`	`Partial`	bounded	deeper semantics, trust-policy behavior, and signed rewrite parity remain out of scope

Practical Readout¶

If OpenMeta stops after the current writer-contract work, it can already argue that it is close to competitor parity on the main tracked still-image targets.

The latest read-gap closure added RAF preview-JPEG EXIF/XMP discovery before the native FujiIFD/raw section and kept native RAF fields in the rendered-image safety drop set. This closes a common competitor-visible RAF read gap without making RAF a rendered-output writer lane.

To get materially closer to Exiv2, the remaining work is mostly:

finish stable writer guarantees for the first-class target family
finish the broader sync policy
harden compare-backed release validation
improve TIFF/DNG/BMFF rewrite trust

To get materially closer to ExifTool, OpenMeta also needs:

more long-tail native format depth
broader general editing behavior
deeper JUMBF/C2PA semantics
a clearer answer for EXR

Execution Order¶

Use this as the practical delivery order for the remaining parity work.

Priority legend:

Now: should be in the next active delivery slice
Next: should start after the Now slice is stable
Later: important for broader parity, but not the next blocker

Work package	Priority	Why this order
Public writer contract for primary targets	`Now`	This is the core trust gap that still keeps OpenMeta below mature writer parity
General EXIF / IPTC / XMP sync engine	`Now`	This is still one of the biggest adoption blockers for general edit workflows
Compare-backed release validation	`Now`	Parity claims remain weaker until compare-backed gates are release-facing instead of mostly API-facing
TIFF / DNG deeper rewrite guarantees	`Now`	This is the highest-risk writer lane for serious still-image export confidence
BMFF writer depth beyond current bounded contract	`Next`	`HEIF/AVIF/CR3` are already real targets, but the bounded writer model still needs more depth for stronger parity
MakerNote rewrite trust	`Next`	Important for trust, but it benefits from the writer-contract and validation work landing first
Modern container read-depth follow-through	`Next`	Visible gap, but less urgent than finishing the current writer baseline
EXR target decision	`Next`	Needs an explicit product choice, but should follow the main writer-contract stabilization work
Long-tail native format semantics	`Later`	Matters more for broad `ExifTool` parity than for the first still-image writer milestone
JUMBF / C2PA deeper semantics	`Later`	Current bounded behavior is already useful; deeper trust semantics should wait until the core writer contract is stable
Full arbitrary metadata editing parity	`Later`	Strategic follow-up, not part of the next parity-closing milestone

Suggested delivery sequence:

Finish the stable writer contract for the first-class target family.
Finish the broader sync-policy layer and compare-backed release validation.
Harden the two highest-risk writer lanes: TIFF/DNG and bounded BMFF.
Revisit MakerNote rewrite trust after the first-class writer contract is stable.
Spend follow-up time on modern-container depth, EXR, and long-tail native semantics only after the main writer baseline is defendable.

Now Slice Implementation Board¶

This board turns the current Now slice into concrete delivery checklists.

The sync item here means the bounded next-slice policy completion needed for practical writer parity. It does not mean full arbitrary EXIF/IPTC/XMP sync parity across every workflow.

1. Public Writer Contract For Primary Targets¶

[x] document final preserve-vs-replace behavior for existing embedded XMP on TIFF, DNG, PNG, WebP, JP2, JXL, and bounded BMFF
[x] document final preserve-vs-replace behavior for destination sidecars across embedded-only, sidecar-only, and dual-write flows
[x] lock explicit unmanaged-metadata preservation rules for unrelated chunks, boxes, items, and tails per target family
[x] add compare-backed read-back gates for each first-class target instead of relying mainly on API-shape regression coverage
[x] make CLI and Python surfaces describe the same writeback behavior and path-derivation rules as the C++ helper
[x] reduce remaining target differences to documented limits instead of accidental implementation details

Evidence: docs/writer_target_contract.md defines per-target preserve/replace rules and the remaining bounded limits. The BMFF section now makes the item-id width rule explicit: supported foreign iloc version 0/1 graphs can be upgraded to output iloc version 2 when inserted metadata needs 32-bit item IDs, while unsupported graph shapes or exhausted 32-bit ID space still fail safely.

2. Bounded EXIF / IPTC / XMP Sync Layer¶

[x] publish one final precedence table for source embedded XMP, destination embedded XMP, and destination sidecar XMP
[x] lock conflict behavior for generated EXIF-to-XMP and IPTC-to-XMP projections when existing XMP is also present
[x] lock canonical generated-XMP writeback behavior for embedded-only, sidecar-only, and dual-write flows
[x] lock namespace preservation and canonicalization rules for managed vs unmanaged XMP content
[x] add regression cases for mixed embedded-plus-sidecar destination states across the primary target family
[x] document the explicit non-goals of this bounded sync layer so it is not confused with full arbitrary sync parity

Evidence: docs/xmp_sync_policy.md now defines the bounded public policy, including carrier precedence, generated-vs-existing conflict behavior, writeback modes, namespace handling, and non-goals. The release-facing transfer tests cover source/destination carrier precedence, generated EXIF/IPTC versus existing XMP conflicts, canonical managed namespace replacement, and persisted embedded/sidecar writeback across the primary writer target family.

3. Compare-Backed Release Validation¶

[x] promote the current primary-target roundtrip checks into explicit release-facing compare gates
[x] add compare-backed validation for TIFF, DNG, PNG, WebP, JP2, JXL, and bounded BMFF target outputs, including fail-safe rejection for unsupported foreign top-level meta BMFF shapes
[x] cover embedded-only, sidecar-only, and dual-write XMP flows in release-facing compare validation
[x] add compare-backed validation for explicit sidecar-base overrides and destination-sidecar cleanup behavior
[x] gate the primary writer family on deterministic read-back of managed metadata after edit/apply
[x] keep public parity claims tied to compare-backed evidence instead of only unit or smoke coverage

Evidence: this plan keeps parity language at the supported-lane level and ties release claims to openmeta_gate_transfer_release, compatibility-dump read-back, and image-usability gates. BMFF high-item-ID insertion is covered by a release-gated API roundtrip that writes into an iloc v2 graph and scans the result back as one Exif item and one XMP item.

4. TIFF / DNG Deeper Rewrite Guarantees¶

[x] lock rewrite guarantees for classic TIFF and BigTIFF root IFD, ExifIFD, preview chains, and bounded SubIFD replacement
[x] lock explicit DNG behavior for ExistingTarget, TemplateTarget, and MinimalFreshScaffold
[x] add compare-backed roundtrip gates for preview chains, raw SubIFD merge behavior, and DNGVersion persistence
[x] document preserve-vs-replace guarantees for existing auxiliary IFD chains and downstream tails
[x] harden read-back and rewrite tests around mixed existing metadata carriers on camera-like TIFF/DNG files
[x] define the bounded edge of TIFF/DNG rewrite depth clearly enough that hosts know what is guaranteed and what is not

Evidence: docs/writer_target_contract.md defines the bounded TIFF/DNG rewrite contract and DNG target-mode behavior. Release-facing compatibility-dump tests now cover classic TIFF, DNG, and BigTIFF DNG-style merge outputs with preview-tail preservation, SubIFD auxiliary-tail preservation, existing root/preview/SubIFD XMP carrier replacement, embedded-versus-sidecar precedence, and DNGVersion read-back.

Done-When Readout¶

[x] the first-class target family has one explicit public writer contract
[x] the bounded sync-policy layer is documented and regression-gated
[x] release-facing compare validation covers the main still-image writer set
[x] TIFF/DNG rewrite guarantees are strong enough to stop being a primary parity blocker
[x] the next work slice can move to bounded BMFF depth instead of still backfilling the writer baseline

Host Integration And Adoption Backlog¶

This backlog captures adoption-oriented work that supports host projects with flat metadata models and deferred output writes. It should not replace the writer-confidence slice above; it should be sequenced around it.

Near-Term Host Contract Work¶

[x] add a small runtime capability query API for read, structured decode, transfer preparation, and target edit support by format and metadata family
[x] mark public host-facing APIs with stability levels such as stable, experimental, or internal; start with visit_metadata(...), snapshot read/build, fileless execution, and bundle execution
[x] publish the generic FlatHost mapping contract: name style, duplicate handling, type projection, deterministic ordering, and namespace behavior
[x] add a deterministic compatibility dump for names, values, scalar types, origins, and transfer/writeback decisions so downstream tests can avoid binary-packet baselines
[x] document final conflict and precedence decisions for generated EXIF/XMP, IPTC/XMP, source embedded XMP, destination embedded XMP, and destination sidecar XMP

Medium-Term Fidelity Work¶

[x] add an opt-in raw-preserving TransferSourceSnapshot mode that keeps original carrier provenance and bounded payload bytes alongside decoded MetaStore state
[x] preserve bounded per-carrier provenance in raw snapshots: container type, block kind, byte range, original order, and route identity
[x] connect decoded entries back to the raw carrier records they were derived from, using snapshot-local decoded entry ids
[x] define policy choices for raw passthrough vs decoded re-emission when the destination container can safely accept either form
[x] add a diagnostic raw-carrier passthrough audit that reports candidate carriers and primary block reasons before any raw passthrough writer path is enabled
[x] add the first opt-in snapshot raw passthrough writer path for eligible non-C2PA JUMBF and draft unsigned C2PA invalidation carriers
[ ] provide versioned snapshot serialization only after the raw/provenance model is settled
[ ] provide full prepared-bundle serialization if hosts need to prepare once and apply later to encoded target bytes

Supporting Work¶

[ ] improve structured diagnostics with severity, stable code, carrier/family, offset or byte range where available, and short host-facing messages
[ ] extend resource accounting beyond current hard limits with preflight estimates for prepared transfers, sidecar output, and serialized snapshots
[ ] add clean-room public micro fixtures for host integration tests; do not vendor large binary assets, third-party source drops, or scraped/spec text
[ ] add examples for read bytes -> snapshot -> target bytes -> edited bytes and visit_metadata(...) -> flat host attribute list
[ ] consider a bounded random-access IO callback only after bytes/file APIs and raw snapshot serialization are stable
[ ] defer any C ABI or opaque-handle facade until the host-facing C++ API is stable enough to freeze a narrow bridge

Raw Snapshot Emission Policy¶

Raw carriers are preserved for provenance, diagnostics, and opt-in bounded passthrough decisions. Transfer preparation still defaults to decoded re-emission from MetaStore.

raw_carrier_passthrough_audit_from_snapshot(...) is the current diagnostic bridge between preserved carriers and emission policy. It reports whether each preserved carrier is a passthrough candidate for a target format, or blocked by missing payload bytes, target carrier incompatibility, active safety filtering, content-bound C2PA, explicit profile policy, missing decoded entry links, or unsupported carrier kind. The audit itself does not change bundle preparation; it is a preflight tool for host UI and test coverage.

The planned policy choices are:

DecodedReemit: current behavior; OpenMeta decodes entries, applies safety filtering, and emits freshly prepared EXIF/XMP/ICC/IPTC/JUMBF carriers.
RawPassthroughWhenSafe: opt-in behavior through TransferRawCarrierPassthroughMode::WhenSafe; OpenMeta may reuse a preserved raw carrier only when the target accepts the same carrier family, the payload was preserved in the snapshot, and the active transfer safety/profile does not require filtering, invalidation, or target-owned image-property rewrite. The current writer path is intentionally narrow: non-C2PA JUMBF and OpenMeta draft unsigned C2PA invalidation carriers can be reused for JPEG, JXL, and BMFF targets, and draft unsigned C2PA invalidation carriers can be reused for WebP. EXIF/XMP/ICC/IPTC still use decoded re-emission.
HostOwnedPassthrough: current integration escape hatch; hosts may inspect TransferSourceSnapshot::raw_carriers and implement their own passthrough outside OpenMeta’s writer path.

Rendered-image transfer keeps using decoded re-emission plus safety filtering. Opaque MakerNotes, content-bound C2PA, source ICC profiles, raw color calibration, and target-owned image properties are not raw-passthrough candidates for rendered exports.

Postponed Work¶

Still out of scope for the current milestone:

full arbitrary metadata editing parity
full C2PA signed rewrite / trust-policy parity
full EXIF / IPTC / XMP sync engine
broad TIFF/DNG and BMFF rewrite parity beyond the bounded current targets
mandatory raw-passthrough snapshots or snapshot serialization in the default read path
C ABI / opaque-handle stability commitments

Practical Summary¶

OpenMeta is no longer blocked by read-path quality for adoption-oriented transfer work.

The main opportunity now is to make the current bounded transfer core easier to use and easier to trust across the primary export targets, instead of continuing to expand read-only surface area first.

page Quick Start

This guide is for the normal OpenMeta use case: a C++ application that needs to read, query, prepare, and transfer image metadata.

OpenMeta is a metadata engine, not an image encoder. In practice that means:

read metadata from an existing file
query it through MetaStore
build new metadata entries when needed
inject metadata into an existing target file or template
prepare metadata artifacts for a host API such as EXR or another host-owned metadata layer

If you need the full support matrix, see metadata_support.md. If you need the detailed target contract, see metadata_transfer_plan.md.

If you already own the encoder or host API, see host_integration.md. For public API adoption status, see api_stability.md. For the stable flat host naming contract, see flat_host_mapping.md. For deterministic host compatibility baselines, see compatibility_dump.md. For generated XMP merge and writeback precedence, see xmp_sync_policy.md. For per-target writer preserve/replace guarantees, see writer_target_contract.md.

1. Add OpenMeta To Your CMake Project¶

If OpenMeta is installed as a package:

find_package(OpenMeta CONFIG REQUIRED)

add_executable(my_app main.cc)
target_link_libraries(my_app PRIVATE OpenMeta::openmeta)

If you build OpenMeta from source in the same workspace, any normal add_subdirectory(...) or install-and-find-package workflow is fine. The public target alias is OpenMeta::openmeta.

2. Build OpenMeta¶

Library and tools:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

Tests:

cmake -S . -B build-tests -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DOPENMETA_BUILD_TESTS=ON
cmake --build build-tests
ctest --test-dir build-tests

If your optional dependencies live in a custom prefix, pass that prefix through CMAKE_PREFIX_PATH.

Optional Adobe DNG SDK bridge:

cmake -S . -B build-dng -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DOPENMETA_WITH_DNG_SDK_ADAPTER=ON \
  -DOPENMETA_USE_LIBCXX=ON \
  -DCMAKE_PREFIX_PATH='<dng-sdk-prefix>;<deps-prefix>'
cmake --build build-dng

3. Read One File Into <tt>MetaStore</tt>¶

This is the basic C++ read path.

#include "openmeta/simple_meta.h"

#include <array>
#include <cstddef>
#include <span>
#include <vector>

std::vector<std::byte> file_bytes = load_file_somehow("file.jpg");

openmeta::MetaStore store;
std::array<openmeta::ContainerBlockRef, 256> blocks {};
std::array<openmeta::ExifIfdRef, 512> ifds {};
std::vector<std::byte> payload(1 << 20);
std::array<uint32_t, 1024> payload_indices {};

openmeta::SimpleMetaDecodeOptions options;
const openmeta::SimpleMetaResult read = openmeta::simple_meta_read(
    std::span<const std::byte>(file_bytes.data(), file_bytes.size()),
    store,
    blocks,
    ifds,
    payload,
    payload_indices,
    options);

store.finalize();

Notes:

simple_meta_read(...) appends decoded entries to MetaStore.
Call store.finalize() before exact-key lookups.
The caller owns the scratch buffers. That is intentional.

4. Query Metadata¶

Use exact-key lookup through MetaStore::find_all(...) when you already know the metadata family and key:

#include "openmeta/meta_key.h"
#include "openmeta/meta_store.h"

openmeta::MetaKeyView make_key;
make_key.kind = openmeta::MetaKeyKind::ExifTag;
make_key.data.exif_tag.ifd = "ifd0";
make_key.data.exif_tag.tag = 0x010F;  // Make

for (openmeta::EntryId id : store.find_all(make_key)) {
    const openmeta::Entry& entry = store.entry(id);
    // Inspect entry.value and entry.origin here.
}

Use exact keys for:

EXIF tags
XMP properties
EXR attributes
ICC tags
IPTC datasets

For semantic inspection UI, use openmeta/metadata_query.h. It reports raw matches plus normalized candidates for areas such as crop/active-area, exposure/gain, white balance, color/profile, lens correction, orientation, and RAW-processing metadata. Color-profile matches include EXIF color-space evidence, ICC header/tag entries, XMP ICC/profile/color-space fields, and PNG profile text carriers. Source-bound camera RAW profile, look, tone-curve, and style metadata is reported separately as source_color_transform, so hosts can inspect it without treating it as a portable ICC/profile value. query_descriptive_metadata(...) also exposes a bounded EXIF/IPTC/XMP reconciliation view for common descriptive fields: title/headline, description/caption, creator/author, and keywords/subject. These helpers use deterministic built-in name/tag matching by default. If OpenMeta is configured with -DOPENMETA_ENABLE_RAPIDFUZZ=ON, the same query helpers also use RapidFuzz to match near-miss property names such as misspelled crop/border/padding paths. Every raw query match carries exact_match, fuzzy_match, and fuzzy_score fields, so inspection UI can label near-miss results separately from exact tag/name hits.

For vendor MakerNote/RAW fields, the query layer also builds conservative per-family grouped candidates for related white-balance, source-color-transform, raw-storage, sensor, computational, thermal, stitch/panorama, and source-processing records. These records are for inspection and safe-transfer policy, not for writing source RAW transforms into rendered outputs. Grouped color, white-balance, and lens-correction records require numeric payloads with conservative minimum shapes before they become matrix/vector/table candidates. Malformed or text-only source records still remain visible as per-entry metadata, but they are not promoted into normalized grouped records. Known geometry patterns can also become normalized rectangles; current public coverage includes DNG crop/active-area tags, Phase One/Leaf RAW geometry, and Fujifilm RAF raw crop/zoom fields, plus Canon, Nikon Capture, and Sony panorama crop/border patterns.

Call metadata_query_fuzzy_search_available() when a UI wants to expose that the stronger fuzzy matcher is compiled in.

For structured interpretation output, use openmeta/metadata_interpretation.h. It projects semantic query candidates into records that carry the query class, semantic kind, normalized shape, confidence, source entry ids, and normalized 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, exposure/gain, color/profile, GPS, geometry, lens correction, and RAW-processing. 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, normalized exposure values, full normalized value vectors for grouped matrix/vector/table concepts, transfer hints, compatible/rendered safety booleans, and same-role conflict flags so host UI can show ambiguity instead of guessing silently. Transfer hints use safe, source_bound, rendered_unsafe, or requires_target_image_spec to separate portable facts from source RAW/correction data and target-owned image facts. transfer_concept_diagnostics_from_store(...) applies those hints to a selected transfer safety mode and returns keep/drop/requires-target-image-spec actions, severity tokens, and default message text for transfer-preview UI. Rendered-transfer drop messages distinguish source color transforms, white balance, lens correction, source-bound RAW processing, and target-owned image properties. Source color transforms cover camera RAW profiles, looks, tone curves, and vendor style/rendering tables that should not be treated as portable rendered-image color profiles. Source-bound RAW processing diagnostics also keep computational, thermal, and stitch/panorama roles separate for UI policy messages. GPS altitude reference codes can be displayed with metadata_concept_gps_altitude_reference_name(...).

For user-facing orientation display, use openmeta/orientation.h instead of showing only the numeric EXIF/TIFF index. interpret_exif_orientation(...) returns the index, human-readable label, clockwise rotation degrees, mirrored state, width/height-swap flag, and nearest rotation-only orientation.

For common enum-like TIFF/EXIF/DNG numeric values, and selected bounded Canon/Nikon MakerNote contexts, use openmeta/exif_value_names.h. Unknown values return an empty string and remain available as numeric MetaStore values.

5. Build A <tt>MetaStore</tt> Manually¶

This is useful when your application creates or edits metadata directly.

#include "openmeta/meta_key.h"
#include "openmeta/meta_store.h"
#include "openmeta/meta_value.h"

openmeta::MetaStore store;

const openmeta::BlockId block = store.add_block(openmeta::BlockInfo {});

openmeta::Entry make_entry;
make_entry.key = openmeta::make_exif_tag_key(store.arena(), "ifd0", 0x010F);
make_entry.value = openmeta::make_text(
    store.arena(), "Vendor", openmeta::TextEncoding::Ascii);
make_entry.origin.block = block;
make_entry.origin.order_in_block = 0;

store.add_entry(make_entry);
store.finalize();

The key/value helpers live in:

6. Export XMP From <tt>MetaStore</tt>¶

For portable sidecar output:

#include "openmeta/xmp_dump.h"

std::vector<std::byte> xmp_bytes;
openmeta::XmpSidecarRequest request;
request.format = openmeta::XmpSidecarFormat::Portable;
request.include_exif = true;
request.include_iptc = true;

const openmeta::XmpDumpResult dump =
    openmeta::dump_xmp_sidecar(store, &xmp_bytes, request);

For lossless OpenMeta-native sidecars, switch request.format to XmpSidecarFormat::Lossless.

7. Copy Metadata Into An Existing Target File¶

This is the common export workflow:

one source file provides metadata
one target file or template already owns the pixel container
OpenMeta edits the target metadata

#include "openmeta/metadata_transfer.h"

openmeta::ExecutePreparedTransferFileOptions options;
options.prepare.prepare.target_format = openmeta::TransferTargetFormat::Jpeg;
options.prepare.prepare.profile.safety =
    openmeta::TransferSafetyMode::RenderedImage;
options.edit_target_path = "rendered.jpg";

const openmeta::ExecutePreparedTransferFileResult exec =
    openmeta::execute_prepared_transfer_file("source.jpg", options);

openmeta::PersistPreparedTransferFileOptions persist;
persist.output_path = "rendered_with_meta.jpg";
persist.overwrite_output = true;

const openmeta::PersistPreparedTransferFileResult saved =
    openmeta::persist_prepared_transfer_file_result(exec, persist);

Use the same pattern for other file-backed targets:

TransferTargetFormat::Tiff
TransferTargetFormat::Dng
TransferTargetFormat::Png
TransferTargetFormat::Webp
TransferTargetFormat::Jp2
TransferTargetFormat::Jxl
bounded BMFF targets such as Heif, Avif, and Cr3

Read Once And Reuse Later¶

If your application already decoded source metadata earlier, keep a decoded source snapshot and execute the later save without reopening the source file:

#include "openmeta/metadata_transfer.h"

const openmeta::ReadTransferSourceSnapshotFileResult snapshot =
    openmeta::read_transfer_source_snapshot_file("source.jpg");

openmeta::ExecutePreparedTransferSnapshotOptions options;
options.prepare.target_format = openmeta::TransferTargetFormat::Tiff;
options.edit_target_path      = "target.tif";
options.execute.edit_apply    = true;

const openmeta::ExecutePreparedTransferFileResult result =
    openmeta::execute_prepared_transfer_snapshot(
        snapshot.snapshot, options);

Python exposes the same reusable snapshot flow for host code:

from pathlib import Path

import openmeta

snapshot_info = openmeta.read_transfer_source_snapshot_file("source.jpg")
snapshot = snapshot_info["snapshot"]

result = openmeta.transfer_snapshot_probe(
    snapshot,
    target_format=openmeta.TransferTargetFormat.Tiff,
    edit_target_path="target.tif",
    target_bytes=Path("target.tif").read_bytes(),
)

By default, source snapshots are decoded-store-backed. They are meant for the common EXIF/XMP/ICC/IPTC transfer workflow, where OpenMeta re-emits decoded metadata after applying the selected safety policy. If a host needs provenance for a later passthrough policy decision, enable ReadTransferSourceSnapshotFileOptions::preserve_raw_carriers or pass preserve_raw_carriers=True in Python. The snapshot then keeps bounded raw carrier records with original ContainerBlockRef ranges, route hints, and payload bytes up to max_raw_carrier_bytes. Each carrier also reports the snapshot-local decoded entry ids attributed to it. Transfer still uses decoded re-emission by default. Use raw_carrier_passthrough_audit_from_snapshot(...) to preflight which preserved carriers are candidates for a target format and which are blocked by missing payloads, target incompatibility, active safety filtering, content-bound C2PA, explicit profile policy, missing decoded entry links, or an unsupported carrier kind. Python exposes the same check as snapshot.raw_carrier_passthrough_audit(...). To allow the bounded passthrough path during snapshot preparation, set PrepareTransferRequest::raw_carrier_passthrough_mode to TransferRawCarrierPassthroughMode::WhenSafe, or pass raw_carrier_passthrough_mode=openmeta.TransferRawCarrierPassthroughMode.WhenSafe to Python snapshot transfer helpers. The current passthrough emitter is deliberately narrow: it can reuse eligible non-C2PA JUMBF and OpenMeta draft unsigned C2PA invalidation carriers for JPEG, JXL, and BMFF targets, plus draft unsigned C2PA invalidation carriers for WebP. EXIF/XMP/ICC/IPTC still use decoded re-emission. If the host owns the final file write path, the lower-level prepare_metadata_for_target_snapshot(...) entry point remains available. If the host already has a decoded MetaStore, build a reusable snapshot with build_transfer_source_snapshot(store). If it already owns the source bytes in memory, use read_transfer_source_snapshot_bytes(bytes) instead of the file-path reader. In Python, if the host already has doc = openmeta.read(...), call doc.build_transfer_source_snapshot() or openmeta.build_transfer_source_snapshot(doc) instead of reopening the file. If it also owns the destination bytes in memory, call the overload execute_prepared_transfer_snapshot(snapshot, target_bytes, options). If it already holds a prepared bundle, use execute_prepared_transfer_bundle(bundle, target_bytes, options) instead. Snapshot execution supports the same existing-sidecar merge and destination carrier-precedence controls as the file helper; when loading an existing sidecar it defaults to edit_target_path unless xmp_existing_sidecar_base_path is set explicitly. For embedded-only writeback with sidecar cleanup and no filesystem path, set xmp_existing_destination_sidecar_state explicitly so OpenMeta can return a cleanup decision without guessing a sidecar location. The Python snapshot helpers intentionally cover the core transfer/edit/persist path. The older transfer_probe(...) / unsafe_transfer_probe(...) entry points remain the broader artifact-dump/debug surface.

8. Check Runtime Capabilities¶

Use the capability API before enabling format/family operations in a host UI or integration layer.

#include "openmeta/metadata_capabilities.h"

const openmeta::MetadataCapability cap = openmeta::metadata_capability(
    openmeta::TransferTargetFormat::Avif,
    openmeta::MetadataCapabilityFamily::Xmp);

if (openmeta::metadata_capability_available(cap.target_edit)) {
    // The current build can edit AVIF XMP within the reported support level.
}

Each operation reports unsupported, supported, bounded, or disabled. bounded means the capability exists within OpenMeta’s documented contract. disabled is used for compile-time-disabled support such as XMP decode when XML support is not available.

Python exposes the same query:

cap = openmeta.metadata_capability(
    openmeta.TransferTargetFormat.Avif,
    openmeta.MetadataCapabilityFamily.Xmp,
)
print(cap["target_edit_name"])

9. Prepare Metadata For Host-Owned Encoders¶

Some applications do not want a file helper. They already own the encoder or the output container and just want OpenMeta to prepare metadata bytes.

EXR Host API¶

EXR is the cleanest host-adapter example.

#include "openmeta/exr_adapter.h"

openmeta::ExrAdapterBatch batch;
openmeta::BuildExrAttributeBatchFileOptions options;

const openmeta::BuildExrAttributeBatchFileResult result =
    openmeta::build_exr_attribute_batch_from_file(
        "source.jpg", &batch, options);

for (const openmeta::ExrAdapterAttribute& attr : batch.attributes) {
    // Forward attr.name, attr.type_name, and attr.value to your EXR writer.
}

Use this when the host already writes EXR files through OpenEXR or its own EXR code.

Generic Host Metadata Export¶

If your application owns the metadata object model, use the generic traversal API and build the mapping in the host layer.

#include "openmeta/interop_export.h"

class MyMetadataSink final : public openmeta::MetadataSink {
public:
    void on_item(const openmeta::ExportItem& item) noexcept override
    {
        // Map item.name + item.entry into your host metadata object.
    }
};

openmeta::ExportOptions options;
options.style              = openmeta::ExportNameStyle::FlatHost;
options.name_policy        = openmeta::ExportNamePolicy::ExifToolAlias;
options.include_makernotes = true;

MyMetadataSink sink;
openmeta::visit_metadata(store, options, sink);

JPEG / JXL / Other Encoder-Owned Outputs¶

For host-owned encoders, the transfer core exposes two patterns:

implement a backend emitter such as JpegTransferEmitter or JxlTransferEmitter
or build a target-neutral adapter view and consume explicit operations

Minimal JPEG/JXL-style pattern:

#include "openmeta/metadata_transfer.h"

openmeta::PrepareTransferFileOptions prepare;
prepare.prepare.target_format = openmeta::TransferTargetFormat::Jxl;

openmeta::PrepareTransferFileResult prepared =
    openmeta::prepare_metadata_for_target_file("source.jpg", prepare);

openmeta::PreparedTransferExecutionPlan plan;
openmeta::compile_prepared_transfer_execution(
    prepared.bundle, openmeta::EmitTransferOptions {}, &plan);

// Then either:
// - implement openmeta::JxlTransferEmitter and call
//   emit_prepared_transfer_compiled(...)
// - or build_prepared_transfer_adapter_view(...) and feed the ops into your
//   own backend abstraction

OpenMeta does not currently ship a TurboJPEG-specific wrapper, but the JPEG transfer path is designed for that kind of integration through JpegTransferEmitter and the adapter-view APIs.

For fuller C++ host-side examples, see host_integration.md.

10. Optional Adobe DNG SDK Bridge¶

If OpenMeta was built with OPENMETA_WITH_DNG_SDK_ADAPTER=ON, you can update an existing DNG file through the Adobe SDK bridge:

#include "openmeta/dng_sdk_adapter.h"

openmeta::ApplyDngSdkMetadataFileResult result =
    openmeta::update_dng_sdk_file_from_file("source.jpg", "target.dng");

This is for applications that already use the Adobe DNG SDK. It is not a raw image encoder.

11. CLI And Python Are Convenience Layers¶

The CLI and Python bindings are useful, but they are thin layers over the same public C++ APIs.

Transfer writeback follows the C++ file-helper contract. With --output, generated sidecar paths are derived from the output path, not from the input or target path. --xmp-writeback sidecar suppresses generated embedded XMP and writes the generated packet as output-stem.xmp. --xmp-writeback embedded_and_sidecar writes both carriers. Embedded-only writeback preserves an existing sidecar unless --xmp-destination-sidecar strip_existing is set; sidecar-only writeback preserves existing embedded XMP unless --xmp-destination-embedded strip_existing is set. --force controls overwriting output files and generated sidecars.

CLI:

./build/metaread file.jpg
./build/metatransfer --source-meta source.jpg --target-jpeg rendered.jpg --output rendered_with_meta.jpg --force
./build/metatransfer --source-meta source.jpg --target-jpeg rendered.jpg --xmp-writeback embedded_and_sidecar --output rendered_with_meta.jpg --force
./build/metatransfer --source-meta source.jpg --target-jpeg rendered.jpg --xmp-destination-sidecar strip_existing --output rendered_with_meta.jpg --force

Python:

PYTHONPATH=build-py/python python3 - <<'PY'
import openmeta

doc = openmeta.read("file.jpg")
print(doc.entry_count)
PY

PYTHONPATH=build-py/python python3 -m openmeta.python.metatransfer \
  --source-meta source.jpg \
  --target-jpeg rendered.jpg \
  --xmp-writeback embedded_and_sidecar \
  --output rendered_with_meta.jpg \
  --force

12. Pick The Next Doc¶

Detailed read support: metadata_support.md
Target-by-target transfer status: metadata_transfer_plan.md
Host-side encoder and SDK integration: host_integration.md
Build, test, and deeper API notes: development.md

page RAW Read Parity Plan

This page tracks the public read-path work needed to move OpenMeta closer to ExifTool-level camera RAW coverage. It is about decoding and interpretation, not writer policy.

OpenMeta should keep a conservative rule here: preserve raw payloads whenever a family is only partially understood, and only promote fields to structured entries when their location, type, byte order, and meaning are stable enough to test.

Validation Method¶

RAW parity work is compared against ExifTool output with normalized values, group names, and intentional-difference notes. Each new lane should add:

a block-discovery test for the native container or embedded metadata carrier
a structured decode test for stable tags
a display-name or semantic-group test when the tag is user-visible
a transfer-safety test when the decoded value is source-specific
a compare note for unsupported or intentionally raw-only payloads

Family Gap Matrix¶

Family	Current lane	Main gap versus ExifTool	Next work
DNG and TIFF-based RAW	Strong baseline through TIFF/EXIF/IFD, DNG tags, XMP, ICC, and MakerNote payloads	Long-tail vendor private tables and model-specific MakerNote fields	Keep adding named tables only when they are stable and safety-classified
Nikon NEF/NRW	Strong TIFF/EXIF path plus expanded Nikon MakerNote tables and normalized Nikon Capture crop bounds	Model-specific encrypted/custom-setting tables and less common correction records	Add focused Nikon tables with byte-order/version gates and safety buckets
Sony ARW/SR2/SRF	Strong TIFF/EXIF path plus Sony RAW/source-processing classification and panorama crop-margin interpretation	Older SRF/SR2 private structures and model-specific private tables	Extend native SR2/SRF table naming and keep raw payload preservation as the fallback
Canon CR2	Strong TIFF/EXIF path plus Canon MakerNote, normalized aspect/crop geometry, and crop/aspect/color-data classification	Long-tail Canon custom functions and per-model color/correction tables	Continue table-by-table decode with rendered-transfer safety coverage
Canon CR3	Bounded BMFF plus EXIF/XMP/ICC/CR3 maker metadata	Deeper BMFF item/property graph semantics and CR3-specific private records	Deepen BMFF metadata graph interpretation before broad CR3 private-table work
Canon CRW/CIFF	Partial native lane: recursive CIFF directories, stable scalar/subtable decoding, common native names, and derived EXIF bridge	Older Canon private tables and long-tail legacy records	Continue table-by-table decode only where stable validation data exists
Fujifilm RAF	Partial native lane: header-declared preview-JPEG EXIF/XMP discovery, FujiIFD/TIFF follow path, RAF header fields, RAF directory geometry tags, RAFData geometry projection, normalized raw crop/zoom rectangles, and standalone XMP fallback	Model-specific RAF tables and less common native sections outside the stable carrier/header/directory subset	Extend native RAF section inventory table-by-table, with broader color/correction safety buckets before transfer use
Sigma X3F	Partial native lane: header fields, known PROP properties, section-directory JPEG metadata follow path, and legacy embedded-EXIF fallback	Deeper image-processing/compression sections and model-specific private records	Add X3F native sections only when they expose stable user-visible fields or transfer-safety inputs
Panasonic, Olympus, Pentax, Kodak, Minolta, Samsung, Ricoh	Mixed TIFF/EXIF and MakerNote table coverage	Older model tables, preview/correction subtables, and private RAW payloads	Prioritize tables that affect crop, color, lens correction, orientation, or transfer safety
Apple, DJI, Google, FLIR	Live-vendor source-processing classification exists for rendered-transfer safety	Computational, thermal, radiometric, and shot-log interpretation depth	Add decode only for stable fields that hosts can use safely
Rare and legacy RAW families	Raw-preservation-first	Native container and MakerNote depth	Preserve raw blocks, then add support only when validation inputs and stable structure are available

Priority¶

Keep writer safety explicit: decoded MakerNote sub-IFDs are not used to reconstruct vendor MakerNote blobs; the original raw MakerNote payload is preserved when available.
Continue high-visibility native read gaps: more model-specific RAF native sections, long-tail CRW/CIFF private tables, and deeper X3F section interpretation.
Deepen BMFF interpretation for CR3, HEIF, and AVIF metadata graphs.
Add X3F image-processing section decode only when the fields can be named, typed, and safety-classified.
Continue vendor MakerNote table work for fields that affect crop, color, orientation, lens correction, or safe transfer decisions.

page OpenEXR Metadata Fit for OpenMeta Core

Status: baseline contract (v1)

Goal¶

Assess whether the current OpenMeta metadata core can represent OpenEXR metadata well enough for read/edit workflows, and identify required API/model changes for good interoperability with OpenEXR and related host metadata layers.

What OpenEXR Metadata Looks Like¶

OpenEXR metadata is a per-part attribute map (name + typed value), not EXIF-like numeric tag tables. Attribute types are strongly typed in the SDK and include:

Scalars and enums (int, float, double, compression, lineOrder, envmap)
Geometric/math types (v2*, v3*, m33*, m44*, box2*)
Structured payloads (chlist, preview, tiledesc, timecode, keycode)
Strings and string vectors
Rational and opaque/custom attribute types

OpenEXR C APIs expose:

Count/list/get attribute by name or index (file order or sorted order)
Explicit typed getters/setters for built-in attribute types
Header write lifecycle (declare/set then write_header)
In-place header update mode with size constraints

Host Metadata Integration Signals¶

Common EXR host libraries often treat EXR metadata as arbitrary key/value attributes and map many EXR names to generic names (DateTime, Copyright, etc.) while preserving EXR-specific names under openexr:*.
EXR host stacks may expose EXIF/IPTC-like interoperability through arbitrary metadata transport, not because EXR natively stores EXIF/IPTC blocks.
OpenColorIO metadata model is mostly string-based transform/config metadata; it is useful for selected color-related fields, not as a full EXR container model.

Fit Against Current OpenMeta Core¶

Current OpenMeta strengths:

MetaStore already supports duplicate keys, per-block origin, deterministic indexing, and binary-search lookups.
MetaValue already supports scalar, array, bytes, text, and rational values.
Existing block model can represent per-part metadata boundaries.

Current implementation snapshot:

MetaKeyKind::ExrAttribute is available (part_index + name).
decode_exr_header(...) is implemented and wired into simple_meta_read fallback path (metadata-only header decode).
Common EXR scalar/vector/matrix types decode to typed MetaValue; unknown and complex payloads are preserved as raw bytes.
Unknown/custom EXR attrs can preserve original type name in Origin::wire_type_name (optional decode behavior).
Origin::wire_type carries EXR type code (WireFamily::Other), and wire_count currently stores attribute byte size.

Remaining gaps for production-level EXR workflows:

Persisting original EXR type_name for unknown/custom attrs (beyond numeric code).
Full canonical policy for complex structured attrs (chlist, preview, stringvector) and helper views.
EXR-aware write/edit lifecycle, including in-place header size constraints.
Optional EXR scanner integration in container_scan (today handled by fallback decode in simple_meta_read).

Design Direction (v1)¶

Add EXR key space and provenance:
- MetaKeyKind::ExrAttribute with fields: part_index, name.
- Reserve block format/container code for EXR header metadata blocks.
Add EXR wire typing:
- Extend wire metadata to carry EXR type id + type_name string when needed.
- Keep unknown/custom attributes as raw bytes + declared type name.
Define canonical value encodings:
- vectors/matrices/boxes as typed arrays with fixed element counts.
- chlist, preview, and other complex structs as bytes + structured decode helpers (opt-in) to keep core storage compact and lossless.
Add EXR decode entry point:
- decode_exr_header(...) that fills MetaStore from EXR parts/attributes.
- Keep image pixel I/O out of scope; metadata only.
Add integration adapters:
- flat host-attribute export: map EXR attrs to generic host names plus openexr:*.
- OpenColorIO adapter: expose selected color metadata subset only.

Canonical encoding details for compound EXR values are tracked in: OpenMeta/docs/design/exr_canonical_value_encoding.md.

Practical Conclusion¶

OpenMeta core is close enough to support EXR metadata without redesigning the store. Main work is key-space/type modeling and a container-specific EXR decode frontend with clear canonical encoding rules for EXR compound attribute types.

page Writer Target Contract

This page defines the bounded preserve/replace contract for OpenMeta transfer writers.

It is scoped to metadata transfer and metadata-only target edits. OpenMeta does not claim full arbitrary metadata-editor parity, pixel transcoding, or byte-for-byte preservation of rewritten metadata structures.

For generated XMP merge, precedence, sidecar output, and sidecar cleanup rules, see xmp_sync_policy.md.

Common Rules¶

Managed metadata families are replaced only when OpenMeta has a prepared block for that family or an explicit strip policy targets that family.

Unmanaged data is preserved as source ranges where the target edit path can parse the container safely. If parsing finds a structure outside the bounded contract, the edit fails with an unsupported or malformed result instead of guessing.

Managed XMP writeback has three modes:

EmbeddedOnly: generated XMP remains in the managed embedded carrier.
SidecarOnly: generated embedded XMP blocks are suppressed and returned as sidecar output.
EmbeddedAndSidecar: generated XMP is written to both the embedded carrier and sidecar output.

Destination embedded-XMP stripping is supported only for sidecar-only writeback on JPEG, TIFF/DNG, PNG, WebP, JP2, JXL, and bounded BMFF targets. Destination sidecar cleanup is supported only for embedded writeback.

Image-dependent metadata is target-owned. When source and target images may differ in dimensions, channel count, sample type, compression, orientation, colorspace, or strip/tile storage layout, host code must preserve or provide target-correct image buffer specs from the actual output image. Use PrepareTransferRequest::target_image_spec when the host knows target dimensions, orientation, samples-per-pixel, bit depth, sample format, photometric interpretation, planar configuration, compression, or EXIF color space. OpenMeta filters source EXIF/XMP image-layout fields during prepared transfer rather than copying stale source width/height, channel/layout, color-space aliases, or source-local storage offsets into another file. ICC transfer should be enabled only when the host knows that the source profile is valid for the target pixel buffer; otherwise the host writer should keep or inject the target profile. The Python binding exposes the same structure as openmeta.TransferTargetImageSpec; the C++ and Python metatransfer command wrappers expose matching --target-* flags for smoke tests and file-helper integration checks.

For coarse transfer safety, use TransferProfile::safety. The default CompatibleFile mode is for metadata repackage or recompression into a compatible target and preserves source camera/color metadata after the target-owned image-layout filter above. RenderedImage is for exports whose pixels may have changed, including RAW-to-rendered outputs. It keeps general descriptive metadata, time fields, GPS, IPTC, and portable XMP, but filters source raw color calibration, profile/gain tables, raw digests/storage identifiers, linearization/crop/correction tags, vendor RAW geometry/color/correction/private tags for Phase One/Leaf, Sony, Canon, Nikon, Fujifilm, Pentax, Panasonic, Olympus, Kodak, Minolta, Sigma, Samsung, Ricoh, Apple/Google computational capture fields, DJI/FLIR thermal processing fields, Casio/Sanyo preview or face-geometry fields, KyoceraRaw WB fields, Reconyx trail-camera processing/environment fields, HP/JVC/GE private placeholders, Motorola source-rendering/sensor fields, Nintendo parallax/camera-info fields, Microsoft stitch/panorama geometry fields, camera raw settings XMP, source ICC profiles, MakerNotes, and non-C2PA JUMBF data. Host code should provide target-correct ICC/profile data and image specs separately.

Transfer Safety Matrix¶

The table below is the public coarse policy for automatic transfer. It is not a privacy policy and it is not a replacement for application-specific metadata controls. Hosts may still strip more metadata. For per-candidate preflight UI, metadata_concepts.h exposes transfer hints such as safe, source_bound, rendered_unsafe, and requires_target_image_spec; transfer_concept_diagnostics_from_store(...) maps those hints to keep/drop/requires-target-image-spec actions, severity tokens, and default message text for a selected transfer mode.

Metadata group	Examples	`CompatibleFile`	`RenderedImage`	Notes
General descriptive metadata	title, description, creator, artist, copyright, rating, label, keywords	Keep	Keep	Safe because it describes the asset or authorship rather than the source pixel encoding.
Capture time	`DateTimeOriginal`, `CreateDate`, subsecond fields, timezone offset fields, GPS time	Keep	Keep	If the output represents a new capture or synthetic composition, host policy should replace or strip these values.
Camera and lens acquisition facts	`Make`, `Model`, `LensModel`, exposure time, f-number, ISO, focal length, flash, metering mode	Keep	Keep	These are safe as capture facts. They are not treated as processing instructions.
Location and IPTC editorial fields	EXIF GPS, XMP GPS aliases, IPTC location, caption, byline, credit, rights, job/reference fields	Keep	Keep	Privacy-sensitive data is intentionally left to host policy.
Portable XMP	Dublin Core, XMP Rights, IPTC Extension, generated EXIF/IPTC projections	Keep after image-layout filtering	Keep after image-layout and rendered-safety filtering	XMP properties from raw-processing namespaces are handled separately below.
Target image layout and storage	width, height, orientation, samples per pixel, bits per sample, sample format, photometric interpretation, compression, rows/strips/tiles, offsets, byte counts, thumbnail/interchange offsets	Target-owned; source values filtered	Target-owned; source values filtered	Host code must preserve target values or provide `target_image_spec`.
Output color/profile metadata	ICC profile blocks, EXIF/XMP `ColorSpace`, color-space aliases, Photoshop ICC profile name	Keep only when the source profile is valid for the target pixel buffer	Drop source ICC/profile facts; host writes target profile	Rendered exports often need a new output profile such as sRGB, Display P3, or a host-managed working/output profile.
RAW/DNG sensor and color pipeline	CFA pattern, black/white levels, linearization tables, `ColorMatrix`, `ForwardMatrix`, `CameraCalibration`, `AsShotNeutral`, DNG private/profile tags, DNG XMP profile properties (`dng:`), profile/gain tables, raw digests/storage identifiers, opcode/correction lists, Phase One/Leaf `ColorMatrix1`, `ColorMatrix2`, `WB_RGBLevels`, sensor-calibration flat fields and linearization coefficients, Sony/Canon/Nikon/Fujifilm/Pentax/Panasonic/Olympus/Kodak/Minolta/Sigma/Samsung/Ricoh/Apple/Casio/Sanyo/KyoceraRaw/Reconyx/Motorola MakerNote color, HDR, source-rendering, and white-balance coefficient tables	Keep only for compatible RAW/DNG-style transfer	Drop	These values describe how to turn original sensor data into rendered color. Reusing them on already-rendered pixels can make CMS or editors apply the raw transform twice.
RAW crop, geometry, storage, correction, and private data	`ActiveArea`, `DefaultCrop*`, masked areas, opcode lists, distortion/vignetting/camera-profile correction data, Phase One/Leaf `SensorWidth`, `SensorHeight`, `SensorLeftMargin`, `SensorTopMargin`, `ImageWidth`, `ImageHeight`, `CameraOrientation`, `RawFormat`, `RawData`, `StripOffsets`, `BlackLevel`, `BlackLevelData`, `SplitColumn`, sensor-temperature correction fields, Sony/Canon/Nikon/Fujifilm/Pentax/Panasonic/Olympus/Kodak/Minolta/Sigma/Samsung/Ricoh decoded RAW geometry/storage/lens-correction fields such as SR2/SRF, RAF header/directory/RAFData fields, MinoltaRaw PRD/RIF/WBG tables, Pentax lens-correction tables, Panasonic sensor subtables, Olympus image-processing/raw-development tables, Kodak sensor/black-level/raw-histogram fields, Samsung Type2 raw/color/correction fields, Ricoh sensor/crop/vignetting fields, Apple computational capture/HDR fields, Google HDR+ and shot-log fields, pixel-shift, multi-shot, composite, and auto-lighting optimizer fields, DJI thermal parameter tables, FLIR thermal raw-data/radiometric calibration/palette/PiP fields, Casio/Sanyo preview image, face geometry, and private data-dump fields, Reconyx trail-camera environment/trigger fields, HP/JVC/GE private placeholders, Motorola sensor fields, Nintendo parallax/camera-info fields, Microsoft stitch/panorama geometry fields, Canon crop/aspect/color-data tables, and Nikon NEF/distortion/vignette tables or named correction fields	Keep only for compatible RAW/DNG-style transfer	Drop	These values are tied to the original sensor geometry, computational rendering, radiometric calibration, source preview data, or raw-processing pipeline. Vendor-private RAW/source tables are dropped in rendered mode even when individual fields are unknown, while named entries also receive narrower color/WB/geometry/correction buckets. Use `phaseone_raw_geometry_from_store()`, `phaseone_raw_processing_from_store()`, and `vendor_raw_processing_from_store()` only to interpret source RAW metadata; rendered exports need target-owned geometry and color/profile data.
Camera raw settings XMP	`crs:*` development settings and raw-edit recipe metadata	Keep	Drop	A rendered file should not normally carry a source raw-edit recipe unless the host intentionally writes a sidecar/workflow record.
Opaque MakerNote payloads	vendor MakerNote blobs and private nested IFDs	Keep the original raw `ExifIFD:MakerNote` payload by default, or follow explicit MakerNote policy	Drop	Decoded safe facts can still be carried through standard EXIF/XMP fields; the opaque vendor blob is not copied for rendered outputs. Decoded-only vendor MakerNote sub-IFDs are not reconstructed into a new blob; prepare reports them as non-serializable when no raw MakerNote payload is available.
C2PA and JUMBF	APP11/JUMBF boxes, C2PA manifests, assertions, signatures	Follow explicit JUMBF/C2PA policy	Drop non-C2PA JUMBF; invalidate C2PA by default if it would otherwise be kept	Pixel-changing exports need a new content binding and signature from the host or signer.
Embedded previews and thumbnails	TIFF preview pages, SubIFD previews, JPEG interchange thumbnail data	Preserve only within bounded target-owned rewrite rules	Target-owned; host should regenerate or preserve target previews	Source previews commonly describe the source pixels, not the rendered target.

Target Summary¶

Target	Managed embedded carriers	Preserve/replace rule	Main limits
`JPEG`	APP1 EXIF, APP1 XMP, APP2 ICC, APP13 IPTC/IRB, bounded APP11 JUMBF/C2PA	Replace matching recognized leading metadata segments; preserve unknown leading segments and image scan data	Not a general JPEG marker editor
`TIFF`	root TIFF tags, EXIF/GPS/Interop IFDs, bounded page/SubIFD chains, XMP tag 700, IPTC 33723, ICC 34675	Rewrite bounded IFD structures and append new metadata tail data; preserve unrelated root tags and bounded downstream tails	Not arbitrary nested-IFD graph rewrite
`DNG`	same as TIFF plus DNG target-mode policy and minimal `DNGVersion` synthesis	Uses the TIFF-family rewrite contract; preserves DNG core target tags when merging non-DNG source metadata into an existing DNG target	Not a full DNG-specific rewrite engine
`PNG`	`eXIf`, XMP `iTXt`, `iCCP`	Insert prepared chunks after `IHDR`; replace matching managed chunks; preserve unrelated chunks	Requires valid PNG with terminal `IEND`
`WebP`	`EXIF`, XMP RIFF chunk, `ICCP`, bounded `C2PA`	Replace matching managed RIFF chunks; preserve unrelated chunks; patch `VP8X` feature bits	EXIF/XMP/ICC edits require an existing `VP8X` chunk
`JP2`	top-level `Exif`, top-level XMP `xml` box, `jp2h/colr` ICC	Replace matching top-level metadata boxes; rewrite `jp2h` only to replace/insert `colr`; preserve unrelated boxes and unrelated `jp2h` children	Does not synthesize `jp2h`; requires one existing `jp2h` for ICC
`JXL`	top-level `Exif`, XMP `xml` box, `jumb`, `c2pa`	Replace matching top-level boxes; preserve signature and non-managed boxes; classify `jumb` as generic JUMBF or C2PA	ICC is encoder handoff only; file edit emits uncompressed prepared metadata boxes
`HEIF` / `AVIF` / `CR3`	BMFF metadata items (`Exif`, XMP `mime`, JUMBF/C2PA), bounded `colr/prof` ICC properties, plus OpenMeta-authored metadata-only `meta` boxes	Preserve non-`meta` top-level boxes; replace prior OpenMeta-authored metadata `meta`; merge/replace/strip item metadata in parseable foreign top-level `meta` graphs by extending `iinf`/`iloc`/`idat`/`iref`; replace prior ICC `colr` properties and remap `iprp`/`ipco`/`ipma` for bounded ICC	Does not rewrite arbitrary BMFF scene/property graphs
`EXR`	safe string header attributes through the EXR transfer emitter or adapter batch	No file rewrite contract today; host applies prepared attributes through its own EXR writer	Attribute-emitter target, not a file edit path

JPEG¶

The JPEG edit path scans leading metadata marker segments before image scan data.

OpenMeta replaces a leading segment when:

the segment route matches a prepared block route
sidecar-only writeback requests embedded XMP stripping and the segment is APP1 XMP
JUMBF or C2PA policy resolves to removal for matching APP11 carriers

Unknown APP/COM segments and all scan data after the leading metadata region are preserved. If same-size replacements are available, OpenMeta can use the in-place edit plan; otherwise it performs a metadata rewrite while preserving the image data range.

TIFF And DNG¶

TIFF-family editing supports classic TIFF and BigTIFF.

Managed updates include:

root IFD metadata tags such as XMP tag 700, IPTC tag 33723, and ICC tag 34675
EXIF payload materialized as bounded TIFF-family IFD structures
EXIF/GPS/Interop pointer regeneration
bounded preview-page chain replacement with downstream tail preservation
bounded SubIFD replacement with downstream auxiliary-tail preservation
preserving an existing target InteropIFD when a replaced ExifIFD omits its own interop child

The active root image IFD remains target-owned for pixel layout and local byte storage. Source EXIF values for root image width/height, sample layout, compression, orientation, strip/tile offsets, strip/tile byte counts, and thumbnail/JPEG interchange offsets are not allowed to replace the target’s active image structure during metadata transfer. For replaced preview-page and SubIFD structures, OpenMeta also strips source-local strip/tile/JPEG storage offsets and preserves the corresponding target-local storage fields when a matching target child exists.

The same target-owned rule is applied before packaging EXIF/XMP metadata for JPEG, PNG, WebP, JP2, JXL, BMFF-family targets, and EXR string attributes. Source descriptive tags such as make/model/date/GPS/copyright continue to transfer; source image-buffer facts do not become target image facts unless a host supplies target-correct values through target_image_spec or another writer-specific path.

Unrelated root IFD tags are preserved. Rewritten structures may be repacked into new offsets appended to the file; offset identity is not part of the contract.

DNG uses the same TIFF-family rewrite contract. ExistingTarget and TemplateTarget require a backing target container. MinimalFreshScaffold can emit a minimal metadata scaffold without an existing DNG target. When a non-DNG source is merged into an existing DNG target, OpenMeta preserves existing target DNG core tags within the bounded DNG policy layer.

PNG¶

The PNG edit path requires a valid PNG signature, an IHDR chunk, and a terminal IEND chunk.

Prepared eXIf, XMP iTXt, and iCCP chunks are inserted immediately after IHDR. Existing chunks from those managed families are removed when a replacement or strip policy targets that family. XMP matching is limited to iTXt chunks using the XML:com.adobe.xmp keyword.

All unrelated chunks are preserved. Bytes following the terminal IEND are preserved as part of the kept terminal range.

WebP¶

The WebP edit path requires a valid RIFF/WebP stream whose RIFF size consumes the input bytes.

Prepared EXIF, XMP, ICCP, and bounded C2PA chunks replace existing chunks from the same managed family. Unrelated chunks are preserved. When EXIF, XMP, or ICC is present after rewrite, OpenMeta patches the existing VP8X feature flags to match the final metadata state.

Prepared WebP EXIF chunks carry the TIFF byte stream directly. They do not include the JPEG APP1 Exif\0\0 preamble.

The current WebP edit contract requires an existing VP8X chunk for EXIF, XMP, or ICC metadata edits. It does not synthesize VP8X.

JP2¶

The JP2 edit path requires a valid JP2 signature box and file-type box.

Prepared top-level Exif and XMP xml boxes replace existing top-level boxes from the same managed family. Unrelated top-level boxes are preserved.

ICC update uses the bounded jp2h/colr route. OpenMeta rewrites the existing jp2h box to replace existing colr children with the prepared ICC colr payload, while preserving unrelated jp2h children. If no colr child exists, the prepared colr child is inserted. The contract requires one existing jp2h box and does not synthesize a new jp2h box.

JXL¶

The JXL edit path requires a valid JXL container.

Prepared top-level Exif, XMP xml, jumb, and c2pa boxes replace existing boxes from the same managed family. Unrelated top-level boxes are preserved, including the JXL signature box. Generic JUMBF and C2PA are distinguished so a generic jumb replacement does not accidentally remove a C2PA carrier, and the C2PA path does not remove unrelated generic JUMBF.

When Brotli support is available, the same family classification can inspect compressed brob metadata boxes by real type. The file edit path emits prepared metadata boxes directly; the jxl:icc-profile route remains an encoder-side handoff and is not serialized by the file edit path.

HEIF / AVIF / CR3¶

The bounded BMFF edit path preserves non-meta top-level boxes as source ranges.

When the target has no foreign top-level meta box, OpenMeta writes one metadata-only top-level meta box using the public bounded contract. That box can contain prepared Exif, XMP, JUMBF, C2PA, and ICC colr property payloads. A prior OpenMeta-authored metadata meta box is removed and replaced by the newly prepared box.

When the target already has a foreign top-level meta box, OpenMeta does not append a second competing meta graph. For parseable HEIF/AVIF-style item graphs it merges, replaces, or strips bounded Exif/XMP/JUMBF/C2PA metadata items in the existing meta by extending iinf, iloc, idat, and iref with cdsc references to the primary item. This constrained merge requires a single parseable iinf, iloc version 0/1/2, pitm, and at most one idat. When inserted metadata needs an item ID wider than 16 bits, OpenMeta upgrades the rebuilt iloc to version 2, emits infe version 3 for those inserted items, and uses iref version 1 for the corresponding cdsc references. If the existing graph has exhausted the usable 32-bit item-id space or mixes item-table shapes outside this bounded contract, the edit fails instead of truncating IDs.

Newly inserted metadata item payloads are appended to the rebuilt idat payload. To preserve broad reader compatibility, their iloc records keep construction method 0 and use absolute file-offset extents within the existing field widths. When all retained self-contained item locations can be represented as absolute extents, OpenMeta compacts the rebuilt iloc base-offset field width to zero for simpler reader compatibility.

Retained foreign item locations are supported when they use construction method 0 with file offsets, or construction method 1 with offsets into an existing idat, with data reference index 0. Construction method 2 is supported only when the retained item has parseable iref iloc references, using explicit extent indexes or reference order, and every referenced item is also retained with a supported local location. External data references, missing method-2 references, removed referenced items, and other construction methods fail as unsupported instead of being rewritten by guesswork.

For bounded ICC transfer, OpenMeta removes prior ICC colr/prof and colr/rICC properties from iprp/ipco, compacts/remaps existing ipma associations, appends the transferred colr/prof property, and associates it with the primary item and any retained item that previously referenced one of the replaced ICC properties. If the replaced association was marked essential, the transferred ICC association keeps that bit. Arbitrary non-ICC property replacement and broader BMFF scene/property graph rewriting remain out of scope.

If sidecar-only writeback asks to strip embedded XMP, OpenMeta can remove XMP from its own OpenMeta-authored metadata meta box and from parseable foreign top-level meta item graphs that satisfy the same bounded primary-item contract. Foreign graphs without pitm, with unsupported iloc, with multiple competing item tables, or otherwise outside that bounded shape are reported as unsupported instead of being guessed.

EXR¶

EXR is a transfer target and host-emitter path, not a file rewrite path.

OpenMeta prepares safe flattened string attributes for transfer and exposes the EXR attribute batch helpers for host-owned EXR writers. Existing EXR file metadata preservation is therefore owned by the host writer, not by an OpenMeta file edit helper.

One important pending use case is late-bound EXR metadata. Streaming tile or scanline writers sometimes only know a value after pixel data is finished, for example total_compute_time. The safe fast design is a fixed-size reservation/patch contract: reserve a typed attribute, such as a double, before writer construction, then patch exactly those value bytes after close. OpenMeta does not provide this patch API yet; it should remain separate from general EXR file rewrite because variable-length header changes would require moving later file structures.

Non-Goals¶

The writer contract does not promise:

arbitrary metadata editing for every carrier a format can contain
preserving byte offsets of rewritten TIFF-family structures
rewriting arbitrary existing BMFF item/property graphs
synthesizing missing JP2 jp2h or WebP VP8X structures
file-level EXR metadata rewrite
signed C2PA rewrite or trust-policy parity beyond the bounded staged handoff paths

page XMP Sync And Writeback Policy

This page defines the bounded public policy for generated portable XMP during metadata transfer.

It covers:

generated EXIF-to-XMP properties
generated IPTC-to-XMP properties
source embedded XMP decoded from the source metadata
destination embedded XMP loaded from the target file
destination sidecar XMP loaded from a sibling .xmp

This is not a full arbitrary metadata synchronization engine. It is the writer-side contract used by the transfer helpers so hosts can predict preserve, merge, and writeback behavior.

For target-specific embedded carrier replacement and unmanaged-data preservation rules, see writer_target_contract.md.

Default Contract¶

The default transfer behavior is conservative:

Option	Default	Effect
`PrepareTransferRequest::xmp_project_exif`	`true`	Generate portable XMP properties from EXIF/TIFF/GPS fields.
`PrepareTransferRequest::xmp_project_iptc`	`true`	Generate portable XMP properties from IPTC-IIM fields.
`PrepareTransferRequest::xmp_include_existing`	`true`	Include existing XMP already decoded into the source `MetaStore`.
`PrepareTransferRequest::xmp_conflict_policy`	`CurrentBehavior`	Emit generated EXIF properties, then existing XMP, then generated IPTC properties.
`xmp_existing_sidecar_mode`	`Ignore`	Do not merge a destination sidecar unless explicitly requested.
`xmp_existing_destination_embedded_mode`	`Ignore`	Do not merge destination embedded XMP unless explicitly requested.
`xmp_writeback_mode`	`EmbeddedOnly`	Keep generated XMP in the managed embedded carrier.
`xmp_destination_embedded_mode`	`PreserveExisting`	Preserve existing embedded XMP when sidecar-only writeback suppresses generated embedded XMP.
`xmp_destination_sidecar_mode`	`PreserveExisting`	Preserve an existing sibling `.xmp` when embedded-only writeback is used.

Native EXIF and IPTC carrier emission is independent from XMP projection. Turning off xmp_project_exif or xmp_project_iptc suppresses only the generated XMP projection, not native EXIF/IPTC transfer.

Existing XMP Carrier Precedence¶

OpenMeta first builds one decoded transfer store. Optional destination XMP carriers are merged into that store before or after the source entries according to explicit precedence options.

For duplicate existing XMP properties, earlier merged entries win during portable XMP output.

Conflict	Option	Default order	Alternate order
destination sidecar vs source embedded XMP	`xmp_existing_sidecar_precedence`	sidecar before source (`SidecarWins`)	source before sidecar (`SourceWins`)
destination embedded XMP vs source embedded XMP	`xmp_existing_destination_embedded_precedence`	destination before source (`DestinationWins`)	source before destination (`SourceWins`)
destination sidecar vs destination embedded XMP	`xmp_existing_destination_carrier_precedence`	sidecar before embedded (`SidecarWins`)	embedded before sidecar (`EmbeddedWins`)

The destination sidecar is loaded only when xmp_existing_sidecar_mode == MergeIfPresent. The destination embedded packet is loaded only when xmp_existing_destination_embedded_mode == MergeIfPresent.

If both destination sidecar and destination embedded XMP are merged on the same side of the source entries, xmp_existing_destination_carrier_precedence decides which destination carrier wins. If they are placed on opposite sides of the source entries, the two source-precedence options define the effective order.

Failed or missing optional destination carriers do not silently change the source metadata. The result reports a status and message for the attempted sidecar or destination-embedded load.

Generated EXIF/IPTC Versus Existing XMP¶

After the transfer store is assembled, xmp_conflict_policy decides the relative precedence between generated portable XMP and the existing XMP set. The existing XMP set includes source embedded XMP plus any destination XMP carriers that were explicitly merged.

Policy	Pass order	Practical effect
`CurrentBehavior`	EXIF-derived, existing XMP, IPTC-derived	EXIF projection wins over existing XMP; existing XMP wins over IPTC projection.
`ExistingWins`	existing XMP, EXIF-derived, IPTC-derived	Existing XMP wins over generated EXIF/IPTC projection.
`GeneratedWins`	EXIF-derived, IPTC-derived, existing XMP	Generated EXIF/IPTC projection wins over existing XMP.

When generated EXIF and generated IPTC projection both claim the same portable property, EXIF-derived output is emitted first and wins.

xmp_existing_standard_namespace_policy applies inside the existing-XMP pass:

PreserveAll keeps existing standard portable namespace entries subject to the conflict order above.
CanonicalizeManaged drops OpenMeta-managed standard portable properties from existing XMP when a generated replacement exists.

xmp_existing_namespace_policy controls breadth:

KnownPortableOnly keeps only standard portable namespaces known to OpenMeta.
PreserveCustom also preserves safe simple or indexed properties from custom namespaces.

Writeback Modes¶

Writeback mode controls where the generated XMP packet goes after transfer execution.

Mode	Edited file	Sibling `.xmp`	Cleanup behavior
`EmbeddedOnly`	Generated XMP stays in the managed embedded carrier.	No generated sidecar output.	Existing sidecar is preserved unless `xmp_destination_sidecar_mode == StripExisting`.
`SidecarOnly`	Generated embedded XMP blocks are suppressed.	Generated XMP is returned as sidecar output.	Existing embedded XMP is preserved unless `xmp_destination_embedded_mode == StripExisting`.
`EmbeddedAndSidecar`	Generated XMP stays in the managed embedded carrier.	The same generated XMP is returned as sidecar output.	No destination sidecar cleanup is requested.

Destination sidecar cleanup is supported only for embedded writeback. If xmp_destination_sidecar_mode == StripExisting, OpenMeta returns a cleanup request for the sibling .xmp; persist_prepared_transfer_file_result(...) performs the removal when remove_destination_xmp_sidecar is true.

Destination embedded-XMP stripping is supported for sidecar-only writeback on the current managed writer targets: JPEG, TIFF/DNG, PNG, WebP, JP2, JXL, and bounded BMFF targets (HEIF, AVIF, CR3). Other combinations report an unsupported policy result instead of guessing.

Sidecar output and cleanup paths are derived from xmp_sidecar_base_path when provided, otherwise from the edit/output target path. Hosts that do not have a filesystem path can set xmp_existing_destination_sidecar_state explicitly so OpenMeta can return deterministic cleanup guidance without probing the filesystem.

The persistence helper writes generated sidecars only when sidecar output is requested. It does not overwrite an existing sidecar unless overwrite_xmp_sidecar is true.

Non-Goals¶

This bounded policy intentionally does not claim:

full MWG-style EXIF/IPTC/XMP reconciliation
arbitrary XMP graph editing
raw packet passthrough or byte-for-byte XMP preservation
semantic conflict resolution beyond the documented portable property order
full sidecar and embedded synchronization for every possible namespace

Those remain broader parity work. The current contract is meant to be stable enough for predictable transfer and export workflows.

dir docs/design

dir docs

dir src/include

dir src/include/openmeta

dir docs/research

dir src

page OpenMeta

../../build/docs/doxygen/xml/docs/images/OpenMeta_Logo.png

OpenMeta is a metadata processing library for image files.

The current focus is safe, format-agnostic reads: find metadata blocks in common containers, decode them into a normalized in-memory model, and expose stable transfer/edit building blocks for export workflows.