Initial Commit

packages/media/image/exif/src/iptc/read-iptc.md

@@ -0,0 +1,73 @@
+# readIptc
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Parses IPTC IIM (Information Interchange Model) metadata from a Photoshop 3.0 APP13 JPEG segment payload. IPTC is the editorial metadata standard used by news agencies and photo distributors for fields such as headline, caption, copyright, keywords, and geographic information. The parser traverses the Photoshop 8BIM resource block structure to locate the IPTC-NAA data block (resource ID 0x0404) and then iterates its Record 2 datasets.
+
+## Features
+
+- Parses the Photoshop 3.0 + 8BIM wrapper before accessing IPTC data
+- Extracts all standard Record 2 editorial fields: headline, caption, copyright, creator, keywords, city, country code, country name, source
+- Handles repeatable fields (keywords) correctly as arrays
+- Returns an empty object gracefully if no IPTC data is present
+- Zero external dependencies — pure TypeScript byte-level parsing
+
+## Usage: Basic Example
+
+```ts
+import { readIptc } from "@suaveplan/exif/iptc";
+
+const iptc = readIptc(app13SegmentData);
+console.log(iptc.headline);
+console.log(iptc.keywords); // string[]
+```
+
+## Usage: Advanced Example
+
+```ts
+import { parseJpegSegments, isIptcSegment } from "@suaveplan/exif";
+import { readIptc } from "@suaveplan/exif/iptc";
+
+const segments = parseJpegSegments(jpegBuffer);
+const iptcSeg = segments.find(isIptcSegment);
+
+if (iptcSeg) {
+  const iptc = readIptc(iptcSeg.data);
+  console.log("Headline:", iptc.headline);
+  console.log("Copyright:", iptc.copyright);
+  console.log("Creator:", iptc.creator);
+  console.log("Keywords:", iptc.keywords?.join(", "));
+  console.log("Location:", [iptc.city, iptc.country].filter(Boolean).join(", "));
+}
+```
+
+## API Reference
+
+### `readIptc(data: Uint8Array): IptcData`
+
+Parses IPTC data from a raw APP13 segment payload (the full `data` field of a `JpegSegment` with marker `0xFFED`).
+
+**Returns:** `IptcData` object with all recognisable fields populated, or an empty `{}` if the data does not match the Photoshop 3.0 + 8BIM + IPTC structure.
+
+**Does not throw.** Malformed or truncated data results in partial or empty output.
+
+### Dataset mapping
+
+| Dataset code | IptcData field |
+|---|---|
+| Record 2, DS 5 (0x05) | `headline` |
+| Record 2, DS 80 (0x50) | `creator` |
+| Record 2, DS 120 (0x78) | `caption` |
+| Record 2, DS 25 (0x19) | `keywords[]` |
+| Record 2, DS 90 (0x5A) | `city` |
+| Record 2, DS 100 (0x64) | `countryCode` |
+| Record 2, DS 101 (0x65) | `country` |
+| Record 2, DS 116 (0x74) | `copyright` |
+| Record 2, DS 115 (0x73) | `source` |
+
+## Implementation Notes
+
+The Photoshop 3.0 wrapper uses Pascal strings for resource names (1-byte length followed by the name, padded to an even byte boundary). The 8BIM block iteration stops on the first non-`8BIM` signature to avoid reading into compressed image data. IPTC record markers are `0x1C` followed by record number and dataset number. Only Record 2 (Application Record) datasets are extracted; Record 1 (Envelope Record) envelope fields are skipped. The string decoder uses Latin-1 (one byte per character); IPTC IIM data is specified as 7-bit ASCII.