Skip to content
Hokusai2.2.2
ivantokar.com

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)
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 pdf 300 × 300 300 × 300 4 1 none
  • image.metadata() and image.resize(width: 100).metadata() are equal (the program printed true). What a pipeline produces is described by OutputInfo from a terminal, not by metadata().
  • 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().
  • InputOptions apply: the selected page, the limits and the access mode.
  • Dimensions (width, height) are the stored size of the selected page. EXIF orientation is a separate typed orientation (ImageOrientation, nil when absent or invalid); orientedSize swaps width and height only for quarter-turn orientations, as phone.jpg shows.
  • pixel (PixelMetadata): channels, hasAlpha, a curated interpretation (.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.
  • format comes from the loader libvips used, not from a file name; nil when 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 > 1 means 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 raw Data. The IPTC block is the Photoshop image-resource block carrying the IPTC records, exactly as libvips exposes it; xmpString decodes XMP only when it is valid UTF-8.
  • sourceByteSize is exact for Data and the file size for a file.

hokusai inspect --input photo.jpg prints the same facts as a table; --json prints one JSON object for scripts.