Робота із зображеннями

Клас Nette\Utils\Image спрощує маніпуляції із зображеннями, такі як зміна розміру, обрізка, підвищення різкості, малювання або об'єднання кількох зображень.

PHP має великий набір функцій для маніпуляції зображеннями. Але їхній API не дуже зручний. Це був би не Nette Framework, якби він не запропонував сексуальний API.

Встановлення:

composer require nette/utils

Усі приклади передбачають створений псевдонім:

use Nette\Utils\Image;
use Nette\Utils\ImageColor;
use Nette\Utils\ImageType;

Створення зображення

Створимо нове true color зображення, наприклад, з розмірами 100×200:

$image = Image::fromBlank(100, 200);

За бажанням можна вказати колір фону (за замовчуванням чорний):

$image = Image::fromBlank(100, 200, ImageColor::rgb(125, 0, 0));

Або завантажимо зображення з файлу:

$image = Image::fromFile('nette.jpg');

Збереження зображення

Зображення можна зберегти у файл:

$image->save('resampled.jpg');

Ми можемо вказати якість стиснення в діапазоні 0..100 для JPEG (за замовчуванням 85), WEBP (за замовчуванням 80) та AVIF (за замовчуванням 30) і 0..9 для PNG (за замовчуванням 9):

$image->save('resampled.jpg', 80); // JPEG, якість 80%

Якщо з розширення файлу не зрозумілий формат, його можна вказати константою:

$image->save('resampled.tmp', null, ImageType::JPEG);

Зображення можна замість диска записати у змінну:

$data = $image->toString(ImageType::JPEG, 80); // JPEG, якість 80%

або надіслати безпосередньо в браузер із відповідним HTTP заголовком Content-Type:

// надсилає заголовок Content-Type: image/png
$image->send(ImageType::PNG);

Формати

Підтримувані формати: JPEG, PNG, GIF, WebP, AVIF та BMP, однак їх також має підтримувати ваша версія PHP, що можна перевірити функцією isTypeSupported(). Анімація не підтримується.

Формат представлений константами ImageType::JPEG, ImageType::PNG, ImageType::GIF, ImageType::WEBP, ImageType::AVIF та ImageType::BMP.

$supported = Image::isTypeSupported(ImageType::JPEG);

Потрібно визначити формат зображення під час завантаження? Метод поверне його у другому параметрі:

$image = Image::fromFile('nette.jpg', $type);

Саме визначення без завантаження зображення виконує Image::detectTypeFromFile().

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

Частою операцією є зміна розмірів зображення. Поточні розміри повертають методи getWidth() та getHeight().

Для зміни служить метод resize(). Приклад пропорційної зміни розміру так, щоб він не перевищував розміри 500×300 пікселів (або ширина буде точно 500 px, або висота буде точно 300 px, один із розмірів обчислюється так, щоб зберегти співвідношення сторін):

$image->resize(500, 300);

Можна вказати лише один розмір, а другий обчислиться:

$image->resize(500, null); // ширина 500px, висота обчислюється

$image->resize(null, 300); // ширина обчислюється, висота 300px

Будь-який розмір можна вказати також у відсотках:

$image->resize('75%', 300); // 75 % × 300px

Поведінку resize можна змінити за допомогою таких прапорців. Усі, крім Image::Stretch, зберігають співвідношення сторін.

Прапорець	Опис
`Image::OrSmaller` (за замовчуванням)	кінцеві розміри будуть меншими або рівними заданим розмірам
`Image::OrBigger`	заповнює (і, можливо, перевищує в одному вимірі) цільову область
`Image::Cover`	заповнює цільову область і обрізає те, що виходить за межі
`Image::ShrinkOnly`	тільки зменшення (запобігає розтягуванню маленького зображення)
`Image::Stretch`	не зберігати співвідношення сторін

Прапорці вказуються як третій аргумент функції:

$image->resize(500, 300, Image::OrBigger);

Прапорці можна комбінувати:

$image->resize(500, 300, Image::ShrinkOnly | Image::Stretch);

Зображення можна вертикально або горизонтально перевернути, вказавши один із розмірів (або обидва) як від'ємне число:

$flipped = $image->resize(null, '-100%'); // перевернути вертикально

$flipped = $image->resize('-100%', '-100%'); // повернути на 180°

$flipped = $image->resize(-125, 500); // змінити розмір і перевернути горизонтально

Після зменшення зображення можна покращити його вигляд легким підвищенням різкості:

$image->sharpen();

Обрізка

Для обрізки служить метод crop():

