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;

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, Image::rgb(125, 0, 0));

Nebo obrázek načteme ze souboru:

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

Podporované formáty jsou JPEG, PNG, GIF, WebP, AVIF a BMP, nicméně musí je podporovat i vaše verze PHP (ověříte ve výpisu phpinfo() v sekci GD). Animace podporované nejsou.

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);
// $type bude Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF nebo Image::BMP

Samotnou detekci bez načtení obrázku provádí Image::detectTypeFromFile() (od nette/utils 3.2).

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 jednou z konstant Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF a Image::BMP:

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

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

$data = $image->toString(Image::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(Image::PNG);

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:

Příznak Popis
Image::FIT (výchozí) výsledné rozměry budou menší nebo rovny požadovaným rozměrům
Image::FILL vyplní (a případně přesáhne v jednom rozměru) cílovou plochu
Image::EXACT vyplní cílovou plochu a ořízne to, co přesáhne
Image::SHRINK_ONLY 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::STRETCH);

Příznaky lze kombinovat:

$image->resize(500, 300, Image::SHRINK_ONLY | 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.

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, jako například imagefilledellipse, ale v objektovém hávu:

$image->filledEllipse($cx, $cy, $width, $height, Image::rgb(255, 0, 0, 63));

Viz Přehled metod.

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, Image::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, ?array $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. Podporované typy jsou Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF a Image::BMP.

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

Načte obrázek z řetezce a vrací jeho typ v $detectedFormat. Podporované typy jsou Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF a Image::BMP.

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

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

static typeToExtension (int $type)string

Vrátí příponu souboru pro danou konstantu Image::XXX.

static typeToMimeType (int $type)string

Vrátí mime type pro danou konstantu Image::XXX.

static extensionToType (string $extension)int

Vrátí typ obrázku jako konstantu Image::XXX podle přípony souboru.

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

Vrátí typ obrázku jako konstantu Image::XXX 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 jako konstantu Image::XXX a v parametrech $width a $height také jeho rozměry.

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 $x, int $y, int $w, int $h, int $start, int $end, int $color)void

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

char (int $font, int $x, int $y, string $char, int $color)void

Nakreslí první znak $char do obrázku s jeho levým horním rohem na $x, $y (vlevo nahoře je 0, 0) s barvou $color. (více)

charUp (int $font, int $x, int $y, string $char, int $color)void

Nakreslí znak $char svisle na určenou souřadnici na daném obrázku. (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

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)

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).

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)

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, int $color=-1)Image

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

ellipse (int $cx, int $cy, int $w, int $h, int $color)void

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

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

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

filledArc (int $cx, int $cy, int $w, int $h, int $s, int $e, int $color, int $style)void

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

filledEllipse (int $cx, int $cy, int $w, int $h, int $color)void

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

filledPolygon (array $points, int $numPoints, int $color)void

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

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

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

fillToBorder (int $x, int $y, int $border, int $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 (int $size, int $angle, int $x, int $y, int $col, string $fontFile, string $text, ?array $extrainfo=null)array

Napište text do obrázku pomocí písem pomocí FreeType 2. (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, int $color)void

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

openPolygon (array $points, int $numPoints, int $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, int $numPoints, int $color)void

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

rectangle (int $x1, int $y1, int $x2, int $y2, int $col)void

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

resize (int|string $width, int|string $height, int $flags=Image::FIT)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 Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF a Image::BMP.

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=Image::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). Typ je jednou z konstant Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF a Image::BMP.

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, int $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.

string (int $font, int $x, int $y, string $str, int $col)void

Vypíše řetězec na zadané souřadnice. (více)

stringUp (int $font, int $x, int $y, string $s, int $col)void

Vypíše řetězec svisle na dané souřadnice. (více)

toString (int $type=Image::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). Typ je jednou z konstant Image::JPEG, Image::PNG, Image::GIF, Image::WEBP, Image::AVIF a Image::BMP.

trueColorToPalette (bool $dither, int $ncolors)void

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

ttfText (int $size, int $angle, int $x, int $y, int $color, string $fontfile, string $text)array

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

verze: 4.0 3.x 2.x