Перейти до вмісту
Hokusai2.2.2
ivantokar.com

Параметри входу та ліміти

InputOptions — це єдина політика декодування джерела з Data чи локального файлу. Відкриття ліниве: побудова конвеєра записує джерело та ці параметри, а файл читається, коли завершальна операція виконує конвеєр. Значення Data зберігається за copy-on-write, тож власну копію можна змінювати чи вивільняти одразу.

let image = try Hokusai(
data: upload,
options: .init(failOn: .truncated, limits: .init(maxBytes: 20_000_000, maxPixels: 50_000_000))
)
Параметр Тип За замовчуванням Значення
page Int? nil (перша сторінка) Нумерована з нуля сторінка багатосторінкового джерела (TIFF, PDF). Завантажується рівно одна сторінка; діапазони сторінок, завантаження всіх сторінок і анімований вивід не підтримуються.
access AccessMode .random .random безпечний для всіх операцій. .sequential передає потоком згори донизу з малим піком пам’яті для однопрохідних конвеєрів і завершується помилкою (як decode) для операцій, що потребують попередніх пікселів (обертання не на 90°, віддзеркалення, розумне обрізання, деякі накладання).
failOn DecodeFailureLevel .warning Коли проблема декодера стає помилкою; кумулятивно від м’якого до суворого: .none, .truncated, .error, .warning.
limits InputLimits див. нижче Захисні межі, що перевіряються до дорогої роботи з пікселями.
revalidate Bool false Оминати кеш операцій libvips під час відкриття локального файлу, щоб бачити зміни файлу за тим самим шляхом. Не впливає на Data.

InputOptions.sequential — скорочення для .init(access: .sequential).

InputLimits розрахований так, щоб зупиняти бомби декомпресії, приймаючи звичайні фотографії; сервери мають звужувати його до власної політики завантажень. Перевищення ліміту викидає HokusaiError.resource.

Ліміт За замовчуванням Коли перевіряється
maxBytes 512 МіБ До копіювання Data у нативне сховище та щодо розміру локального файлу.
maxPixels 268 402 689 (16383 × 16383) width × height завантаженої сторінки, з виявленням переповнення.
maxChannels 8 Кількість смуг.
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)" }
Випадок Результат
Зображення 1600 × 1000 з maxPixels: 1_000_000 resource (вид decodedPixels, ліміт 1 000 000, фактично 1 600 000)
Файл 310 КБ з maxBytes: 10_000 resource (вид encodedBytes, ліміт 10 000, фактично 309 729)
Напівзавантажений PNG, типовий failOn decode: «the image data could not be decoded»
Те саме, failOn: .none декодує те, що є: усі 1000 рядків, відсутня частина доповнена
Байти, що не є зображенням decode, діагностика «buffer is not in a known format»
Відсутній файл io (операція read, причина «file not found»), із завершальної операції, а не з конструктора

Випадок .none — пастка для сервісів: з failOn: .none пошкоджений файл декодується з доповненням відсутніх даних, тож кілька сотень байтів, що заявляють 130 мільйонів пікселів, коштують гігабайт і десятки секунд у межах типового maxPixels. Сервіс, що використовує .none, має також знизити maxPixels. Типовий .warning завершується помилкою швидко.

page обирає сторінку з нуля. Джерело з однією сторінкою повідомляє pages.count == 1; вибір сторінки, відмінної від 0, для однієї сторінки — це unsupported("page selection": "this image has a single page"). Сторінка за межами кінця багатосторінкового джерела — invalidOption. maxPixels застосовується до єдиної завантаженої сторінки. (У фікстурах документації немає багатосторінкового TIFF; PDF з однією сторінкою, прочитаний вище, повідомляє pages.count == 1.)

Лишайте .random, доки не виміряли, що піковий обсяг пам’яті є проблемою, і конвеєр справді однопрохідний, згори донизу (завантаження → resize → збереження). У бенчмарках Hokusai послідовний доступ робив конвеєри сильно зменшуваних JPEG значно повільнішими за типовий. Жоден режим не змінює, що декодується, лише як буферизується декодування; з .random декодер, що не вміє позиціюватися, декодує все зображення в пам’ять (або в тимчасовий файл понад дисковим порогом libvips, типово 100 МБ).