Skip to content
Hokusai2.2.2
ivantokar.com

Input options & limits

InputOptions is the single policy for decoding a source from Data or a local file. Opening is lazy: constructing a pipeline records the source and these options, and the file is read when a terminal evaluates the pipeline. A Data value is retained copy-on-write, so you may mutate or release your own copy immediately.

let image = try Hokusai(
data: upload,
options: .init(failOn: .truncated, limits: .init(maxBytes: 20_000_000, maxPixels: 50_000_000))
)
Option Type Default Meaning
page Int? nil (first page) Zero-based page of a multi-page source (TIFF, PDF). Exactly one page is loaded; page ranges, all-page loading and animation output are not supported.
access AccessMode .random .random is safe for every operation. .sequential streams top-to-bottom with low peak memory for single-pass pipelines, and fails (as decode) for operations that need earlier pixels (rotation by non-90° angles, flips, smart crop, some compositing).
failOn DecodeFailureLevel .warning When a decoder problem becomes an error, cumulative from permissive to strict: .none, .truncated, .error, .warning.
limits InputLimits see below Defensive bounds checked before expensive pixel work.
revalidate Bool false Bypass libvips’ operation cache when opening a local file, so changes to a file at the same path are seen. No effect for Data.

InputOptions.sequential is a shorthand for .init(access: .sequential).

InputLimits is sized to stop decompression bombs while accepting ordinary photographs; servers should tighten it to their own upload policy. Exceeding a limit throws HokusaiError.resource.

Limit Default Checked
maxBytes 512 MiB Before Data is copied into native storage, and against a local file’s size.
maxPixels 268,402,689 (16383 × 16383) width × height of the loaded page, with overflow detection.
maxChannels 8 The number of bands.
func attempt(_ name: String, _ run: () async throws -> String) async {
do { print(name, "→", try await run()) } catch { print(name, "→ throws", error) }
}
let bytes = try Data(contentsOf: URL(fileURLWithPath: "scene.png"))
// Limits are checked before any pixel work.
await attempt("maxPixels 1,000,000") {
let image = try Hokusai(data: bytes, options: .init(limits: .init(maxPixels: 1_000_000)))
return "\(try await image.png().data().info.width)"
}
await attempt("maxBytes 10,000") {
let image = try Hokusai(data: bytes, options: .init(limits: .init(maxBytes: 10_000)))
return "\(try await image.png().data().info.width)"
}
// A truncated upload: the default failOn (.warning) rejects it, .none decodes what is there.
let truncated = bytes.prefix(bytes.count / 2)
await attempt("truncated, default") {
let image = try Hokusai(data: truncated)
return "\(try await image.jpeg().data().info.height) rows"
}
await attempt("truncated, failOn .none") {
let image = try Hokusai(data: truncated, options: .init(failOn: .none))
return "\(try await image.jpeg().data().info.height) rows"
}
// Garbage is not an image, whatever the options.
await attempt("not an image") { "\(try await Hokusai(data: Data("hello".utf8)).png().data().info.width)" }
// A missing file is an I/O error from the terminal, not from the constructor.
await attempt("missing file") { "\(try await Hokusai(url: URL(fileURLWithPath: "missing.png")).png().data().info.width)" }
Case Result
A 1600 × 1000 image with maxPixels: 1_000_000 resource (kind decodedPixels, limit 1,000,000, actual 1,600,000)
A 310 KB file with maxBytes: 10_000 resource (kind encodedBytes, limit 10,000, actual 309,729)
A half-uploaded PNG, default failOn decode: “the image data could not be decoded”
The same, failOn: .none decodes what is there: the full 1000 rows, with the missing part padded
Bytes that are not an image decode, diagnostic “buffer is not in a known format”
A missing file io (operation read, reason “file not found”), from the terminal, not the constructor

The .none case is a trap for services: with failOn: .none a damaged file is decoded with the missing data padded, so a few hundred bytes that claim 130 million pixels cost a gigabyte and tens of seconds inside the default maxPixels. A service that uses .none should also lower maxPixels. The default .warning fails fast.

page selects a zero-based page. A source with one page reports pages.count == 1; selecting a page other than 0 of a single-page source is unsupported("page selection": "this image has a single page"). A page beyond the end of a multi-page source is invalidOption. maxPixels applies to the one page that is loaded. (The documentation fixtures do not include a multi-page TIFF; the PDF of one page read back above reports pages.count == 1.)

Keep .random unless you have measured that peak memory is a problem and the pipeline is genuinely single-pass and top-to-bottom (load → resize → save). In Hokusai’s benchmarks, sequential access made heavily downscaled JPEG pipelines significantly slower than the default. Neither mode changes what is decoded, only how the decode is buffered; with .random, a decoder that cannot seek decodes the whole image into memory (or a temporary file above libvips’ disc threshold, 100 MB by default).