Práce s obrázky

Třída Nette\Utils\Image zjednodušuje manipulaci s obrázky, jako je změna velikosti, oříznutí, doostření, kreslení nebo spojování více obrázků.

PHP disponuje rozsáhlou sadou funkcí pro manipulaci s obrázky. Ale jejich API není moc pohodlné. To by nebyl Nette Framework, aby nepřišel se sexy API.

Instalace:

composer require nette/utils

Všechny příklady předpokládají vytvořený alias:

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

Vytvoření obrázku

Vytvoříme nový true color obrázek, například s rozměry 100×200:

$image = Image::fromBlank(100, 200);

Volitelně lze určit barvu pozadí (výchozí je černá):

$image = Image::fromBlank(100, 200, ImageColor::rgb(125, 0, 0));

Nebo obrázek načteme ze souboru:

$image = Image::fromFile('nette.jpg');

Uložení obrázku

Obrázek lze uložit do souboru:

$image->save('resampled.jpg');

Můžeme určit kvalitu komprese v rozsahu 0..100 pro JPEG (výchozí 85), WEBP (výchozí 80) a AVIF (výchozí 30) a 0..9 pro PNG (výchozí 9):

$image->save('resampled.jpg', 80); // JPEG, kvalita 80%

Pokud z přípony souboru není zřejmý formát, lze ho určit konstantou:

$image->save('resampled.tmp', null, ImageType::JPEG);

Obrázek lze místo na disk zapsat do proměnné:

$data = $image->toString(ImageType::JPEG, 80); // JPEG, kvalita 80%

nebo poslat přímo do prohlížeče s příslušnou HTTP hlavičkou Content-Type:

// odešle hlavičku Content-Type: image/png
$image->send(ImageType::PNG);

Formáty

Podporované formáty jsou JPEG, PNG, GIF, WebP, AVIF a BMP, nicméně musí je podporovat i vaše verze PHP, což ověříte funkcí isTypeSupported(). Animace podporované nejsou.

Formát představují konstanty ImageType::JPEG, ImageType::PNG, ImageType::GIF, ImageType::WEBP, ImageType::AVIF a ImageType::BMP.

$supported = Image::isTypeSupported(ImageType::JPEG);

Potřebujete při načtení detekovat formát obrázku? Metoda ho vrátí v druhém parametru:

$image = Image::fromFile('nette.jpg', $type);

Samotnou detekci bez načtení obrázku provádí Image::detectTypeFromFile().

Změna velikosti

Častou operací je změna rozměrů obrázku. Akutální rozměry vrací metody getWidth() a getHeight().

Ke změně slouží metoda resize(). Příklad proporcionální změny velikosti tak, aby nepřesáhl rozměry 500×300 pixelů (buď bude šířka přesně 500 px nebo výška bude přesně 300 px, jeden z rozměrů se dopočítá tak, aby byl zachován poměr stran):

$image->resize(500, 300);

Je možné specifikovat jen jeden rozměr a druhý se dopočítá:

$image->resize(500, null); // šířka 500px, výška se dopočítá

$image->resize(null, 300); // šířka se dopočítá, výška 300px

Kterýkoliv rozměr je možné uvést i v procentech:

$image->resize('75%', 300); // 75 % × 300px

Chování resize lze ovlivnit následujícími příznaky. Všechny kromě Image::Stretch zachovávají poměr stran.

Příznak	Popis
`Image::OrSmaller` (výchozí)	výsledné rozměry budou menší nebo rovny požadovaným rozměrům
`Image::OrBigger`	vyplní (a případně přesáhne v jednom rozměru) cílovou plochu
`Image::Cover`	vyplní cílovou plochu a ořízne to, co přesáhne
`Image::ShrinkOnly`	pouze zmenšování (zabrání roztažení malého obrázku)
`Image::Stretch`	nezachovávat poměr stran

Příznaky se uvádějí jako třetí argument funkce:

$image->resize(500, 300, Image::OrBigger);

