Reading metadata
metadata() has one meaning: what the root source reported when it was opened. It never describes the transformed pipeline. It is async because it opens the source off Swift’s cooperative executor on Hokusai’s evaluation scheduler, and it reads only the header.
_ = try await Hokusai(url: URL(fileURLWithPath: "emblem.png")).resize(width: 300).pdf().write(to: URL(fileURLWithPath: "page.pdf"))
for name in ["scene.png", "phone.jpg", "emblem.png", "page.pdf"] { let m = try await Hokusai(url: URL(fileURLWithPath: name)).metadata() print(name, "→", m.format?.rawValue ?? "unknown", "\(m.width)×\(m.height)", "oriented \(m.orientedSize.width)×\(m.orientedSize.height)", "· channels", m.pixel.channels, "alpha", m.pixel.hasAlpha, m.pixel.interpretation, "· pages", m.pages.count, "· exif", m.exif?.count ?? 0, "bytes", "· source", m.sourceByteSize.map(String.init) ?? "n/a", "bytes")}
// metadata() describes the source as opened, never the pipeline built on it.let original = try await Hokusai(url: URL(fileURLWithPath: "scene.png")).metadata()let afterResize = try await Hokusai(url: URL(fileURLWithPath: "scene.png")).resize(width: 100).metadata()print("same metadata after resize:", original == afterResize)
// A truncated header is an error from metadata(); a file with an intact header reads even if its pixels are damaged.let bytes = try Data(contentsOf: URL(fileURLWithPath: "scene.png"))let damaged = try await Hokusai(data: bytes.prefix(bytes.count / 2)).metadata()print("half a PNG still reports", damaged.width, "×", damaged.height)What it showed
Section titled “What it showed”| Source | Format | Stored size | Oriented size | Channels | Pages | EXIF |
|---|---|---|---|---|---|---|
scene.png |
png | 1600 × 1000 | 1600 × 1000 | 3 (no alpha) | 1 | none |
phone.jpg |
jpeg | 1000 × 1600 | 1600 × 1000 | 3 | 1 | 32 bytes |
emblem.png |
png | 400 × 400 | 400 × 400 | 4 (alpha) | 1 | none |
page.pdf |
300 × 300 | 300 × 300 | 4 | 1 | none |
image.metadata()andimage.resize(width: 100).metadata()are equal (the program printedtrue). What a pipeline produces is described byOutputInfofrom a terminal, not bymetadata().- A composite pipeline reports only its base source; call
metadata()on an overlay’s own value to inspect it. - Because only the header is read, half a PNG still reports 1600 × 1000, even though decoding its pixels would fail. Pixels are checked by terminals, not by
metadata(). InputOptionsapply: the selectedpage, the limits and the access mode.
Fields
Section titled “Fields”- Dimensions (
width,height) are the stored size of the selected page. EXIF orientation is a separate typedorientation(ImageOrientation,nilwhen absent or invalid);orientedSizeswaps width and height only for quarter-turn orientations, asphone.jpgshows. pixel(PixelMetadata):channels,hasAlpha, a curatedinterpretation(.grayscale,.sRGB,.rgb,.cmyk,.lab, …; it says how stored values are read and does not mean an ICC profile was applied),sampleFormat,bitsPerSample, and for PNG whether it is palette-based.formatcomes from the loader libvips used, not from a file name;nilwhen it cannot be identified (for example JPEG XL). AVIF and HEIC share one loader and are told apart by their HEIF compression.pages(PageMetadata):count > 1means multi-page.animation: loop count and per-frame delays; present only when the source carries frame delays, so a multi-page TIFF is not reported as animated.- Density: one value in DPI plus the source’s preferred unit when it records one. libvips reports 1 pixel/mm for a file with no recorded resolution; that default is treated as “none”, not as 25.4 DPI.
- Embedded blocks (
exif,iccProfile,xmp,iptc) are owned rawData. The IPTC block is the Photoshop image-resource block carrying the IPTC records, exactly as libvips exposes it;xmpStringdecodes XMP only when it is valid UTF-8. sourceByteSizeis exact forDataand the file size for a file.
Command line
Section titled “Command line”hokusai inspect --input photo.jpg prints the same facts as a table; --json prints one JSON object for scripts.
Related
Section titled “Related”- Metadata retention: what the output keeps
- Input options