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

Класс 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 для работы с изображениями, см. #Обзор методов, но в объектной обертке:

$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

Выводит заданный текст на изображение. (подробнее)