Příznaky lze kombinovat:

$image->resize(500, 300, Image::ShrinkOnly | Image::Stretch);

Obrázky lze vertikálně nebo horizontálně překlopit tak, že jeden z rozměrů (případně oba) uvedeme jako záporné číslo:

$flipped = $image->resize(null, '-100%'); // flip vertical

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

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

Po zmenšení obrázku je možné vylepšit jeho vzhled jemným doostřením:

$image->sharpen();

Oříznutí

Pro oříznutí slouží metoda crop():

$image->crop($left, $top, $width, $height);

Podobně jako u resize() mohou být všechny hodnoty uvedeny v procentech. Procenta u $left a $top se počítají ze zbylého místa, podobně jako u CSS vlastnosti background-position:

$image->crop('100%', '50%', '80%', '80%');

Obrázek lze také oříznout automaticky, například oříznutí černých okrajů:

$image->cropAuto(IMG_CROP_BLACK);

Metoda cropAuto() je objektovou náhradou funkce imagecropauto(), v její dokumentaci najdete další informace.

Barvy

Metoda ImageColor::rgb() vám umožňuje definovat barvu pomocí hodnot červené, zelené a modré (RGB). Volitelně můžete také specifikovat hodnotu průhlednosti v rozmezí 0 (naprosto průhledné) až 1 (zcela neprůhledné), tedy stejně jako v CSS.

$color = ImageColor::rgb(255, 0, 0); // Červená
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // Poloprůhledná modrá

Metoda ImageColor::hex() umožňuje definovat barvu pomocí hexadecimálního formátu, podobně jako v CSS. Podporuje formáty #rgb, #rrggbb, #rgba a #rrggbbaa:

$color = ImageColor::hex("#F00"); // Červená
$transparentGreen = ImageColor::hex("#00FF0080"); // Poloprůhledná zelená

Barvy lze použít v dalších metodách, jako třeba ellipse(), fill() atd.

Kreslení a úpravy

Můžeš kreslit, můžeš psát, ale listy netrhat. Jsou vám k dispozici všechny funkce PHP pro práci s obrázky, viz Přehled metod, ale v objektovém hávu:

$image->filledEllipse($centerX, $centerY, $width, $height, ImageColor::rgb(255, 0, 0));

Protože PHP funkce pro kreslení obdelníků jsou nepraktické kvůli určení souřadnic, nabízí třída Image jejich náhrady v podobě funkcí rectangleWH() a filledRectangleWH().

Spojení více obrázků

Do obrázku lze snadno vložit jiný obrázek:

$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, ImageColor::rgb(52, 132, 210));

// souřadnice lze uvést opět v procentech
$blank->place($logo, '80%', '80%'); // vložíme poblíž pravého dolního rohu

Při vkládání se respektuje alphakanál, navíc můžeme ovlivnit průhlednost vkládaného obrázku (vytvoříme tzv. watermark):

$blank->place($image, '80%', '80%', 25); // průhlednost je 25 %

Takové API je skutečně radost používat!

Přehled metod

static fromBlank (int $width, int $height, ?ImageColor $color=null): Image

Vytvoří nový true color obrázek daných rozměrů. Výchozí barva je černá.

static fromFile (string $file, int &$detectedFormat=null): Image

Načte obrázek ze souboru a vrací jeho typ v $detectedFormat.

static fromString (string $s, int &$detectedFormat=null): Image

Načte obrázek z řetezce a vrací jeho typ v $detectedFormat.

static rgb (int $red, int $green, int $blue, int $transparency=0): array

Tuto funkci nahradila třída ImageColor, viz barvy.

static typeToExtension (int $type): string

Vrátí příponu souboru pro daný typ.

static typeToMimeType (int $type): string

Vrátí mime type pro daný typ.

static extensionToType (string $extension): int

Vrátí typ obrázku podle přípony souboru.

static detectTypeFromFile (string $file, int &$width=null, int &$height=null): ?int

