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

Класс Nette\Utils\Image позволяет легко манипулировать изображениями, например, изменять размер, обрезать, повышать резкость, рисовать или соединять несколько изображений.

PHP имеет обширный набор функций для работы с изображениями. Но их API не очень удобен. Это был бы не Nette Framework, если бы не придумали сексуальный API.

Установка:

composer require nette/utils

Во всех примерах предполагается, что псевдоним уже создан:

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

Создание изображения

Создайте новое истинно цветное изображение, например, размером 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%'); // flip vertical

$flipped = $image->resize('-100%', '-100%'); // rotate 180°

$flipped = $image->resize(-125, 500); // resize & flip horizontal

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

$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); // Red
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // Semi-transparent blue

Метод ImageColor::hex() позволяет задать цвет, используя шестнадцатеричный формат, аналогично CSS. Он поддерживает форматы #rgb, #rrggbb, #rgba и #rrggbbaa:

$color = ImageColor::hex("#F00"); // Red
$transparentGreen = ImageColor::hex("#00FF0080"); // Semi-transparent green

Цвета могут использоваться и в других методах, таких как 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

Создает новое истинно цветное изображение заданных размеров. По умолчанию используется черный цвет.

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

Возвращает массив поддерживаемых типов изображений (константы ImageType::XXX).

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

Позволяет использовать два различных режима рисования в трехцветных изображениях. В режиме наложения компонент альфа-канала цвета, используемый во всех функциях рисования, таких как setPixel(), определяет, в какой степени базовый цвет должен просвечивать. В результате в этот момент существующий цвет автоматически смешивается с цветом рисунка, и результат сохраняется в изображении. В результате пиксель становится непрозрачным. В режиме без смешивания цвет мультфильма копируется дословно с информацией альфа-канала и заменяется на целевой пиксель. Режим наложения недоступен при рисовании на изображениях палитры. (подробнее)

antialias(bool $on): void

Активация рисования сглаженных линий и многоугольников. Не поддерживает альфа-каналы. Работает только с трехцветными изображениями.

Использование сглаженного примитива с прозрачным цветом фона может привести к неожиданным результатам. Метод смешивания использует цвет фона как любой другой цвет. (подробнее)

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

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