Работа с изображениями
Класс 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. Левый край
может быть отрицательным, если текст начинается с левого выступающего
элемента (kerning).
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
Копирует часть $src на изображение, начиная с координат
$srcX, $srcY с шириной $srcW и высотой $srcH.
Определенная часть будет скопирована на координаты $dstX и
$dstY. (подробнее)
copyMergeGray(Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void
Копирует часть $src на изображение, начиная с координат
$srcX, $srcY с шириной $srcW и высотой $srcH.
Определенная часть будет скопирована на координаты $dstX и
$dstY.
Эта функция идентична 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
Записывает текст на изображение, используя шрифты FreeType. (подробнее)
gammaCorrect(float $inputgamma, float $outputgamma): void
Применяет гамма-коррекцию к изображению относительно входной и выходной гаммы. (подробнее)
getClip(): array
Возвращает текущую область обрезки, т.е. область, за пределами которой пиксели не будут нарисованы. (подробнее)
getHeight(): int
Возвращает высоту изображения.
getImageResource(): resource|GdImage
Возвращает исходный ресурс изображения GD.
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
Преобразует изображение на основе палитры в полноцветное изображение (truecolor). (подробнее)
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
Сохраняет изображение в строку.
Качество сжатия находится в диапазоне 0..100 для JPEG (по умолчанию 85), WEBP (по умолчанию 80) и AVIF (по умолчанию 30) и 0..9 для PNG (по умолчанию 9).
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
Выводит заданный текст на изображение, используя шрифты TrueType. (подробнее)