$image->crop($left, $top, $width, $height);

Подібно до resize(), усі значення можуть бути вказані у відсотках. Відсотки для $left та $top обчислюються з решти місця, подібно до CSS властивості background-position:

$image->crop('100%', '50%', '80%', '80%');

Зображення також можна обрізати автоматично, наприклад, обрізати чорні краї:

$image->cropAuto(IMG_CROP_BLACK);

Метод cropAuto() є об'єктною заміною функції imagecropauto(), в її документації ви знайдете додаткову інформацію.

Кольори

Метод ImageColor::rgb() дозволяє визначити колір за допомогою значень червоного, зеленого та синього (RGB). За бажанням ви також можете вказати значення прозорості в діапазоні від 0 (повністю прозорий) до 1 (повністю непрозорий), так само, як у CSS.

$color = ImageColor::rgb(255, 0, 0); // Червоний
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // Напівпрозорий синій

Метод ImageColor::hex() дозволяє визначити колір за допомогою шістнадцяткового формату, подібно до CSS. Підтримує формати #rgb, #rrggbb, #rgba та #rrggbbaa:

$color = ImageColor::hex("#F00"); // Червоний
$transparentGreen = ImageColor::hex("#00FF0080"); // Напівпрозорий зелений

Кольори можна використовувати в інших методах, таких як ellipse(), fill() тощо.

Малювання та редагування

Можеш малювати, можеш писати, але листя не рвати. Вам доступні всі функції PHP для роботи із зображеннями, див. Přehled metod, але в об'єктній обгортці:

$image->filledEllipse($centerX, $centerY, $width, $height, ImageColor::rgb(255, 0, 0));

Оскільки функції PHP для малювання прямокутників непрактичні через визначення координат, клас Image пропонує їхні заміни у вигляді функцій rectangleWH() та filledRectangleWH().

Об'єднання кількох зображень

В зображення можна легко вставити інше зображення:

$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, ImageColor::rgb(52, 132, 210));

// координати можна вказати знову у відсотках
$blank->place($logo, '80%', '80%'); // вставимо поблизу правого нижнього кута

При вставці враховується альфа-канал, крім того, ми можемо впливати на прозорість вставлюваного зображення (створимо так званий водяний знак):

$blank->place($image, '80%', '80%', 25); // прозорість 25 %

Такий API справді приємно використовувати!

Огляд методів

static fromBlank (int $width, int $height, ?ImageColor $color=null): Image

Створює нове true color зображення заданих розмірів. Колір за замовчуванням — чорний.

static fromFile (string $file, int &$detectedFormat=null): Image

Завантажує зображення з файлу і повертає його тип у $detectedFormat.

static fromString (string $s, int &$detectedFormat=null): Image

Завантажує зображення з рядка і повертає його тип у $detectedFormat.

static rgb (int $red, int $green, int $blue, int $transparency=0): array

Цю функцію замінив клас ImageColor, див. кольори.

static typeToExtension (int $type): string

Повертає розширення файлу для даного типу.

static typeToMimeType (int $type): string

Повертає mime-тип для даного типу.

static extensionToType (string $extension): int

Повертає тип зображення за розширенням файлу.

static detectTypeFromFile (string $file, int &$width=null, int &$height=null): ?int

Повертає тип зображення, а в параметрах $width та $height також його розміри.

static detectTypeFromString (string $s, int &$width=null, int &$height=null): ?int

Повертає тип зображення з рядка, а в параметрах $width та $height також його розміри.

static isTypeSupported (int $type): bool

Перевіряє, чи підтримується даний тип зображення.

static getSupportedTypes(): array

Повертає масив підтримуваних типів зображення.

static calculateTextBox (string $text, string $fontFile, float $size, float $angle=0, array $options=[]): array

Обчислює розміри прямокутника, який охоплює текст певним шрифтом та розміром. Повертає асоціативний масив, що містить ключі left, top, width, height. Лівий край може бути від'ємним, якщо текст починається з лівого підрізання.

affine (array $affine, ?array $clip=null): Image

Повертає зображення, що містить афінно трансформоване зображення src, використовуючи необов'язкову область обрізки. (більше).

affineMatrixConcat (array $m1, array $m2): array

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

affineMatrixGet (int $type, ?mixed $options=null): array

Повертає матрицю трансформації. (більше)

alphaBlending (bool $on): void

