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

Класът 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%'); // обръщане по вертикала

$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); // 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

Прилага конволюционна матрица към изображението, като използва посочените коефициент и отместване. (повече подробности)

Изисква Пълен GD разширение, така че може да не работи навсякъде.

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

Копира част от $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

Напишете текста на картинката. (повече)

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

Прилагане на гама корекция на изображението спрямо входната и изходната гама. (повече подробности)

getClip(): array

Връща текущото изрязване, т.е. областта, извън която няма да бъдат изчертавани пиксели. (повече подробности)

getHeight(): int

Връща височината на изображението.

getImageResource(): resource|GdImage

Връща ресурса източник.

getWidth(): int

Връща ширината на изображението.

interlace(int $interlace=null): int

Включва или изключва режима с преливане. Ако е зададен режим с преплитане и изображението е записано във формат JPEG, изображението ще бъде записано като прогресивен JPEG. (повече подробности)

isTrueColor(): bool

Определете дали изображението е истинскоцветно. (прочети повече)

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 в градуси. Центърът на завъртане е центърът на изображението и завъртяното изображение може да има различен размер от оригиналното изображение. (повече подробности)

Изисква Пълен GD разширение, така че може да не работи навсякъде.

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

Увеличава рязкостта на изображението.

Изисква Пълен GD разширение, така че може да не работи навсякъде.

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

Записва изображението в низ.

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

Преобразува истинско цветно изображение в палитра. (прочети повече)

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

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