Vrátí typ obrázku a v parametrech $width a $height také jeho rozměry.

static detectTypeFromString (string $s, int &$width=null, int &$height=null): ?int

Vrátí typ obrázku z řetězce a v parametrech $width a $height také jeho rozměry.

static isTypeSupported (int $type): bool

Zjišťuje, zda je podporovaný daný typ obrázku.

static getSupportedTypes(): array

Vrací pole podporovaných typů obrázku.

static calculateTextBox (string $text, string $fontFile, float $size, float $angle=0, array $options=[]): array

Spočítá rozměry obdélníku, který obepne text v určitém písmu a velikosti. Vrací asociativní pole obsahující klíče left, top, width, height. Levý okraj může být i záporný, pokud text začíná levým podřezáváním.

affine (array $affine, ?array $clip=null): Image

Vraťte obrázek obsahující afinně transformovaný obraz src pomocí volitelné oblasti oříznutí. (více).

affineMatrixConcat (array $m1, array $m2): array

Vrací zřetězení dvou afinních transformačních matic, což je užitečné, pokud by se na stejný obrázek mělo najednou použít více transformací. (více)

affineMatrixGet (int $type, ?mixed $options=null): array

Vrátí maticovou transformační matici. (více)

alphaBlending (bool $on): void

Umožňuje dva různé režimy kreslení v obrázcích truecolor. V režimu prolnutí určuje součást alfa kanálu barvy použité ve všech funkcích kreslení, jako je například setPixel(), do jaké míry by mělo být umožněno prosvítání základní barvy. Výsledkem je, že se v tomto bodě automaticky smíchá existující barva s barvou kreslenou a výsledek uloží do obrázku. Výsledný pixel je neprůhledný. V režimu bez prolnutí se kreslená barva zkopíruje doslova s informacemi o alfa kanálu a nahradí cílový pixel. Režim prolnutí není k dispozici při kreslení na paletových obrázcích. (více)

antialias (bool $on): void

Aktivujte kreslení vyhlazených čar a polygonů. Nepodporuje alfa kanály. Funguje pouze u obrazů truecolor.

Použití antialiased primitiv s průhlednou barvou pozadí může skončit s některými neočekávanými výsledky. Metoda prolnutí používá barvu pozadí jako všechny ostatní barvy. (více)

arc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color): void

Nakreslí oblouk kruhu se středem v daných souřadnicích. (více)

colorAllocate (int $red, int $green, int $blue): int

Vrací identifikátor barvy představující barvu složenou z daných komponent RGB. Musí být volána pro vytvoření každé barvy, která má být použita v obrázku. (více)

colorAllocateAlpha (int $red, int $green, int $blue, int $alpha): int

Chová se stejně jako colorAllocate() s přidáním parametru průhlednosti $alpha. (více)

colorAt (int $x, int $y): int

Vrátí index barvy pixelu na určeném místě v obrázku. Pokud je obrazem truecolor, vrátí tato funkce hodnotu RGB tohoto pixelu jako celé číslo. Použijte bitshifting a bitmasking pro přístup k samostatnýchm hodnotám červené, zelené a modré složky: (více)

colorClosest (int $red, int $green, int $blue): int

Vrátí index barvy v paletě obrazu, který je „nejblíže“ zadané hodnotě RGB. „Vzdálenost“ mezi požadovanou barvou a každou barvou v paletě se vypočítá, jako by hodnoty RGB představovaly body v trojrozměrném prostoru. (více)

colorClosestAlpha (int $red, int $green, int $blue, int $alpha): int

Vrátí index barvy v paletě obrazu, který je „nejblíže“ zadané hodnotě RGB a úrovni $alpha. (více)

colorClosestHWB (int $red, int $green, int $blue): int

Získejte index barvy, která má odstín, bílou a černou barvu nejblíže dané barvě. (více)

colorDeallocate (int $color): void

