Зміна розміру
resize змінює розміри зображення в пікселях. Використовуйте його для мініатюр, вписування завантажень у макет або отримання точного прямокутника, як-от соціальна картка 1200 × 630. Зразок на цій сторінці — пейзаж 1600 × 1000, предмет якого, маяк, розташований у правій третині, тож дію кожного параметра добре видно.
Мінімальний приклад
Section titled “Мінімальний приклад”let image = try Hokusai(url: URL(fileURLWithPath: "scene.png"))
// One dimension: the aspect ratio is kept.try await image.resize(width: 400).webp(quality: 85) .write(to: URL(fileURLWithPath: "width-400.webp"))
// Both dimensions: `fit` decides how the image meets the box (default: .cover).try await image.resize(width: 400, height: 400).webp(quality: 85) .write(to: URL(fileURLWithPath: "box-400.webp"))
width: 400WEBP · 400 × 250 · 6 KB 
400 × 400WEBP · 400 × 400 · 7 KB
З одним розміром інший визначається співвідношенням сторін. З обома fit вирішує, як зображення зустрічається з рамкою; за замовчуванням .cover заповнює рамку й обрізає надлишок.
Параметри
Section titled “Параметри”| Параметр | Тип | За замовчуванням | Примітки |
|---|---|---|---|
width |
Int? |
nil |
Пікселі, 1…2 147 483 647. Потрібен принаймні один із width і height. |
height |
Int? |
nil |
Той самий діапазон. |
fit |
ResizeFit |
.cover |
.inside, .outside, .fill, .cover, .contain. |
position |
ResizePosition |
.center |
Звідки береться обрізання .cover: дев’ять сторін світу, .attention, .entropy. |
kernel |
ResizeKernel |
.lanczos3 |
.nearest, .linear, .cubic, .mitchell, .lanczos2, .lanczos3, .mks2013, .mks2021. |
withoutEnlargement |
Bool |
false |
Залишити поточний розмір замість збільшення. |
withoutReduction |
Bool |
false |
Залишити поточний розмір замість зменшення. |
background |
Color |
.transparent |
Колір поля для .contain. |
Виклик без width і height або зі значенням поза діапазоном одразу, під час побудови конвеєра, викидає HokusaiError.invalidOption.
Вибір режиму вписування
Section titled “Вибір режиму вписування”let image = try Hokusai(url: URL(fileURLWithPath: "scene.png"))let box = (width: 480, height: 480)
let fits: [(String, ResizeFit)] = [ ("cover", .cover), ("contain", .contain), ("fill", .fill), ("inside", .inside), ("outside", .outside),]for (name, fit) in fits { try await image .resize(width: box.width, height: box.height, fit: fit, background: Color(red: 0.93, green: 0.93, blue: 0.9)) .png() .write(to: URL(fileURLWithPath: "\(name).png"))}
.coverPNG · 480 × 480 · 106 KB 
.containPNG · 480 × 480 · 84 KB 
.fillPNG · 480 × 480 · 115 KB 
.insidePNG · 480 × 300 · 83 KB 
.outsidePNG · 768 × 480 · 154 KB
Усі п’ять режимів для рамки 480 × 480. Зверніть увагу на розміри: точну задану рамку повертають лише .cover, .contain і .fill.
| Режим | Співвідношення сторін | Розмір результату | Для чого |
|---|---|---|---|
.cover |
зберігається; надлишок обрізається | рівно width × height |
мініатюри й картки, що мають бути заповнені (не з withoutEnlargement на малих джерелах, див. нижче) |
.contain |
зберігається; решта заповнюється background |
рівно width × height |
показ усього зображення у фіксованому слоті |
.fill |
ігнорується; розтягується | рівно width × height |
рідко; свідома деформація |
.inside |
зберігається | найбільший розмір у межах обох обмежень | обмеження «не більше ніж» |
.outside |
зберігається | найменший розмір, що покриває обидва обмеження | коли ви самі обріжете |
Звідки береться обрізання
Section titled “Звідки береться обрізання”Обрізання .cover відкидає частину зображення, а position обирає, що залишиться. За замовчуванням рамка центрується. Тут із пейзажу вирізано квадрат:
let image = try Hokusai(url: URL(fileURLWithPath: "scene.png"))
// A square cover crop keeps only part of the landscape. `position` chooses which part.let positions: [(String, ResizePosition)] = [ ("center", .center), ("west", .west), ("east", .east), ("attention", .attention), ("entropy", .entropy),]for (name, position) in positions { try await image .resize(width: 360, height: 360, fit: .cover, position: position) .png() .write(to: URL(fileURLWithPath: "\(name).png"))}
.centerPNG · 360 × 360 · 73 KB 
.westPNG · 360 × 360 · 53 KB 
.eastPNG · 360 × 360 · 81 KB 
.attentionPNG · 360 × 360 · 81 KB 
.entropyPNG · 360 × 360 · 78 KB
Дев’ять позицій сторін світу (.north, .south, .east, .west, чотири кути та .center) прив’язують рамку обрізання до цієї сторони. .attention віддає перевагу відтінкам шкіри, насиченому кольору й деталям; .entropy — ділянці з найбільшою локальною варіацією. Обидва залежать від вмісту й роблять той самий вибір, що й smartCrop. position не впливає на жоден режим, крім .cover.
Без збільшення, без зменшення
Section titled “Без збільшення, без зменшення”let small = try Hokusai(url: URL(fileURLWithPath: "emblem.png")).resize(width: 100)
// Without a guard, a larger width enlarges the 100-pixel image.let enlarged = try await small.resize(width: 300).png().data()// withoutEnlargement leaves an image that is already smaller than the request alone.let guarded = try await small.resize(width: 300, withoutEnlargement: true).png().data()// withoutReduction is the opposite guard: it only ever makes the image larger.let notReduced = try await small.resize(width: 50, withoutReduction: true).png().data()
print("enlarged", enlarged.info.width, "guarded", guarded.info.width, "not reduced", notReduced.info.width)try guarded.data.write(to: URL(fileURLWithPath: "guarded.png"))try enlarged.data.write(to: URL(fileURLWithPath: "enlarged.png"))
за замовчуваннямPNG · 300 × 300 · 38 KB 
withoutEnlargementPNG · 100 × 100 · 3 KB
Коли обчислений розмір більший за поточний у будь-якому вимірі, withoutEnlargement: true замінює його поточним розміром; пропорційного обмеження немає. withoutReduction — дзеркальний. Використовуйте withoutEnlargement для обмежень «не ширше ніж», коли надходять зображення невідомого розміру. Що поверне запит із захистом, залежить від режиму, а одна комбінація завершується помилкою:
// A 100 × 100 image and a 480 × 480 request that would enlarge it.let small = try Hokusai(url: URL(fileURLWithPath: "emblem.png")).resize(width: 100)
for (name, fit) in [("inside", ResizeFit.inside), ("contain", .contain), ("cover", .cover)] { do { let output = try await small .resize(width: 480, height: 480, fit: fit, withoutEnlargement: true, background: .white) .png().data() print(name, "→", output.info.width, "×", output.info.height) } catch { print(name, "→ throws", error) }}Режим (запит 480 × 480, джерело 100 × 100, withoutEnlargement: true) |
Результат |
|---|---|
.inside |
100 × 100: зображення не змінюється |
.contain |
480 × 480: зображення лишається 100 пікселів і доповнюється полями до рамки |
.cover |
викидає HokusaiError.transform (extract): незбільшене зображення менше за рамку обрізання |
Отже, для рамки на зображенні, що може бути малим, використовуйте .inside для обмеження або .contain для слота з полями, а не .cover; або спершу прочитайте metadata() і оберіть режим.
Ядра ресемплінгу
Section titled “Ядра ресемплінгу”Ядро — це фільтр, що обчислює нові пікселі. Типове .lanczos3 різке й підходить майже для всього. .nearest копіює пікселі без змішування, зберігає чіткі краї пікселів і підходить для піксель-арту; інші обмінюють різкість на плавність. Кожне зображення нижче зменшено до 40 пікселів вказаним ядром, а потім збільшено лише через .nearest, щоб було видно пікселі.
let image = try Hokusai(url: URL(fileURLWithPath: "emblem.png"))
// Shrinking and then viewing 4× larger shows how each kernel resamples.let kernels: [(String, ResizeKernel)] = [ ("nearest", .nearest), ("linear", .linear), ("cubic", .cubic), ("mitchell", .mitchell), ("lanczos3", .lanczos3),]for (name, kernel) in kernels { try await image .resize(width: 40, kernel: kernel) // shrink to 40 pixels .resize(width: 160, kernel: .nearest) // enlarge with .nearest only to make pixels visible .png() .write(to: URL(fileURLWithPath: "\(name).png"))}
.nearestPNG · 160 × 160 · 1 KB 
.linearPNG · 160 × 160 · 2 KB 
.cubicPNG · 160 × 160 · 2 KB 
.mitchellPNG · 160 × 160 · 2 KB 
.lanczos3PNG · 160 × 160 · 2 KB
.mks2013 і .mks2021 (Magic Kernel Sharp) потребують libvips 8.17 або новішої, вище за базову 8.16. На старішій збірці запит такого ядра викидає HokusaiError.unsupported під час додавання кроку, тож перевірте Hokusai.capabilities() або обробіть помилку. Версію libvips показує hokusai info.
Поєднання з іншими операціями
Section titled “Поєднання з іншими операціями”- Порядок змінює пікселі, а не лише швидкість. Зміна розміру перед розмиттям розмиває в новому масштабі; розмиття, а потім зменшення дає інший, м’якший результат. Дивіться Порядок операцій.
- Спершу орієнтація. Фото з телефона мають орієнтацію EXIF. Ставте
autoOrient()передresize, інакше портретне фото змінюється з поміняними шириною й висотою. Дивіться Орієнтація. extractпісляresizeадресує пікселі вже зміненого зображення, а не оригіналу (Обрізання та полотно).- Зменшення під час завантаження. Коли конвеєр нерухомого JPEG або WebP починається з
resize(за потреби післяautoOrient), декодер масштабує під час читання. Розміри виводу ідентичні звичайному шляху; лише роботи менше.resizeпісля іншої операції цього не отримує.
Помилки та обмеження
Section titled “Помилки та обмеження”| Ситуація | Результат |
|---|---|
Ні width, ні height, або значення поза 1…Int32.max |
HokusaiError.invalidOption, викидається під час побудови конвеєра |
Компонента кольору background поза 0…1 |
HokusaiError.invalidOption, викидається одразу |
.mks2013 / .mks2021 на libvips старішій за 8.17 |
HokusaiError.unsupported, викидається під час додавання кроку |
.cover з обома розмірами й withoutEnlargement: true на зображенні, меншому за рамку |
HokusaiError.transform (extract), викидається під час виконання конвеєра |
Результат понад RuntimeConfiguration.maxOutputPixels (за замовчуванням 2³⁰ пікселів) |
HokusaiError.resource (outputPixels), викидається під час виконання конвеєра, до обчислення будь-якого пікселя |
Пов’язане
Section titled “Пов’язане”- Обрізання та полотно:
extract,extend,trim,smartCrop - Кодування та вивід: формати виводу, використані вище
- Рецепт соціальної картки