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

Зміна розміру

resize змінює розміри зображення в пікселях. Використовуйте його для мініатюр, вписування завантажень у макет або отримання точного прямокутника, як-от соціальна картка 1200 × 630. Зразок на цій сторінці — пейзаж 1600 × 1000, предмет якого, маяк, розташований у правій третині, тож дію кожного параметра добре видно.

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"))
  • Весь пейзаж, зменшений до 400 на 250 пікселів.
    width: 400WEBP · 400 × 250 · 6 KB
  • Пейзаж, обрізаний до квадрата 400 на 400 навколо маяка.
    400 × 400WEBP · 400 × 400 · 7 KB

З одним розміром інший визначається співвідношенням сторін. З обома fit вирішує, як зображення зустрічається з рамкою; за замовчуванням .cover заповнює рамку й обрізає надлишок.

Параметр Тип За замовчуванням Примітки
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"))
}
  • Квадрат 480 на 480, заповнений центральною ділянкою пейзажу.
    .coverPNG · 480 × 480 · 106 KB
  • Увесь пейзаж у квадраті 480 на 480 зі світлими полями зверху й знизу.
    .containPNG · 480 × 480 · 84 KB
  • Увесь пейзаж, розтягнутий у квадрат 480 на 480, з деформованим маяком.
    .fillPNG · 480 × 480 · 115 KB
  • Увесь пейзаж, зменшений, щоб вміститися в 480 на 480, тобто 480 на 300 пікселів.
    .insidePNG · 480 × 300 · 83 KB
  • Пейзаж, зменшений доти, доки він покриє 480 на 480, тобто 768 на 480 пікселів, без обрізання.
    .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"))
  • Емблема, збільшена зі 100 до 300 пікселів, помітно мʼякша.
    за замовчуваннямPNG · 300 × 300 · 38 KB
  • Емблема, залишена на 100 пікселях.
    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() і оберіть режим.

Ядро — це фільтр, що обчислює нові пікселі. Типове .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
  • Емблема, зменшена ядром Ланцоша 3: різкі краї.
    .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 після іншої операції цього не отримує.
Ситуація Результат
Ні 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), викидається під час виконання конвеєра, до обчислення будь-якого пікселя