Práce s obrázky

Třída Nette\Utils\Image je určena pro základní manipulaci s obrázky. Zjednodušuje nejčastější úkony, jako je změna velikosti, doostření nebo odeslání do prohlížeče.

Základní použití

Základní manipulace s obrázky, jako je zmenšení, oříznutí nebo doostření, obnáší v PHP psaní nečitelného a nesrozumitelnému kódu. Vyjádřeno velmi diplomaticky :-) A to by nebyl Nette Framework, aby nepřišel s příjemnějším API.

Nejprve obrázek načteme ze souboru:

use Nette\Utils\Image;

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

nebo vytvoříme obrázek nový, prázdný, s rozměry 100×200:

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

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

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

A vypíšeme jeho rozměry:

echo "Rozměry jsou {$image->getWidth()} × {$image->getHeight()}";

Změna velikosti

Ke změně velikosti se používá metoda resize. První dva parametry určují šířku a výšku, volitelný třetí slouží pro příznaky.

Proporcionální změna velikosti tak, aby nepřesáhl rozměry 50×30 pixelů (buď bude šířka přesně 50 px nebo výška bude přesně 30 px, druhý rozměr se dopočítá tak, aby byl zachován poměr stran):

$image->resize(50, 30);

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

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

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

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

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

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(50, 30, Image::STRETCH);

Příznaky lze kombinovat:

$image->resize(50, 30, 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, 50); // resize & flip horizontal

Úpravy

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

$image->sharpen();

Obrázek ořízneme dle souřadnic obdélníku:

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

Zmenšený obrázek můžeme vložit do jiného (vytvoříme tzv. watermark):

$blank = Image::fromBlank(320, 240, Image::rgb(52, 132, 210));
$blank->place($image, 0, 0); // vložíme na pozici 0px, 0px

// souřadnice lze uvést opět v procentech
$blank->place($image, '80%', '75%', 25); // průhlednost je 25 %

Uložení obrázku

Obrázek lze uložit do souboru:

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

Volitelně lze stanovit i kvalitu a formát obrázku. (Pokud není uveden, detekuje se z přípony):

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

Podporovány jsou formáty PNG, GIF, JPEG a WEBP.

Alternativně lze obrázek uložit i do proměnné:

$binary = (string) $image;

nebo poslat přímo do prohlížeče s nastavením příslušné hlavičky Content-Type:

// odešle jako image/jpeg
$image->send();

// odešle jako image/png
$image->send(Image::PNG);

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

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í na obrazech truecolor. V režimu prolnutí určuje součást alfa kanálu barvy dodávané do všech funkcí kreslení, jako je například setPixel(), do jaké míry by měla být umožněna prosvítání základní barvy. Výsledkem je, že gd v tomto bodě automaticky smíchá existující barvu s barvou výkresu a výsledek uloží do obrázku. Výsledný pixel je neprůhledný. V režimu bez prolnutí se barva výkresu 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 rychlé kreslení antialiaed metod pro čáry a kabelové polygony. Nepodporuje alfa komponenty. Funguje to pomocí přímé směsi. 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. Nedostatek podpory alfa komponent neumožňuje antialiasingovou metodu založenou na alfa. (více)

arc($x, $y, $w, $h, $start, $end, $color)void

Nakreslí oblouk kruhu soustředěný na dané souřadnice. (více)

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

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

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

Nakreslí znak $char svisle na určenou souřadnici na daném obrázku. (více)

