Параметри входу та ліміти
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).
Ліміти
Section titled “Ліміти”InputLimits розрахований так, щоб зупиняти бомби декомпресії, приймаючи звичайні фотографії; сервери мають звужувати його до власної політики завантажень. Перевищення ліміту викидає HokusaiError.resource.
| Ліміт | За замовчуванням | Коли перевіряється |
|---|---|---|
maxBytes |
512 МіБ | До копіювання Data у нативне сховище та щодо розміру локального файлу. |
maxPixels |
268 402 689 (16383 × 16383) | width × height завантаженої сторінки, з виявленням переповнення. |
maxChannels |
8 | Кількість смуг. |
Як виглядає кожен збій
Section titled “Як виглядає кожен збій”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 завершується помилкою швидко.
Сторінки
Section titled “Сторінки”page обирає сторінку з нуля. Джерело з однією сторінкою повідомляє pages.count == 1; вибір сторінки, відмінної від 0, для однієї сторінки — це unsupported("page selection": "this image has a single page"). Сторінка за межами кінця багатосторінкового джерела — invalidOption. maxPixels застосовується до єдиної завантаженої сторінки. (У фікстурах документації немає багатосторінкового TIFF; PDF з однією сторінкою, прочитаний вище, повідомляє pages.count == 1.)
Вибір доступу
Section titled “Вибір доступу”Лишайте .random, доки не виміряли, що піковий обсяг пам’яті є проблемою, і конвеєр справді однопрохідний, згори донизу (завантаження → resize → збереження). У бенчмарках Hokusai послідовний доступ робив конвеєри сильно зменшуваних JPEG значно повільнішими за типовий. Жоден режим не змінює, що декодується, лише як буферизується декодування; з .random декодер, що не вміє позиціюватися, декодує все зображення в пам’ять (або в тимчасовий файл понад дисковим порогом libvips, типово 100 МБ).