De-alokuje barvu dříve přidělenou pomocí colorAllocate() nebo colorAllocateAlpha(). (více)

colorExact (int $red, int $green, int $blue): int

Vrátí index zadané barvy v paletě obrázku. (více)

colorExactAlpha (int $red, int $green, int $blue, int $alpha): int

Vrátí index zadané barvy + alfa v paletě obrázku. (více)

colorMatch (Image $image2): void

Přizpůsobí barvy palety druhému obrazu. (více)

colorResolve (int $red, int $green, int $blue): int

Vrátí index barvy pro požadovanou barvu, buď přesnou barvu, nebo nejbližší možnou alternativu. (více)

colorResolveAlpha (int $red, int $green, int $blue, int $alpha): int

Vrátí index barev pro požadovanou barvu, buď přesnou barvu, nebo nejbližší možnou alternativu. (více)

colorSet (int $index, int $red, int $green, int $blue): void

Nastaví zadaný index v paletě na zadanou barvu. (více)

colorsForIndex (int $index): array

Získá barvu určeného indexu. (více)

colorsTotal(): int

Vrátí počet barev v obrazové paletě. (více)

colorTransparent (?int $color=null): int

Získá nebo nastaví průhlednou barvu v obrázku. (více)

convolution (array $matrix, float $div, float $offset): void

Aplikuje na obrázek konvoluční matici, používá daný koeficient a offset. (více)

Vyžaduje přítomnost Bundled GD extension, nemusí tedy fungovat všude.

copy (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH): void

Zkopíruje část $src na obrázek začínající na souřadnicích $srcX, $srcY se šířkou $srcW a výškou $srcH. Definovaná část bude zkopírována na souřadnice $dstX a $dstY. (více)

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

Zkopíruje část $src na obrázek začínající na souřadnicích $srcX, $srcY se šířkou $srcW a výškou $srcH. Definovaná část bude zkopírována na souřadnice $dstX a $dstY.

Tato funkce je identická s copyMerge() s tou výjimkou, že při sloučení zachovává odstín zdroje převedením cílových pixelů na šedou stupnici před operací kopírování. (více)

copyResampled (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

Zkopíruje obdélníkovou část jednoho obrázku na druhý obrázek, hladce interpoluje hodnoty obrazových bodů, takže zejména zmenšení velikosti obrázku si stále zachovává velkou jasnost.

Jinými slovy, copyResampled() vezme obdélníkovou oblast ze $src šířky $srcW a výšky $srcH v poloze ($srcX, $srcY) a umístí ji do obdélníkové oblasti obrazu šířky $dstW a výška $dstH v poloze ($dstX, $dstY).

Pokud se zdrojové a cílové souřadnice, šířka a výška liší, provede se odpovídající roztažení nebo zmenšení fragmentu obrazu. Souřadnice se vztahují k levému hornímu rohu. Tuto funkci lze použít ke kopírování oblastí ve stejném obrázku, ale pokud se oblasti překrývají, výsledky nebudou předvídatelné. (více)

copyResized (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

Zkopíruje obdélníkovou část jednoho obrázku na jiný obrázek. Jinými slovy, copyResized() získá obdélníkovou oblast ze $src šířky $srcW a výšky $srcH v poloze ($srcX, $srcY) a umístí ji do obdélníkové oblasti obrazu šířky $dstW ] a výška $dstH v poloze ($dstX, $dstY).

crop (int|string $left, int|string $top, int|string $width, int|string $height): Image

Ořízne obrázek do dané obdélníkové oblasti. Rozměry je možné zadávat jako integery v pixelech nebo řetězce v procentech (například '50%').

cropAuto (int $mode=-1, float $threshold=.5, ?ImageColor $color=null): Image

Automaticky ořízne obrázek podle daného $mode. (více)

ellipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

Nakreslí elipsu se středem na zadaných souřadnicích. (více)

fill (int $x, int $y, ImageColor $color): void

Výplní oblast počínaje danou souřadnicí (vlevo nahoře je 0, 0) s daným $color. (více)

filledArc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color, int $style): void

