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');
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
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) a WEBP (výchozí 80) 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->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
.
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
.
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í 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)
psText(string $text, int $font, int $size, int $color, int $backgroundColor, int $x, int $y, ?int $space=null, ?int $tightness=null, ?float $angle=null, ?int $antialiasSteps=null): array
Nakreslí text na obrázek pomocí písem PostScript Type1.
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) a WEBP (výchozí 80) 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
a Image::WEBP
.
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) a WEBP (výchozí 80) a 0..9 pro PNG (výchozí 9). Typ je
jednou z konstant Image::JPEG
, Image::PNG
, Image::GIF
a Image::WEBP
.
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) a WEBP (výchozí 80) a 0..9 pro PNG (výchozí 9). Typ je
jednou z konstant Image::JPEG
, Image::PNG
, Image::GIF
a Image::WEBP
.
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)