Работа с изображениями
Класс Nette\Utils\Image позволяет легко манипулировать изображениями, например, изменять размер, обрезать, повышать резкость, рисовать или соединять несколько изображений.
PHP имеет обширный набор функций для работы с изображениями. Но их API не очень удобен. Это был бы не Nette Framework, если бы не придумали сексуальный API.
Установка:
composer require nette/utils
Во всех примерах предполагается, что псевдоним уже создан:
use Nette\Utils\Image;
Создание изображения
Создайте новое истинно цветное изображение, например, размером 100×200:
$image = Image::fromBlank(100, 200);
По желанию можно указать цвет фона (по умолчанию черный):
$image = Image::fromBlank(100, 200, Image::rgb(125, 0, 0));
Или загрузите изображение из файла:
$image = Image::fromFile('nette.jpg');
Нужно ли определять формат изображения при загрузке? Метод возвращает его во втором параметре:
$image = Image::fromFile('nette.jpg', $type);
// $type bude Image::JPEG, Image::PNG, Image::GIF, Image::WEBP nebo Image::BMP
Обнаружение без загрузки осуществляется по адресу
Image::detectTypeFromFile().
Сохранение изображения
Изображение можно сохранить в файл:
$image->save('resampled.jpg');
Мы можем задать качество сжатия в диапазоне 0…100 для JPEG (по умолчанию 85) и WEBP (по умолчанию 80) и 0…9 для PNG (по умолчанию 9):
$image->save('resampled.jpg', 80); // JPEG, 80% качества
Если формат не очевиден из расширения файла, он может быть указан
одной из констант Image::JPEG, Image::PNG, Image::GIF,
Image::WEBP и Image::BMP:
$image->save('resampled.tmp', null, Image::JPEG);
Изображение может быть записано не на диск, а в переменную:
$data = $image->toString(Image::JPEG, 80); // JPEG, 80% качества
или отправляется непосредственно в браузер с соответствующим
HTTP-заголовком Content-Type:
// отправляет заголовок Content-Type: image/png
$image->send(Image::PNG);
Изменить размер
Частой операцией является изменение размера изображения.
Фактические размеры возвращаются методами 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(), более подробную информацию см. в документации к ней.
Рисование и редактирование
Вы можете рисовать, можете писать, но не рвите страницы.
Все функции PHP для работы с изображениями, такие как imagefilledellipse, доступны вам, но в объектно-ориентированном обличье:
$image->filledEllipse($cx, $cy, $width, $height, Image::rgb(255, 0, 0, 63));
См. раздел Обзор методов.
Объединение нескольких изображений
Вы можете легко вставить другое изображение в фотографию:
$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, Image::rgb(52, 132, 210));
// координаты могут быть снова заданы в процентах
$blank->place($logo, '80%', '80%'); // вставьте в правый нижний угол
Альфаканал соблюдается во время вставки, и мы можем влиять на прозрачность вставленного изображения (мы создаем водяной знак):
$blank->place($image, '80%', '80%', 25); // прозрачность составляет 25%
Этот API – настоящее удовольствие от использования!
Обзор методов
static fromBlank(int $width, int $height, array $color=null): Image
Создает новое истинно цветное изображение заданных размеров. По умолчанию используется черный цвет.
static fromFile(string $file, int &$detectedFormat=null): Image
Считывает изображение из файла и возвращает его тип в формате
$detectedFormat. Поддерживаемые типы: Image::JPEG, Image::PNG,
Image::GIF, Image::WEBP и Image::BMP.
static fromString(string $s, int &$detectedFormat=null): Image
Считывает изображение из строки и возвращает его тип в формате
$detectedFormat. Поддерживаемые типы: Image::JPEG, Image::PNG,
Image::GIF, Image::WEBP и Image::BMP.
static rgb(int $red, int $green, int $blue, int $transparency=0): array
Создает цвет, который может быть использован в других методах, таких
как ellipse(), fill() и т.д.
static typeToExtension(int $type): string
Возвращает расширение файла для заданной константы Image::XXX.
static typeToMimeType(int $type): string
Возвращает тип mime для заданной константы Image::XXX.
static extensionToType(string $extension): int
Возвращает тип изображения в виде константы Image::XXX в
соответствии с расширением файла.
static detectTypeFromFile(string $file, int &$width=null, int &$height=null): ?int
Возвращает тип изображения в виде константы Image::XXX, а также его
размеры в параметрах $width и $height.
static detectTypeFromString(string $s, int &$width=null, int &$height=null): ?int
Возвращает тип изображения из строки в виде константы Image::XXX и
его размеры в параметрах $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 $x, int $y, int $w, int $h, int $start, int $end, int $color): void
Рисует дугу окружности с центром в заданных координатах. (подробнее)
char(int $font, int $x, int $y, string $char, int $color): void
Нарисует первый символ $char в изображении с левым верхним углом
$x, $y (левый верхний угол равен 0, 0) цветом $color. (подробнее)
charUp(int $font, int $x, int $y, string $char, int $color): void
Рисует символ $char вертикально по указанной координате в
заданном изображении. (подробнее)
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, int $color=-1): Image
Автоматическое кадрирование изображения в соответствии с заданным
$mode. (подробнее)
ellipse(int $cx, int $cy, int $w, int $h, int $color): void
Рисует эллипс с центром в заданных координатах. (подробнее)
fill(int $x, int $y, int $color): void
Заполняет область, начинающуюся в заданной координате (слева вверху
0, 0), заданным $color. (подробнее)
filledArc(int $cx, int $cy, int $w, int $h, int $s, int $e, int $color, int $style): void
Рисует неполную дугу с центром в заданных координатах. (подробнее)
filledEllipse(int $cx, int $cy, int $w, int $h, int $color): void
Рисует эллипс с центром в заданных координатах. (подробнее)
filledPolygon(array $points, int $numPoints, int $color): void
Создает заполненный многоугольник на изображении. (подробнее)
filledRectangle(int $x1, int $y1, int $x2, int $y2, int $color): void
Создает прямоугольник, заполненный $color на изображении,
начиная с точки 1 и заканчивая точкой 2. Точка 0, 0 – левый верхний угол
изображения. (подробнее)
fillToBorder(int $x, int $y, int $border, int $color): void
Создает заливку, цвет границы которой определяется $border.
Начальная точка заливки – $x, $y (левый верхний угол – 0, 0),
а область заливается цветом $color. (подробнее)
filter(int $filtertype, int …$args): void
Применяет заданный фильтр $filtertype к изображению. (подробнее)
flip(int $mode): void
Инвертирует изображение по заданному адресу $mode. (подробнее)
ftText(int $size, int $angle, int $x, int $y, int $col, string $fontFile, string $text, array $extrainfo=null): array
Пишите текст на изображении, используя шрифты FreeType 2. (подробнее)
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, int $color): void
Проводит линию между двумя заданными точками. (подробнее)
openPolygon(array $points, int $numPoints, int $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, int $numPoints, int $color): void
Создает многоугольник на изображении. (подробнее)
rectangle(int $x1, int $y1, int $x2, int $y2, int $col): 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) и 0…9 для PNG (по умолчанию 9). Если тип не очевиден из
расширения файла, вы можете указать его с помощью одной из констант
Image::JPEG, Image::PNG, Image::GIF, Image::WEBP и
Image::BMP.
saveAlpha(bool $saveflag): void
Устанавливает флаг сохранения полной информации альфа-канала (в отличие от монохромной прозрачности) при сохранении изображений PNG.
Для сохранения альфа-канала альфа-квантование должно быть отключено
(alphaBlending(false)). (подробнее)
scale(int $newWidth, int $newHeight=-1, int $mode=IMG_BILINEAR_FIXED): Image
Масштабирование изображения с использованием заданного алгоритма интерполяции. (подробнее)
send(int $type=Image::JPEG, int $quality=null): void
Выводит изображение в браузер.
Качество сжатия находится в диапазоне 0…100 для JPEG (по умолчанию 85) и WEBP
(по умолчанию 80) и 0…9 для PNG (по умолчанию 9). Тип является одной из
констант Image::JPEG, Image::PNG, Image::GIF, Image::WEBP и
Image::BMP.
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, int $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, поэтому может работать не везде.
string(int $font, int $x, int $y, string $str, int $col): void
Выводит строку по заданным координатам. (подробнее)
stringUp(int $font, int $x, int $y, string $s, int $col): void
Выводит строку по вертикали в заданных координатах. (подробнее)
toString(int $type=Image::JPEG, int $quality=null): string
Сохраняет изображение в строке.
Качество сжатия находится в диапазоне 0…100 для JPEG (по умолчанию 85) и WEBP
(по умолчанию 80) и 0…9 для PNG (по умолчанию 9). Тип – это одна из констант
Image::JPEG, Image::PNG, Image::GIF, Image::WEBP и
Image::BMP.
trueColorToPalette(bool $dither, int $ncolors): void
Преобразует truecolor изображение в палитру. (подробнее)
ttfText(int $size, int $angle, int $x, int $y, int $color, string $fontfile, string $text): array
Печатает заданный текст в изображение с использованием шрифтов TrueType. (подробнее)