Nakreslí částečný oblouk se středem na zadaných souřadnicích. (více)

filledEllipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

Nakreslí elipsu se středem na zadaných souřadnicích. (více)

filledPolygon (array $points, ImageColor $color): void

Vytvoří v obraze vyplněný mnohoúhelník. (více)

filledRectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Vytvoří obdélník vyplněný $color v obrázku počínaje bodem $x1 & $y1 a končící bodem $x2 & $y2. Bod 0, 0 je levý horní roh obrázku. (více)

filledRectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

Vytvoří obdélník vyplněný $color v obrázku počínaje bodem $left & $top o šířce $width a výšce $height. Bod 0, 0 je levý horní roh obrázku.

fillToBorder (int $x, int $y, int $border, ImageColor $color): void

Vykreslí výplň, jejíž barva okraje je definována pomocí $border. Výchozím bodem výplně je $x, $y (vlevo nahoře je 0, 0) a oblast je vyplněna barvou $color. (více)

filter (int $filtertype, int …$args): void

Použije daný filtr $filtertype na obrázek. (více)

flip (int $mode): void

Převrátí obrázek pomocí daného $mode. (více)

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

Napište text do obrázku. (více)

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

Aplikuje gama korekci na obraz vzhledem k vstupnímu a výstupnímu gamma. (více)

getClip(): array

Vrátí aktuální ořez, tj. oblast, za kterou nebudou nakresleny žádné pixely. (více)

getHeight(): int

Vrátí výšku obrázku.

getImageResource(): resource|GdImage

Vrací původní resource.

getWidth(): int

Vrátí šířku obrázku.

interlace (?int $interlace=null): int

Zapíná nebo vypíná prokládaný režim. Pokud je prokládaný režim nastaven a obrázek je uložen jako JPEG, bude uložen jako progresivní JPEG. (více)

isTrueColor(): bool

Zjistí, zda je obraz truecolor. (více)

layerEffect (int $effect): void

Nastavte příznak prolnutí alfa tak, aby používal efekty vrstvení. (více)