colorAllocate($red, $green, $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($red, $green, $blue, $alpha)int

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

colorAt($x, $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 masking pro přístup k výrazným hodnotám červené, zelené a modré složky: (více)

colorClosest($red, $green, $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($red, $green, $blue, $alpha)int

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

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

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

colorDeallocate($color): void

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

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

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

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

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

colorMatch(Image $image2)void

Přizpůsobí barvy palety verzi obrazu přesněji verzi skutečné barvy. (více)

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

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

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

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

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

Tím nastavíte zadaný index v paletě na zadanou barvu. To je užitečné pro vytváření efektů podobných záplavám v paletovaných obrazech bez režie provádění skutečné záplavy. (více)

colorsForIndex($index): array

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

colorsTotal(): int

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

colorTransparent($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, $dstX, $dstY, $srcX, $srcY, $srcW, $srcH)void

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

copyMerge(Image $src, $dstX, $dstY, $srcX, $srcY, $srcW, $srcH, $opacity)void

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

copyMergeGray(Image $src, $dstX, $dstY, $srcX, $srcY, $srcW, $srcH, $opacity)void

Zkopíruje část $src na snímek začínající na souřadnicích x/y $srcX, $srcY se šířkou $srcW a výškou $srcH. Definovaná část bude zkopírována na souřadnice x/y $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, $dstX, $dstY, $srcX, $srcY, $dstW, $dstH, $srcW, $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 od $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, $dstX, $dstY, $srcX, $srcY, $dstW, $dstH, $srcW, $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 od $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ř. '50%').

cropAuto(int $mode = –1, float $threshold = .5, int $color = –1)Image

Automaticky ořízne snímek podle daného $mode. (více)

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

Nakreslí elipsu vystředěnou na zadané souřadnice. (více)

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

Provádí záplavovou výplň počínaje danou souřadnicí (vlevo nahoře je 0, 0) s daným $color na obrázku. (více)

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

Nakreslí částečný oblouk vystředěný na zadané souřadnici v obrázku. (více)

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

Nakreslí elipsu vystředěnou na zadané souřadnici v obrázku. (více)

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

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

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

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

fillToBorder($x, $y, $border, $color)void

Provádí záplavovou 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($filtertype): void

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

flip(int $mode): void

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

ftText($size, $angle, $x, $y, $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 gama. (více)

getClip(): array

Načte aktuální obdélník oříznutí, 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($interlace = null): int

Zapíná nebo vypíná prokládaný bit. Pokud je prokládaný bit nastaven a obraz je použit jako obrázek JPEG, je obraz vytvořen jako progresivní JPEG. (více)

isTrueColor(): bool

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

layerEffect($effect): void

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

line($x1, $y1, $x2, $y2, $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 z $source do obrázku. (více)

paletteToTrueColor(): void

Převede obrázek založený na paletě vytvořený funkcemi jako create() na skutečný barevný obrázek, například createtruecolor(). (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 x/y $left a $top. Souřadnice je možné zadávat jako integery v pixelech nebo řetězce v procentech (např. '50%').

polygon(array $points, $numPoints, $color)void

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

psText(string $text, $font, $size, $color, $backgroundColor, $x, $y, $space = null, $tightness = null, float $angle = null, $antialiasSteps = null)array

Nakreslí text na obrázek pomocí písem PostScript Type1. (více)

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

Vytvoří obdélník začínající zadanými souřadnicemi. (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ř. '50%').

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

Umožňuje nastavit a získat 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, $backgroundColor)Image

Otočí snímek 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.

saveAlpha(bool $saveflag)void

Nastavuje příznak, který určuje, 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.

setBrush(Image $brush)void

Nastavuje obraz štětce, který se má použít 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í obdélník oříznutí, tj. Oblast, za kterou nebudou nakresleny žádné pixely. (více)

setInterpolation(int $method = IMG_BILINEAR_FIXED)void

Nastaví metodu interpolace, nastavení metody interpolace ovlivní vykreslování různých funkcí v GD, jako je například funkce rotate(). (více)

setPixel($x, $y, $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($thickness): void

Nastavuje tloušťku čar nakreslených 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 GD 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, aby mohly projít 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($font, $x, $y, string $str, $col)void

Nakreslí řetězec na zadané souřadnice. (více)

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

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

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

Uloží obrázek do řetezce.

trueColorToPalette(bool $dither, $ncolors)void

Převede obraz truecolor na obraz palety. Kód pro tuto funkci byl původně vytvořen z kódu knihovny Independent JPEG Group, což je vynikající. Kód byl upraven tak, aby ve výsledné paletě zachoval co nejvíce informací o alfa kanálech, kromě zachování co možná největších barev. Toto nefunguje tak dobře, jak by se dalo doufat. Obvykle je nejlepší namísto toho vytvořit jednoduše barevný výstupní obraz, který zaručuje nejvyšší kvalitu výstupu. (více)

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

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