Дозволяє два різних режими малювання в зображеннях truecolor. У режимі змішування компонент альфа-каналу кольору, що використовується у всіх функціях малювання, таких як setPixel(), визначає, наскільки має бути дозволено просвічування основного кольору. В результаті існуючий колір автоматично змішується з кольором малювання в цій точці, і результат зберігається в зображенні. Отриманий піксель є непрозорим. У режимі без змішування колір малювання копіюється буквально з інформацією про альфа-канал і замінює цільовий піксель. Режим змішування недоступний при малюванні на палітрових зображеннях. (більше)

antialias (bool $on): void

Активуйте малювання згладжених ліній та полігонів. Не підтримує альфа-канали. Працює тільки з зображеннями truecolor.

Використання згладжених примітивів з прозорим кольором фону може призвести до несподіваних результатів. Метод змішування використовує колір фону так само, як і всі інші кольори. (більше)

arc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color): void

Малює дугу кола з центром у заданих координатах. (більше)

colorAllocate (int $red, int $green, int $blue): int

Повертає ідентифікатор кольору, що представляє колір, складений із заданих компонентів RGB. Має бути викликаний для створення кожного кольору, який буде використовуватися в зображенні. (більше)

colorAllocateAlpha (int $red, int $green, int $blue, int $alpha): int

Поводиться так само, як colorAllocate(), з додаванням параметра прозорості $alpha. (більше)

colorAt (int $x, int $y): int

Повертає індекс кольору пікселя у вказаному місці зображення. Якщо зображення є truecolor, ця функція повертає значення RGB цього пікселя як ціле число. Використовуйте бітовий зсув та бітову маску для доступу до окремих значень червоної, зеленої та синьої компонент: (більше)

colorClosest (int $red, int $green, int $blue): int

Повертає індекс кольору в палітрі зображення, який є «найближчим» до заданого значення RGB. “Відстань” між бажаним кольором та кожним кольором у палітрі обчислюється так, ніби значення RGB представляють точки в тривимірному просторі. (більше)

colorClosestAlpha (int $red, int $green, int $blue, int $alpha): int

Повертає індекс кольору в палітрі зображення, який є «найближчим» до заданого значення RGB та рівня $alpha. (більше)

colorClosestHWB (int $red, int $green, int $blue): int

Отримайте індекс кольору, який має відтінок, білий та чорний колір, найближчі до заданого кольору. (більше)

colorDeallocate (int $color): void

Де-алокує колір, раніше виділений за допомогою colorAllocate() або colorAllocateAlpha(). (більше)

colorExact (int $red, int $green, int $blue): int

Повертає індекс заданого кольору в палітрі зображення. (більше)

colorExactAlpha (int $red, int $green, int $blue, int $alpha): int

Повертає індекс заданого кольору + альфа в палітрі зображення. (більше)

colorMatch (Image $image2): void

Пристосовує кольори палітри до другого зображення. (більше)

colorResolve (int $red, int $green, int $blue): int

Повертає індекс кольору для бажаного кольору, або точний колір, або найближчу можливу альтернативу. (більше)

colorResolveAlpha (int $red, int $green, int $blue, int $alpha): int

Повертає індекс кольору для бажаного кольору, або точний колір, або найближчу можливу альтернативу. (більше)

colorSet (int $index, int $red, int $green, int $blue): void

Встановлює заданий індекс у палітрі на заданий колір. (більше)

colorsForIndex (int $index): array

Отримує колір зазначеного індексу. (більше)

colorsTotal(): int

Повертає кількість кольорів у палітрі зображення. (більше)

colorTransparent (?int $color=null): int

Отримує або встановлює прозорий колір у зображенні. (більше)

convolution (array $matrix, float $div, float $offset): void

Застосовує до зображення матрицю згортки, використовуючи заданий коефіцієнт та зсув. (більше)

Потребує наявності Bundled GD extension, тому може працювати не скрізь.

copy (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH): void

Копіює частину $src на зображення, починаючи з координат $srcX, $srcY з шириною $srcW та висотою $srcH. Визначена частина буде скопійована на координати $dstX та $dstY. (більше)