line (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Nakreslí čáru mezi dvěma danými body. (více)

openPolygon (array $points, ImageColor $color): void

Nakreslí na obrázek otevřený mnohoúhelník. Na rozdíl od polygon() není mezi posledním a prvním bodem nakreslena žádná čára. (více)

paletteCopy (Image $source): void

Zkopíruje paletu ze $source do obrázku. (více)

paletteToTrueColor(): void

Převede obrázek založený na paletě na plnobarevný obrázek. (více)

place (Image $image, int|string $left=0, int|string $top=0, int $opacity=100): Image

Zkopíruje $image do obrázku na souřadnice $left a $top. Souřadnice je možné zadávat jako integery v pixelech nebo řetězce v procentech (například '50%').

polygon (array $points, ImageColor $color): void

Vytvoří v obrazu mnohoúhelník. (více)

rectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

Vytvoří obdélník na zadaných souřadnicích. (více)

rectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

Vytvoří obdélník na zadaných souřadnicích.

resize (int|string $width, int|string $height, int $flags=Image::OrSmaller): Image

Změní velikost obrázku, více informací. Rozměry je možné zadávat jako integery v pixelech nebo řetězce v procentech (například '50%').

resolution (?int $resX=null, ?int $resY=null): mixed

Nastaví nebo vrátí rozlišení obrázku v DPI (tečky na palec). Pokud není zadán žádný z volitelných parametrů, je aktuální rozlišení vráceno jako indexované pole. Pokud je zadáno pouze $resX, horizontální a vertikální rozlišení se nastaví na tuto hodnotu. Pokud jsou zadány oba volitelné parametry, horizontální a vertikální rozlišení se nastaví na tyto hodnoty.

Rozlišení se používá pouze jako meta informace, když jsou obrázky čteny a zapisovány do formátů podporujících tento druh informací (aktuálně PNG a JPEG). Nemá to vliv na žádné operace kreslení. Výchozí rozlišení nových snímků je 96 DPI. (více)

rotate (float $angle, int $backgroundColor): Image

Otočí obrázek pomocí zadaného $angle ve stupních. Střed otáčení je střed obrazu a rotovaný obraz může mít jiné rozměry než původní obraz. (více)

Vyžaduje přítomnost Bundled GD extension, nemusí tedy fungovat všude.

save (string $file, ?int $quality=null, ?int $type=null): void

Uloží obrázek do souboru.

Kvalita komprese je v rozsahu 0..100 pro JPEG (výchozí 85), WEBP (výchozí 80) a AVIF (výchozí 30) a 0..9 pro PNG (výchozí 9). Pokud typ není zřejmý z přípony souboru, můžete jej zadat pomocí jedné z konstant ImageType.

saveAlpha (bool $saveflag): void

Nastavuje příznak, zda při ukládání obrazů PNG zachovat úplné informace o alfa kanálu (na rozdíl od jednobarevné průhlednosti).

Alfablending musí být deaktivován (alphaBlending(false)), aby si alfa kanál udržel na prvním místě. (více)

scale (int $newWidth, int $newHeight=-1, int $mode=IMG_BILINEAR_FIXED): Image

Měřítko obrázku pomocí daného interpolačního algoritmu. (více)

send (int $type=ImageType::JPEG, ?int $quality=null): void

Vypíše obrázek do prohlížeče.

Kvalita komprese je v rozsahu 0..100 pro JPEG (výchozí 85), WEBP (výchozí 80) a AVIF (výchozí 30) a 0..9 pro PNG (výchozí 9).

setBrush (Image $brush): void

Nastavuje obraz štětce, který se použije ve všech funkcích kreslení čar (například line() a polygon()) při kreslení se speciálními barvami IMG_COLOR_BRUSHED nebo IMG_COLOR_STYLEDBRUSHED. (více)

setClip (int $x1, int $y1, int $x2, int $y2): void

Nastaví aktuální ořez, tj. oblast, za kterou nebudou nakresleny žádné pixely. (více)

setInterpolation (int $method=IMG_BILINEAR_FIXED): void

Nastaví metodu interpolace, která ovlivní metody rotate() a affine(). (více)

setPixel (int $x, int $y, ImageColor $color): void

Nakreslí pixel na zadané souřadnici. (více)

setStyle (array $style): void

Nastavuje styl, který mají používat všechny funkce kreslení čar (například line() a polygon()) při kreslení speciální barvou IMG_COLOR_STYLED nebo linií obrázků s barvou IMG_COLOR_STYLEDBRUSHED. (více)

setThickness (int $thickness): void

Nastavuje tloušťku čar při kreslení obdélníků, mnohoúhelníků, oblouků atd. Na $thickness pixelů. (více)

setTile (Image $tile): void

Nastaví obrázek dlaždice, který bude použit ve všech funkcích vyplňování regionů (například fill() a filledPolygon()), když se vyplní speciální barvou IMG_COLOR_TILED.

Dlaždice je obrázek používaný k vyplnění oblasti opakovaným vzorem. Jakýkoli obraz lze použít jako dlaždici a nastavením průhledného barevného indexu obrazu dlaždice pomocí colorTransparent() lze vytvořit dlaždici, kde budou prosvítat určité části podkladové oblasti. (více)

sharpen(): Image

Doostří obrázek.

Vyžaduje přítomnost Bundled GD extension, nemusí tedy fungovat všude.

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

Uloží obrázek do řetezce.

Kvalita komprese je v rozsahu 0..100 pro JPEG (výchozí 85), WEBP (výchozí 80) a AVIF (výchozí 30) a 0..9 pro PNG (výchozí 9).

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

Převede obraz truecolor na paletový. (více)

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

Vypíše daný text do obrázku. (více)