copyMerge (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void

copyMergeGray (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void

Ця функція ідентична copyMerge(), за винятком того, що при злитті зберігає відтінок джерела, перетворюючи цільові пікселі на сіру шкалу перед операцією копіювання. (більше)

copyResampled (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

Копіює прямокутну частину одного зображення на інше зображення, плавно інтерполюючи значення пікселів, так що, зокрема, зменшення розміру зображення все ще зберігає велику чіткість.

Іншими словами, copyResampled() бере прямокутну область з $src шириною $srcW та висотою $srcH в позиції ($srcX, $srcY) і розміщує її в прямокутній області зображення шириною $dstW та висотою $dstH в позиції ($dstX, $dstY).

Якщо вихідні та цільові координати, ширина та висота відрізняються, виконується відповідне розтягування або зменшення фрагмента зображення. Координати відносяться до лівого верхнього кута. Цю функцію можна використовувати для копіювання областей в тому ж зображенні, але якщо області перекриваються, результати будуть непередбачуваними. (більше)

copyResized (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

Копіює прямокутну частину одного зображення на інше зображення. Іншими словами, copyResized() отримує прямокутну область з $src шириною $srcW та висотою $srcH в позиції ($srcX, $srcY) і розміщує її в прямокутній області зображення шириною $dstW ] та висотою $dstH в позиції ($dstX, $dstY).

crop (int|string $left, int|string $top, int|string $width, int|string $height): Image

Обрізає зображення до заданої прямокутної області. Розміри можна задавати як цілі числа в пікселях або рядки у відсотках (наприклад, '50%').

cropAuto (int $mode=-1, float $threshold=.5, ?ImageColor $color=null): Image

Автоматично обрізає зображення відповідно до заданого $mode. (більше)

ellipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

Малює еліпс з центром у заданих координатах. (більше)

fill (int $x, int $y, ImageColor $color): void

Заповнює область, починаючи з заданої координати (лівий верхній кут — 0, 0), заданим $color. (більше)

filledArc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color, int $style): void

Малює часткову дугу з центром у заданих координатах. (більше)

filledEllipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

Малює еліпс з центром у заданих координатах. (більше)

filledPolygon (array $points, ImageColor $color): void

Створює в зображенні заповнений багатокутник. (більше)

filledRectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Створює прямокутник, заповнений $color в зображенні, починаючи з точки $x1 & $y1 і закінчуючи точкою $x2 & $y2. Точка 0, 0 — це лівий верхній кут зображення. (більше)

filledRectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

Створює прямокутник, заповнений $color в зображенні, починаючи з точки $left & $top з шириною $width та висотою $height. Точка 0, 0 — це лівий верхній кут зображення.

fillToBorder (int $x, int $y, int $border, ImageColor $color): void

Виконує заливку, колір межі якої визначено за допомогою $border. Початковою точкою заливки є $x, $y (лівий верхній кут — 0, 0), а область заповнюється кольором $color. (більше)

filter (int $filtertype, int …$args): void

Застосовує заданий фільтр $filtertype до зображення. (більше)

flip (int $mode): void

Перевертає зображення за допомогою заданого $mode. (більше)

ftText (float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array

Написати текст на зображенні. (більше)

gammaCorrect (float $inputgamma, float $outputgamma): void

Застосовує гамма-корекцію до зображення відносно вхідної та вихідної гамми. (більше)

getClip(): array

Повертає поточну область обрізки, тобто область, за межами якої не будуть намальовані жодні пікселі. (більше)

getHeight(): int

Повертає висоту зображення.

getImageResource(): resource|GdImage

Повертає оригінальний ресурс.

getWidth(): int

Повертає ширину зображення.

interlace (?int $interlace=null): int

Вмикає або вимикає режим черезрядкової розгортки. Якщо режим черезрядкової розгортки встановлено і зображення зберігається як JPEG, воно буде збережено як прогресивний JPEG. (більше)

isTrueColor(): bool

Визначає, чи є зображення truecolor. (більше)

layerEffect (int $effect): void

Встановіть прапорець змішування альфа, щоб використовувати ефекти шарів. (більше)

line (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Малює лінію між двома заданими точками. (більше)

openPolygon (array $points, ImageColor $color): void

Малює на зображенні відкритий багатокутник. На відміну від polygon(), між останньою та першою точкою лінія не малюється. (більше)

paletteCopy (Image $source): void

Копіює палітру з $source до зображення. (більше)

paletteToTrueColor(): void

Перетворює зображення на основі палітри на повнокольорове зображення. (більше)

place (Image $image, int|string $left=0, int|string $top=0, int $opacity=100): Image

Копіює $image до зображення на координати $left та $top. Координати можна задавати як цілі числа в пікселях або рядки у відсотках (наприклад, '50%').

polygon (array $points, ImageColor $color): void

Створює в зображенні багатокутник. (більше)

rectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Створює прямокутник на заданих координатах. (більше)

rectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

Створює прямокутник на заданих координатах.

resize (int|string $width, int|string $height, int $flags=Image::OrSmaller): Image

Змінює розмір зображення, більше інформації. Розміри можна задавати як цілі числа в пікселях або рядки у відсотках (наприклад, '50%').

resolution (?int $resX=null, ?int $resY=null): mixed

Встановлює або повертає роздільну здатність зображення в DPI (точки на дюйм). Якщо не задано жодного з необов'язкових параметрів, поточна роздільна здатність повертається як індексований масив. Якщо задано лише $resX, горизонтальна та вертикальна роздільна здатність встановлюються на це значення. Якщо задано обидва необов'язкові параметри, горизонтальна та вертикальна роздільна здатність встановлюються на ці значення.

Роздільна здатність використовується лише як метаінформація, коли зображення читаються та записуються у формати, що підтримують цей тип інформації (наразі PNG та JPEG). Це не впливає на жодні операції малювання. Стандартна роздільна здатність нових зображень — 96 DPI. (більше)

rotate (float $angle, int $backgroundColor): Image

Повертає зображення за допомогою заданого $angle у градусах. Центр обертання — це центр зображення, і повернуте зображення може мати інші розміри, ніж оригінальне зображення. (більше)

Потребує наявності Bundled GD extension, тому може працювати не скрізь.

save (string $file, ?int $quality=null, ?int $type=null): void

Зберігає зображення у файл.

Якість стиснення знаходиться в діапазоні 0..100 для JPEG (за замовчуванням 85), WEBP (за замовчуванням 80) та AVIF (за замовчуванням 30) і 0..9 для PNG (за замовчуванням 9). Якщо тип не зрозумілий з розширення файлу, ви можете вказати його за допомогою однієї з констант ImageType.

saveAlpha (bool $saveflag): void

Встановлює прапорець, чи зберігати повну інформацію про альфа-канал при збереженні зображень PNG (на відміну від одноколірної прозорості).

Альфа-змішування має бути вимкнено (alphaBlending(false)), щоб альфа-канал зберігся на першому місці. (більше)

scale (int $newWidth, int $newHeight=-1, int $mode=IMG_BILINEAR_FIXED): Image

Масштабує зображення за допомогою заданого алгоритму інтерполяції. (більше)

send (int $type=ImageType::JPEG, ?int $quality=null): void

Виводить зображення в браузер.

Якість стиснення знаходиться в діапазоні 0..100 для JPEG (за замовчуванням 85), WEBP (за замовчуванням 80) та AVIF (за замовчуванням 30) і 0..9 для PNG (за замовчуванням 9).

setBrush (Image $brush): void

Встановлює зображення пензля, яке буде використовуватися у всіх функціях малювання ліній (наприклад, line() та polygon()) при малюванні спеціальними кольорами IMG_COLOR_BRUSHED або IMG_COLOR_STYLEDBRUSHED. (більше)

setClip (int $x1, int $y1, int $x2, int $y2): void

Встановлює поточну область обрізки, тобто область, за межами якої не будуть намальовані жодні пікселі. (більше)

setInterpolation (int $method=IMG_BILINEAR_FIXED): void

Встановлює метод інтерполяції, який впливає на методи rotate() та affine(). (більше)

setPixel (int $x, int $y, ImageColor $color): void

Малює піксель на заданій координаті. (більше)

setStyle (array $style): void

Встановлює стиль, який мають використовувати всі функції малювання ліній (наприклад, line() та polygon()) при малюванні спеціальним кольором IMG_COLOR_STYLED або ліній зображень з кольором IMG_COLOR_STYLEDBRUSHED. (більше)

setThickness (int $thickness): void

Встановлює товщину ліній при малюванні прямокутників, багатокутників, дуг тощо на $thickness пікселів. (більше)

setTile (Image $tile): void

Встановлює зображення плитки, яке буде використовуватися у всіх функціях заповнення областей (наприклад, fill() та filledPolygon()), коли заповнюється спеціальним кольором IMG_COLOR_TILED.

Плитка — це зображення, яке використовується для заповнення області повторюваним візерунком. Будь-яке зображення можна використовувати як плитку, а встановивши прозорий індекс кольору зображення плитки за допомогою colorTransparent(), можна створити плитку, де будуть просвічувати певні частини базової області. (більше)

sharpen(): Image

Підвищує різкість зображення.

Потребує наявності Bundled GD extension, тому може працювати не скрізь.

toString (int $type=ImageType::JPEG, ?int $quality=null): string

Зберігає зображення в рядок.

trueColorToPalette (bool $dither, int $ncolors): void

Перетворює зображення truecolor на палітрове. (більше)

ttfText (float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array

Виводить заданий текст на зображення. (більше)