Arbeiten mit Bildern
********************
.[perex]
Die Klasse [api:Nette\Utils\Image] vereinfacht die Arbeit mit Bildern, etwa das Ändern der Größe, das Zuschneiden, Schärfen, Zeichnen oder das Zusammenfügen mehrerer Bilder.
PHP verfügt über einen umfangreichen Satz von Funktionen zur Bildbearbeitung. Deren API ist allerdings nicht besonders benutzerfreundlich. Es wäre nicht das Nette Framework, wenn es nicht mit einer angenehmen API käme.
Installation:
```shell
composer require nette/utils
```
Die folgenden Beispiele setzen voraus, dass diese Klassen-Aliase definiert sind:
```php
use Nette\Utils\Image;
use Nette\Utils\ImageColor;
use Nette\Utils\ImageType;
```
Erstellung eines Bildes
=======================
Erzeugen Sie ein neues Truecolor-Bild, zum Beispiel mit den Abmessungen 100×200:
```php
$image = Image::fromBlank(100, 200);
```
Optional können Sie die Hintergrundfarbe angeben (standardmäßig Schwarz):
```php
$image = Image::fromBlank(100, 200, ImageColor::rgb(125, 0, 0));
```
Oder Sie laden ein Bild aus einer Datei:
```php
$image = Image::fromFile('nette.jpg');
```
Speichern des Bildes
====================
Das Bild lässt sich in eine Datei speichern:
```php
$image->save('resampled.jpg');
```
Die Kompressionsqualität können Sie im Bereich 0-100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30) sowie 0-9 für PNG (Standard 9) angeben:
```php
$image->save('resampled.jpg', 80); // JPEG, Qualität 80 %
```
Wenn sich das Format nicht aus der Dateiendung ergibt, lässt es sich über eine [Konstante |#Formate] angeben:
```php
$image->save('resampled.tmp', null, ImageType::JPEG);
```
Statt es auf die Festplatte zu speichern, lässt sich das Bild auch in eine Variable schreiben:
```php
$data = $image->toString(ImageType::JPEG, 80); // JPEG, Qualität 80 %
```
oder direkt mit dem passenden HTTP-Header `Content-Type` an den Browser senden:
```php
// sendet den Header Content-Type: image/png
$image->send(ImageType::PNG);
```
Formate
=======
Unterstützt werden JPEG, PNG, GIF, WebP, AVIF und BMP. Ihre PHP-Version muss sie allerdings ebenfalls unterstützen, was Sie mit der Funktion [#isTypeSupported()] prüfen können. Animationen werden nicht unterstützt.
Die Formate werden durch die Konstanten `ImageType::JPEG`, `ImageType::PNG`, `ImageType::GIF`, `ImageType::WEBP`, `ImageType::AVIF` und `ImageType::BMP` repräsentiert.
```php
$supported = Image::isTypeSupported(ImageType::JPEG);
```
Sie müssen das Format des Bildes beim Laden erkennen? Die Methode gibt es im zweiten Parameter zurück:
```php
$image = Image::fromFile('nette.jpg', $type);
```
Die Erkennung, ohne das Bild selbst zu laden, erledigt `Image::detectTypeFromFile()`.
Größenänderung
==============
Eine häufige Aufgabe ist das Ändern der Bildgröße. Die aktuellen Abmessungen liefern die Methoden `getWidth()` und `getHeight()`.
Zum Ändern der Größe dient die Methode `resize()`. Beispiel für eine proportionale Änderung, sodass das Bild 500x300 Pixel nicht überschreitet (entweder ist die Breite genau 500px oder die Höhe genau 300px; die zweite Abmessung wird so berechnet, dass das Seitenverhältnis erhalten bleibt):
```php
$image->resize(500, 300);
```
Es lässt sich auch nur eine Abmessung angeben, die zweite wird dann automatisch berechnet:
```php
$image->resize(500, null); // Breite 500px, Höhe wird automatisch berechnet
$image->resize(null, 300); // Breite wird automatisch berechnet, Höhe 300px
```
Jede Abmessung lässt sich auch in Prozent angeben:
```php
$image->resize('75%', 300); // 75 % × 300px
```
Das Verhalten von `resize()` lässt sich durch die folgenden Flags beeinflussen. Alle Flags außer `Image::Stretch` erhalten das Seitenverhältnis.
|---------------------------------------------------------------------------------------
| Flag | Beschreibung
|---------------------------------------------------------------------------------------
| `Image::OrSmaller` (Standard) | die resultierenden Abmessungen sind kleiner oder gleich den geforderten Abmessungen
| `Image::OrBigger` | füllt den Zielbereich aus (und überschreitet ihn eventuell in einer Abmessung)
| `Image::Cover` | füllt den Zielbereich aus und schneidet ab, was darüber hinausgeht
| `Image::ShrinkOnly` | verkleinert nur (verhindert das Hochskalieren eines kleinen Bildes)
| `Image::Stretch` | erhält das Seitenverhältnis nicht
Die Flags werden der Methode als drittes Argument übergeben:
```php
$image->resize(500, 300, Image::OrBigger);
```
Flags lassen sich kombinieren:
```php
$image->resize(500, 300, Image::ShrinkOnly | Image::Stretch);
```
Bilder lassen sich vertikal oder horizontal spiegeln, indem eine der Abmessungen (oder beide) als negative Zahl angegeben wird:
```php
$flipped = $image->resize(null, '-100%'); // vertikal spiegeln
$flipped = $image->resize('-100%', '-100%'); // um 180° drehen
$flipped = $image->resize(-125, 500); // Größe ändern & horizontal spiegeln
```
Nach dem Ändern der Größe können Sie das Aussehen des Bildes durch dezentes Schärfen verbessern:
```php
$image->sharpen();
```
Zuschneiden
===========
Zum Zuschneiden dient die Methode `crop()`:
```php
$image->crop($left, $top, $width, $height);
```
Wie bei `resize()` lassen sich alle Werte in Prozent angeben. Die Prozentwerte für `$left` und `$top` werden aus dem verbleibenden Platz berechnet, ähnlich wie bei der CSS-Eigenschaft `background-position`:
```php
$image->crop('100%', '50%', '80%', '80%');
```
[* crop.svg *]
Das Bild lässt sich auch automatisch zuschneiden, etwa um schwarze Ränder zu entfernen:
```php
$image->cropAuto(IMG_CROP_BLACK);
```
Die Methode `cropAuto()` ist ein objektorientierter Wrapper für die Funktion `imagecropauto()`, mehr dazu in [ihrer Dokumentation|https://www.php.net/manual/en/function.imagecropauto].
Farben .{data-version:4.0.2}
============================
Mit der Methode `ImageColor::rgb()` lässt sich eine Farbe über die Werte für Rot, Grün und Blau (RGB) definieren. Optional können Sie zusätzlich einen Transparenzwert von 0 (völlig transparent) bis 1 (völlig deckend) angeben, genau wie in CSS.
```php
$color = ImageColor::rgb(255, 0, 0); // Rot
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // halbtransparentes Blau
```
Mit der Methode `ImageColor::hex()` lässt sich eine Farbe im Hexadezimalformat definieren, ähnlich wie in CSS. Unterstützt werden die Formate `#rgb`, `#rrggbb`, `#rgba` und `#rrggbbaa`:
```php
$color = ImageColor::hex("#F00"); // Rot
$transparentGreen = ImageColor::hex("#00FF0080"); // halbtransparentes Grün
```
Farben lassen sich in weiteren Methoden verwenden, etwa in `ellipse()`, `fill()` und so weiter.
Zeichnen und Bearbeiten
=======================
Alle PHP-Funktionen zur Bildbearbeitung stehen Ihnen zur Verfügung, siehe [#Methodenübersicht], allerdings in objektorientierter Form:
```php
$image->filledEllipse($centerX, $centerY, $width, $height, ImageColor::rgb(255, 0, 0));
```
Weil die nativen PHP-Funktionen zum Zeichnen von Rechtecken wegen der Angabe der Koordinaten etwas unpraktisch sind, bietet die Klasse `Image` Ersatz an: [#rectangleWH()] und [#filledRectangleWH()].
Zusammenfügen mehrerer Bilder
=============================
Sie können ein anderes Bild ganz leicht auf das aktuelle setzen:
```php
$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, ImageColor::rgb(52, 132, 210));
// die Koordinaten lassen sich auch in Prozent angeben
$blank->place($logo, '80%', '80%'); // nahe der rechten unteren Ecke platzieren
```
Beim Platzieren wird der Alphakanal berücksichtigt. Zusätzlich können Sie die Transparenz des platzierten Bildes beeinflussen und so ein Wasserzeichen erzeugen:
```php
$blank->place($image, '80%', '80%', 25); // die Deckkraft beträgt 25 %
```
Mit einer solchen API zu arbeiten ist wirklich ein Vergnügen!
Methodenübersicht
=================
static fromBlank(int $width, int $height, ?ImageColor $color=null): Image .[method]
-----------------------------------------------------------------------------------
Erzeugt ein neues Truecolor-Bild mit den angegebenen Abmessungen. Die Standardfarbe ist Schwarz.
static fromFile(string $file, int &$detectedFormat=null, string &$warnings=null): Image .[method]
-------------------------------------------------------------------------------------------------
Liest ein Bild aus einer Datei und gibt seinen [Typ |#Formate] in `$detectedFormat` zurück. Wenn Sie `$warnings` übergeben, werden darin nicht fatale Warnungen des Bilddecoders abgelegt, statt sie als PHP-Warnung auszulösen; gibt es keine, bleibt der Wert `null`.
static fromString(string $s, int &$detectedFormat=null, string &$warnings=null): Image .[method]
------------------------------------------------------------------------------------------------
Liest ein Bild aus einem String und gibt seinen [Typ |#Formate] in `$detectedFormat` zurück. Wenn Sie `$warnings` übergeben, werden darin nicht fatale Warnungen des Bilddecoders abgelegt, statt sie als PHP-Warnung auszulösen; gibt es keine, bleibt der Wert `null`.
static rgb(int $red, int $green, int $blue, int $transparency=0): array .[method][deprecated]
---------------------------------------------------------------------------------------------
Diese Funktion wurde durch die Klasse `ImageColor` ersetzt, siehe [#Farben].
static typeToExtension(int $type): string .[method]
---------------------------------------------------
Gibt die Dateiendung für den angegebenen [Typ |#Formate] zurück.
static typeToMimeType(int $type): string .[method]
--------------------------------------------------
Gibt den MIME-Typ für den angegebenen [Typ |#Formate] zurück.
static extensionToType(string $extension): int .[method]
--------------------------------------------------------
Gibt den [Typ |#Formate] des Bildes anhand der Dateiendung zurück.
static detectTypeFromFile(string $file, int &$width=null, int &$height=null): ?int .[method]
--------------------------------------------------------------------------------------------
Gibt den [Typ |#Formate] der Bilddatei zurück und in den Parametern `$width` und `$height` außerdem ihre Abmessungen.
static detectTypeFromString(string $s, int &$width=null, int &$height=null): ?int .[method]
-------------------------------------------------------------------------------------------
Gibt den [Typ |#Formate] des Bildes aus einem String zurück und in den Parametern `$width` und `$height` außerdem seine Abmessungen.
static isTypeSupported(int $type): bool .[method]
-------------------------------------------------
Prüft, ob der angegebene [Typ |#Formate] des Bildes unterstützt wird.
static getSupportedTypes(): array .[method]{data-version:4.0.4}
---------------------------------------------------------------
Gibt ein Array der unterstützten Bild[typen |#Formate] zurück.
static calculateTextBox(string $text, string $fontFile, float $size, float $angle=0, array $options=[]): array .[method]
------------------------------------------------------------------------------------------------------------------------
Berechnet die Abmessungen des Rechtecks, das den Text in einer bestimmten Schrift und Größe umschließt. Gibt ein assoziatives Array mit den Schlüsseln `left`, `top`, `width` und `height` zurück. Der linke Rand kann negativ sein, wenn der Text mit einem linken Unterschneidungsüberhang beginnt.
affine(array $affine, ?array $clip=null): Image .[method]
---------------------------------------------------------
Gibt ein Bild zurück, das das affin transformierte Ausgangsbild enthält, unter Verwendung eines optionalen Ausschnittbereichs. ([mehr |https://www.php.net/manual/en/function.imageaffine])
alphaBlending(bool $on): void .[method]
---------------------------------------
Erlaubt zwei verschiedene Modi zum Zeichnen auf Truecolor-Bildern. Im Blending-Modus bestimmt der Alphakanal der Farbe, die allen Zeichenfunktionen wie `setPixel()` übergeben wird, wie stark die darunterliegende Farbe durchscheinen darf. Die vorhandene Farbe an dieser Stelle wird dadurch automatisch mit der Zeichenfarbe gemischt und das Ergebnis im Bild gespeichert. Das resultierende Pixel ist deckend. Im Nicht-Blending-Modus wird die Zeichenfarbe wortwörtlich samt ihrer Alphakanal-Information kopiert und ersetzt das Zielpixel. Auf Palettenbildern steht der Blending-Modus nicht zur Verfügung. ([mehr |https://www.php.net/manual/en/function.imagealphablending])
antialias(bool $on): void .[method]
-----------------------------------
Aktiviert die schnellen Zeichenmethoden mit Antialiasing für Linien und Drahtgitter-Polygone. Alphakomponenten werden nicht unterstützt. Es arbeitet mit einer direkten Blend-Operation und funktioniert nur mit Truecolor-Bildern.
Antialiasing-Primitive mit transparenter Hintergrundfarbe können zu unerwarteten Ergebnissen führen. Die Blend-Methode behandelt die Hintergrundfarbe wie jede andere Farbe. Die fehlende Unterstützung der Alphakomponente erlaubt kein Antialiasing auf Alpha-Basis. ([mehr |https://www.php.net/manual/en/function.imageantialias])
arc(int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color): void .[method]
---------------------------------------------------------------------------------------------------------------------------
Zeichnet einen Kreisbogen mit dem Mittelpunkt an den angegebenen Koordinaten. ([mehr |https://www.php.net/manual/en/function.imagearc])
colorAllocate(int $red, int $green, int $blue): int .[method]
-------------------------------------------------------------
Gibt einen Farbbezeichner zurück, der die aus den angegebenen RGB-Komponenten zusammengesetzte Farbe repräsentiert. Die Methode muss für jede Farbe aufgerufen werden, die im Bild verwendet werden soll. ([mehr |https://www.php.net/manual/en/function.imagecolorallocate])
colorAllocateAlpha(int $red, int $green, int $blue, int $alpha): int .[method]
------------------------------------------------------------------------------
Verhält sich identisch zu `colorAllocate()`, ergänzt um den Transparenzparameter `$alpha`. ([mehr |https://www.php.net/manual/en/function.imagecolorallocatealpha])
colorAt(int $x, int $y): int .[method]
--------------------------------------
Gibt den Farbindex des Pixels an der angegebenen Stelle im Bild zurück. Bei einem Truecolor-Bild gibt die Funktion den RGB-Wert dieses Pixels als ganze Zahl zurück. Verwenden Sie Bitverschiebung und Maskierung, um an die einzelnen Werte der Rot-, Grün- und Blau-Komponente zu kommen: ([mehr |https://www.php.net/manual/en/function.imagecolorat])
colorClosest(int $red, int $green, int $blue): int .[method]
------------------------------------------------------------
Gibt den Index der Farbe in der Palette des Bildes zurück, die dem angegebenen RGB-Wert am "nächsten" ist. Der "Abstand" zwischen der gewünschten Farbe und jeder Farbe der Palette wird so berechnet, als wären die RGB-Werte Punkte im dreidimensionalen Raum. ([mehr |https://www.php.net/manual/en/function.imagecolorclosest])
colorClosestAlpha(int $red, int $green, int $blue, int $alpha): int .[method]
-----------------------------------------------------------------------------
Gibt den Index der Farbe in der Palette des Bildes zurück, die dem angegebenen RGB-Wert und dem `$alpha`-Wert am "nächsten" ist. ([mehr |https://www.php.net/manual/en/function.imagecolorclosestalpha])
colorClosestHWB(int $red, int $green, int $blue): int .[method]
---------------------------------------------------------------
Ermittelt den Index der Farbe, deren Farbton, Weiß- und Schwarzanteil der angegebenen Farbe am nächsten kommt. ([mehr |https://www.php.net/manual/en/function.imagecolorclosesthwb])
colorDeallocate(int $color): void .[method]
-------------------------------------------
Gibt eine Farbe frei, die zuvor mit `colorAllocate()` oder `colorAllocateAlpha()` reserviert wurde. ([mehr |https://www.php.net/manual/en/function.imagecolordeallocate])
colorExact(int $red, int $green, int $blue): int .[method]
----------------------------------------------------------
Gibt den Index der angegebenen Farbe in der Palette des Bildes zurück. ([mehr |https://www.php.net/manual/en/function.imagecolorexact])
colorExactAlpha(int $red, int $green, int $blue, int $alpha): int .[method]
---------------------------------------------------------------------------
Gibt den Index der angegebenen Farbe samt Alpha in der Palette des Bildes zurück. ([mehr |https://www.php.net/manual/en/function.imagecolorexactalpha])
colorMatch(Image $image2): void .[method]
-----------------------------------------
Gleicht die Farben der Palettenversion eines Bildes stärker an die Truecolor-Version an. ([mehr |https://www.php.net/manual/en/function.imagecolormatch])
colorResolve(int $red, int $green, int $blue): int .[method]
------------------------------------------------------------
Gibt einen Farbindex für die gewünschte Farbe zurück, entweder die exakte Farbe oder die nächstmögliche Alternative. ([mehr |https://www.php.net/manual/en/function.imagecolorresolve])
colorResolveAlpha(int $red, int $green, int $blue, int $alpha): int .[method]
-----------------------------------------------------------------------------
Gibt einen Farbindex für die gewünschte Farbe zurück, entweder die exakte Farbe oder die nächstmögliche Alternative. ([mehr |https://www.php.net/manual/en/function.imagecolorresolvealpha])
colorSet(int $index, int $red, int $green, int $blue, int $alpha=0): void .[method]
-----------------------------------------------------------------------------------
Setzt den angegebenen Index in der Palette auf die angegebene Farbe. ([mehr |https://www.php.net/manual/en/function.imagecolorset])
colorsForIndex(int $index): array .[method]
-------------------------------------------
Ermittelt die Farbe für einen angegebenen Index. ([mehr |https://www.php.net/manual/en/function.imagecolorsforindex])
colorsTotal(): int .[method]
----------------------------
Gibt die Anzahl der Farben in der Palette des Bildes zurück. ([mehr |https://www.php.net/manual/en/function.imagecolorstotal])
colorTransparent(?int $color=null): int .[method]
-------------------------------------------------
Ermittelt oder setzt die transparente Farbe im Bild. ([mehr |https://www.php.net/manual/en/function.imagecolortransparent])
convolution(array $matrix, float $div, float $offset): void .[method]
---------------------------------------------------------------------
Wendet eine Faltungsmatrix auf das Bild an, mit dem angegebenen Koeffizienten und Offset. ([mehr |https://www.php.net/manual/en/function.imageconvolution])
.[note]
Erfordert die *Bundled GD extension*, funktioniert also möglicherweise nicht überall.
copy(Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH): void .[method]
--------------------------------------------------------------------------------------------------
Kopiert einen Teil von `$src` in das Bild, beginnend bei den Koordinaten `$srcX`, `$srcY`, mit der Breite `$srcW` und der Höhe `$srcH`. Der so definierte Ausschnitt wird an die Koordinaten `$dstX` und `$dstY` kopiert. ([mehr |https://www.php.net/manual/en/function.imagecopy])
copyMerge(Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void .[method]
---------------------------------------------------------------------------------------------------------------------
Kopiert einen Teil von `$src` in das Bild, beginnend bei den Koordinaten `$srcX`, `$srcY`, mit der Breite `$srcW` und der Höhe `$srcH`. Der so definierte Ausschnitt wird an die Koordinaten `$dstX` und `$dstY` kopiert. ([mehr |https://www.php.net/manual/en/function.imagecopymerge])
copyMergeGray(Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void .[method]
-------------------------------------------------------------------------------------------------------------------------
Kopiert einen Teil von `$src` in das Bild, beginnend bei den Koordinaten `$srcX`, `$srcY`, mit der Breite `$srcW` und der Höhe `$srcH`. Der so definierte Ausschnitt wird an die Koordinaten `$dstX` und `$dstY` kopiert.
Diese Funktion ist identisch mit `copyMerge()`, nur bewahrt sie beim Zusammenführen den Farbton der Quelle, indem sie die Zielpixel vor dem Kopieren in Graustufen umwandelt. ([mehr |https://www.php.net/manual/en/function.imagecopymergegray])
copyResampled(Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void .[method]
---------------------------------------------------------------------------------------------------------------------------------
Kopiert einen rechteckigen Ausschnitt eines Bildes in ein anderes Bild und interpoliert die Pixelwerte dabei weich, sodass insbesondere beim Verkleinern eines Bildes viel Schärfe erhalten bleibt.
Mit anderen Worten: `copyResampled()` nimmt aus `$src` einen rechteckigen Bereich der Breite `$srcW` und der Höhe `$srcH` an der Position (`$srcX`,`$srcY`) und setzt ihn in einen rechteckigen Bereich des Bildes mit der Breite `$dstW` und der Höhe `$dstH` an der Position (`$dstX`,`$dstY`).
Unterscheiden sich die Koordinaten sowie Breite und Höhe von Quelle und Ziel, wird der Bildausschnitt entsprechend gestreckt oder gestaucht. Die Koordinaten beziehen sich auf die linke obere Ecke. Mit dieser Funktion lassen sich auch Bereiche innerhalb desselben Bildes kopieren, überlappen sich die Bereiche jedoch, ist das Ergebnis unvorhersehbar. ([mehr |https://www.php.net/manual/en/function.imagecopyresampled])
copyResized(Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void .[method]
-------------------------------------------------------------------------------------------------------------------------------
Kopiert einen rechteckigen Ausschnitt eines Bildes in ein anderes Bild. Mit anderen Worten: `copyResized()` nimmt aus `$src` einen rechteckigen Bereich der Breite `$srcW` und der Höhe `$srcH` an der Position (`$srcX`,`$srcY`) und setzt ihn in einen rechteckigen Bereich des Bildes mit der Breite `$dstW` und der Höhe `$dstH` an der Position (`$dstX`,`$dstY`).
Unterscheiden sich die Koordinaten sowie Breite und Höhe von Quelle und Ziel, wird der Bildausschnitt entsprechend gestreckt oder gestaucht. Die Koordinaten beziehen sich auf die linke obere Ecke. Mit dieser Funktion lassen sich auch Bereiche innerhalb desselben Bildes kopieren, überlappen sich die Bereiche jedoch, ist das Ergebnis unvorhersehbar. ([mehr |https://www.php.net/manual/en/function.imagecopyresized])
crop(int|string $left, int|string $top, int|string $width, int|string $height): Image .[method]
-----------------------------------------------------------------------------------------------
Schneidet das Bild auf den angegebenen rechteckigen Bereich zu. Die Abmessungen lassen sich als ganze Zahlen in Pixeln oder als Strings in Prozent angeben (z. B. `'50%'`).
cropAuto(int $mode=0, float $threshold=.5, ?ImageColor $color=null): Image .[method]
------------------------------------------------------------------------------------
Schneidet das Bild automatisch nach dem angegebenen `$mode` zu. ([mehr |https://www.php.net/manual/en/function.imagecropauto])
ellipse(int $centerX, int $centerY, int $width, int $height, ImageColor $color): void .[method]
-----------------------------------------------------------------------------------------------
Zeichnet eine Ellipse mit dem Mittelpunkt an den angegebenen Koordinaten. ([mehr |https://www.php.net/manual/en/function.imageellipse])
fill(int $x, int $y, ImageColor $color): void .[method]
-------------------------------------------------------
Führt eine Flächenfüllung ab der angegebenen Koordinate aus (links oben ist 0, 0), und zwar mit der Farbe `$color`. ([mehr |https://www.php.net/manual/en/function.imagefill])
filledArc(int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color, int $style): void .[method]
---------------------------------------------------------------------------------------------------------------------------------------------
Zeichnet einen Teilbogen mit dem Mittelpunkt an den angegebenen Koordinaten. ([mehr |https://www.php.net/manual/en/function.imagefilledarc])
filledEllipse(int $centerX, int $centerY, int $width, int $height, ImageColor $color): void .[method]
-----------------------------------------------------------------------------------------------------
Zeichnet eine Ellipse mit dem Mittelpunkt an den angegebenen Koordinaten. ([mehr |https://www.php.net/manual/en/function.imagefilledellipse])
filledPolygon(array $points, ImageColor $color): void .[method]
---------------------------------------------------------------
Erzeugt ein gefülltes Polygon im Bild. ([mehr |https://www.php.net/manual/en/function.imagefilledpolygon])
filledRectangle(int $x1, int $y1, int $x2, int $y2, ImageColor $color): void .[method]
--------------------------------------------------------------------------------------
Erzeugt im Bild ein mit `$color` gefülltes Rechteck, das am Punkt (`$x1`, `$y1`) beginnt und bei (`$x2`, `$y2`) endet. Der Punkt (0, 0) ist die linke obere Ecke des Bildes. ([mehr |https://www.php.net/manual/en/function.imagefilledrectangle])
filledRectangleWH(int $x, int $y, int $width, int $height, ImageColor $color): void .[method]
---------------------------------------------------------------------------------------------
Erzeugt im Bild ein mit `$color` gefülltes Rechteck, das am Punkt (`$x`, `$y`) beginnt und die Breite `$width` sowie die Höhe `$height` hat. Der Punkt (0, 0) ist die linke obere Ecke des Bildes.
fillToBorder(int $x, int $y, ImageColor $borderColor, ImageColor $color): void .[method]
----------------------------------------------------------------------------------------
Führt eine Flächenfüllung aus, deren Rand durch die Farbe `$borderColor` bestimmt ist. Startpunkt der Füllung ist (`$x`, `$y`) (links oben ist 0, 0), gefüllt wird der Bereich mit der Farbe `$color`. ([mehr |https://www.php.net/manual/en/function.imagefilltoborder])
filter(int $filtertype, int ...$args): void .[method]
-----------------------------------------------------
Wendet den angegebenen Filter `$filtertype` auf das Bild an. ([mehr |https://www.php.net/manual/en/function.imagefilter])
flip(int $mode): void .[method]
-------------------------------
Spiegelt das Bild gemäß dem angegebenen `$mode`. ([mehr |https://www.php.net/manual/en/function.imageflip])
ftText(float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array .[method]
----------------------------------------------------------------------------------------------------------------------------------------
Schreibt Text in das Bild. ([mehr |https://www.php.net/manual/en/function.imagefttext])
gammaCorrect(float $inputgamma, float $outputgamma): void .[method]
-------------------------------------------------------------------
Wendet auf das Bild eine Gammakorrektur mit dem angegebenen Eingangs- und Ausgangsgamma an. ([mehr |https://www.php.net/manual/en/function.imagegammacorrect])
getClip(): array .[method]
--------------------------
Liefert das aktuelle Beschneidungsrechteck, also den Bereich, außerhalb dessen keine Pixel gezeichnet werden. ([mehr |https://www.php.net/manual/en/function.imagegetclip])
getHeight(): int .[method]
--------------------------
Gibt die Höhe des Bildes zurück.
getImageResource(): GdImage .[method]
-------------------------------------
Gibt die zugrunde liegende GD-Bildressource zurück.
getWidth(): int .[method]
-------------------------
Gibt die Breite des Bildes zurück.
interlace(?int $interlace=null): int .[method]
----------------------------------------------
Schaltet das Interlacing ein oder aus. Ist Interlacing aktiviert und wird das Bild als JPEG gespeichert, entsteht ein progressives JPEG. ([mehr |https://www.php.net/manual/en/function.imageinterlace])
isTrueColor(): bool .[method]
-----------------------------
Prüft, ob das Bild ein Truecolor-Bild ist. ([mehr |https://www.php.net/manual/en/function.imageistruecolor])
layerEffect(int $effect): void .[method]
----------------------------------------
Setzt das Alpha-Blending-Flag für die Verwendung von Ebeneneffekten. ([mehr |https://www.php.net/manual/en/function.imagelayereffect])
line(int $x1, int $y1, int $x2, int $y2, ImageColor $color): void .[method]
---------------------------------------------------------------------------
Zeichnet eine Linie zwischen den beiden angegebenen Punkten. ([mehr |https://www.php.net/manual/en/function.imageline])
openPolygon(array $points, ImageColor $color): void .[method]
-------------------------------------------------------------
Zeichnet ein offenes Polygon in das Bild. Anders als bei `polygon()` wird zwischen dem letzten und dem ersten Punkt keine Linie gezogen. ([mehr |https://www.php.net/manual/en/function.imageopenpolygon])
paletteCopy(Image $source): void .[method]
------------------------------------------
Kopiert die Palette von `$source` in das Bild. ([mehr |https://www.php.net/manual/en/function.imagepalettecopy])
paletteToTrueColor(): void .[method]
------------------------------------
Wandelt ein palettenbasiertes Bild in ein Truecolor-Bild um. ([mehr |https://www.php.net/manual/en/function.imagepalettetotruecolor])
place(Image $image, int|string $left=0, int|string $top=0, int $opacity=100): Image .[method]
---------------------------------------------------------------------------------------------
Kopiert `$image` an den Koordinaten (`$left`, `$top`) in das aktuelle Bild. Die Koordinaten lassen sich als ganze Zahlen in Pixeln oder als Strings in Prozent angeben (z. B. `'50%'`).
polygon(array $points, ImageColor $color): void .[method]
---------------------------------------------------------
Erzeugt ein Polygon im Bild. ([mehr |https://www.php.net/manual/en/function.imagepolygon])
rectangle(int $x1, int $y1, int $x2, int $y2, ImageColor $color): void .[method]
--------------------------------------------------------------------------------
Erzeugt ein Rechteck an den angegebenen Koordinaten. ([mehr |https://www.php.net/manual/en/function.imagerectangle])
rectangleWH(int $x, int $y, int $width, int $height, ImageColor $color): void .[method]
---------------------------------------------------------------------------------------
Erzeugt ein Rechteck an den angegebenen Koordinaten anhand von Breite und Höhe.
resize(int|string $width, int|string $height, int $mode=Image::OrSmaller): Image .[method]
------------------------------------------------------------------------------------------
Ändert die Größe des Bildes, siehe [mehr Informationen |#Größenänderung]. Die Abmessungen lassen sich als ganze Zahlen in Pixeln oder als Strings in Prozent angeben (z. B. `'50%'`).
resolution(?int $resX=null, ?int $resY=null): mixed .[method]
-------------------------------------------------------------
Erlaubt es, die Auflösung eines Bildes in DPI (dots per inch) zu setzen und auszulesen. Wird keiner der optionalen Parameter angegeben, wird die aktuelle Auflösung als indiziertes Array zurückgegeben. Wird nur `$resX` angegeben, werden die horizontale und die vertikale Auflösung auf diesen Wert gesetzt. Werden beide optionalen Parameter angegeben, werden die horizontale und die vertikale Auflösung jeweils auf diese Werte gesetzt.
Die Auflösung dient nur als Metainformation, wenn Bilder aus Formaten gelesen oder in Formate geschrieben werden, die diese Art von Information unterstützen (derzeit PNG und JPEG). Auf Zeichenoperationen hat sie keinen Einfluss. Die Standardauflösung neuer Bilder beträgt 96 DPI. ([mehr |https://www.php.net/manual/en/function.imageresolution])
rotate(float $angle, ImageColor $backgroundColor): Image .[method]
------------------------------------------------------------------
Dreht das Bild um den angegebenen Winkel `$angle` in Grad. Das Drehzentrum ist die Mitte des Bildes, und das gedrehte Bild kann andere Abmessungen haben als das ursprüngliche. ([mehr |https://www.php.net/manual/en/function.imagerotate])
.[note]
Erfordert die *Bundled GD extension*, funktioniert also möglicherweise nicht überall.
save(string $file, ?int $quality=null, ?int $type=null): void .[method]
-----------------------------------------------------------------------
Speichert das Bild in eine Datei.
Die Kompressionsqualität liegt im Bereich 0-100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30) sowie 0-9 für PNG (Standard 9). Wenn sich der Typ nicht aus der Dateiendung ergibt, können Sie ihn über eine der Konstanten `ImageType` angeben.
saveAlpha(bool $saveflag): void .[method]
-----------------------------------------
Setzt das Flag, das bestimmt, ob beim Speichern von PNG-Bildern die vollständige Alphakanal-Information gespeichert wird (statt einer einfarbigen Transparenz).
Nette schaltet dieses Flag im Konstruktor von `Image` ein, ein über `fromFile()`, `fromString()` oder `fromBlank()` geladenes oder erzeugtes Bild behält seinen Alphakanal also. Beachten Sie, dass im Standard-Blending-Modus das Alpha einer gezeichneten Farbe nur zum Mischen des Ergebnisses dient und nicht gespeichert wird. Soll die gezeichnete Transparenz erhalten bleiben, rufen Sie also zuerst `alphaBlending(false)` auf. ([mehr |https://www.php.net/manual/en/function.imagesavealpha])
scale(int $newWidth, int $newHeight=-1, int $mode=IMG_BILINEAR_FIXED): Image .[method]
--------------------------------------------------------------------------------------
Skaliert ein Bild mit dem angegebenen Interpolationsalgorithmus. ([mehr |https://www.php.net/manual/en/function.imagescale])
send(int $type=ImageType::JPEG, ?int $quality=null): void .[method]
-------------------------------------------------------------------
Gibt das Bild an den Browser aus.
Die Kompressionsqualität liegt im Bereich 0-100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30) sowie 0-9 für PNG (Standard 9).
setBrush(Image $brush): void .[method]
--------------------------------------
Setzt das Pinselbild, das alle Funktionen zum Zeichnen von Linien (etwa `line()` und `polygon()`) verwenden, wenn mit den speziellen Farben `IMG_COLOR_BRUSHED` oder `IMG_COLOR_STYLEDBRUSHED` gezeichnet wird. ([mehr |https://www.php.net/manual/en/function.imagesetbrush])
setClip(int $x1, int $y1, int $x2, int $y2): void .[method]
-----------------------------------------------------------
Setzt das aktuelle Beschneidungsrechteck, also den Bereich, außerhalb dessen keine Pixel gezeichnet werden. ([mehr |https://www.php.net/manual/en/function.imagesetclip])
setInterpolation(int $method=IMG_BILINEAR_FIXED): void .[method]
----------------------------------------------------------------
Setzt die Interpolationsmethode, die sich auf die Methoden `rotate()` und `affine()` auswirkt. ([mehr |https://www.php.net/manual/en/function.imagesetinterpolation])
getInterpolation(): int .[method]
---------------------------------
Gibt die aktuelle Interpolationsmethode zurück, die die Methoden `rotate()` und `affine()` verwenden.
setPixel(int $x, int $y, ImageColor $color): void .[method]
-----------------------------------------------------------
Zeichnet ein Pixel an der angegebenen Koordinate. ([mehr |https://www.php.net/manual/en/function.imagesetpixel])
setStyle(array $style): void .[method]
--------------------------------------
Setzt den Stil, den alle Funktionen zum Zeichnen von Linien (etwa `line()` und `polygon()`) verwenden, wenn mit der speziellen Farbe `IMG_COLOR_STYLED` gezeichnet wird, oder für Linien aus Bildern mit der Farbe `IMG_COLOR_STYLEDBRUSHED`. ([mehr |https://www.php.net/manual/en/function.imagesetstyle])
setThickness(int $thickness): void .[method]
--------------------------------------------
Setzt die Stärke der Linien, die beim Zeichnen von Rechtecken, Polygonen, Bögen usw. gezogen werden, auf `$thickness` Pixel. ([mehr |https://www.php.net/manual/en/function.imagesetthickness])
setTile(Image $tile): void .[method]
------------------------------------
Setzt das Kachelbild, das alle Funktionen zum Füllen von Bereichen (etwa `fill()` und `filledPolygon()`) verwenden, wenn mit der speziellen Farbe `IMG_COLOR_TILED` gefüllt wird.
Eine Kachel ist ein Bild, mit dem ein Bereich in einem sich wiederholenden Muster gefüllt wird. Als Kachel lässt sich jedes Bild verwenden, und indem Sie mit `colorTransparent()` den Index der transparenten Farbe des Kachelbildes setzen, entsteht eine Kachel, durch die bestimmte Teile des darunterliegenden Bereichs durchscheinen. ([mehr |https://www.php.net/manual/en/function.imagesettile])
sharpen(): Image .[method]
--------------------------
Schärft das Bild.
.[note]
Erfordert die *Bundled GD extension*, funktioniert also möglicherweise nicht überall.
toString(int $type=ImageType::JPEG, ?int $quality=null): string .[method]
-------------------------------------------------------------------------
Gibt das Bild als String aus.
Die Kompressionsqualität liegt im Bereich 0-100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30) sowie 0-9 für PNG (Standard 9).
trueColorToPalette(bool $dither, int $ncolors): void .[method]
--------------------------------------------------------------
Wandelt ein Truecolor-Bild in ein Palettenbild um. ([mehr |https://www.php.net/manual/en/function.imagetruecolortopalette])
ttfText(float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array .[method]
-----------------------------------------------------------------------------------------------------------------------------------------
Schreibt den angegebenen Text in das Bild. ([mehr |https://www.php.net/manual/en/function.imagettftext])
Arbeiten mit Bildern
Die Klasse Nette\Utils\Image vereinfacht
die Arbeit mit Bildern, etwa das Ändern der Größe, das Zuschneiden, Schärfen, Zeichnen oder das Zusammenfügen mehrerer
Bilder.
PHP verfügt über einen umfangreichen Satz von Funktionen zur Bildbearbeitung. Deren API ist allerdings nicht besonders
benutzerfreundlich. Es wäre nicht das Nette Framework, wenn es nicht mit einer angenehmen API käme.
Installation:
composer require nette/utils
Die folgenden Beispiele setzen voraus, dass diese Klassen-Aliase definiert sind:
use Nette\Utils\Image;
use Nette\Utils\ImageColor;
use Nette\Utils\ImageType;
Erstellung eines Bildes
Erzeugen Sie ein neues Truecolor-Bild, zum Beispiel mit den Abmessungen 100×200:
$image = Image::fromBlank(100, 200);
Optional können Sie die Hintergrundfarbe angeben (standardmäßig Schwarz):
Die Kompressionsqualität können Sie im Bereich 0–100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30)
sowie 0–9 für PNG (Standard 9) angeben:
oder direkt mit dem passenden HTTP-Header Content-Type an den Browser senden:
// sendet den Header Content-Type: image/png
$image->send(ImageType::PNG);
Formate
Unterstützt werden JPEG, PNG, GIF, WebP, AVIF und BMP. Ihre PHP-Version muss sie allerdings ebenfalls unterstützen, was Sie
mit der Funktion isTypeSupported() prüfen können. Animationen werden nicht unterstützt.
Die Formate werden durch die Konstanten ImageType::JPEG, ImageType::PNG, ImageType::GIF,
ImageType::WEBP, ImageType::AVIF und ImageType::BMP repräsentiert.
Sie müssen das Format des Bildes beim Laden erkennen? Die Methode gibt es im zweiten Parameter zurück:
$image = Image::fromFile('nette.jpg', $type);
Die Erkennung, ohne das Bild selbst zu laden, erledigt Image::detectTypeFromFile().
Größenänderung
Eine häufige Aufgabe ist das Ändern der Bildgröße. Die aktuellen Abmessungen liefern die Methoden getWidth()
und getHeight().
Zum Ändern der Größe dient die Methode resize(). Beispiel für eine proportionale Änderung, sodass das Bild
500×300 Pixel nicht überschreitet (entweder ist die Breite genau 500px oder die Höhe genau 300px; die zweite Abmessung wird so
berechnet, dass das Seitenverhältnis erhalten bleibt):
$image->resize(500, 300);
Es lässt sich auch nur eine Abmessung angeben, die zweite wird dann automatisch berechnet:
$image->resize(500, null); // Breite 500px, Höhe wird automatisch berechnet
$image->resize(null, 300); // Breite wird automatisch berechnet, Höhe 300px
Jede Abmessung lässt sich auch in Prozent angeben:
$image->resize('75%', 300); // 75 % × 300px
Das Verhalten von resize() lässt sich durch die folgenden Flags beeinflussen. Alle Flags außer
Image::Stretch erhalten das Seitenverhältnis.
Flag
Beschreibung
Image::OrSmaller (Standard)
die resultierenden Abmessungen sind kleiner oder gleich den geforderten Abmessungen
Image::OrBigger
füllt den Zielbereich aus (und überschreitet ihn eventuell in einer Abmessung)
Image::Cover
füllt den Zielbereich aus und schneidet ab, was darüber hinausgeht
Image::ShrinkOnly
verkleinert nur (verhindert das Hochskalieren eines kleinen Bildes)
Image::Stretch
erhält das Seitenverhältnis nicht
Die Flags werden der Methode als drittes Argument übergeben:
Nach dem Ändern der Größe können Sie das Aussehen des Bildes durch dezentes Schärfen verbessern:
$image->sharpen();
Zuschneiden
Zum Zuschneiden dient die Methode crop():
$image->crop($left, $top, $width, $height);
Wie bei resize() lassen sich alle Werte in Prozent angeben. Die Prozentwerte für $left und
$top werden aus dem verbleibenden Platz berechnet, ähnlich wie bei der CSS-Eigenschaft
background-position:
$image->crop('100%', '50%', '80%', '80%');
Das Bild lässt sich auch automatisch zuschneiden, etwa um schwarze Ränder zu entfernen:
$image->cropAuto(IMG_CROP_BLACK);
Die Methode cropAuto() ist ein objektorientierter Wrapper für die Funktion imagecropauto(), mehr
dazu in ihrer Dokumentation.
Farben
Mit der Methode ImageColor::rgb() lässt sich eine Farbe über die Werte für Rot, Grün und Blau (RGB)
definieren. Optional können Sie zusätzlich einen Transparenzwert von 0 (völlig transparent) bis 1 (völlig deckend) angeben,
genau wie in CSS.
Mit der Methode ImageColor::hex() lässt sich eine Farbe im Hexadezimalformat definieren, ähnlich wie in CSS.
Unterstützt werden die Formate #rgb, #rrggbb, #rgba und #rrggbbaa:
Weil die nativen PHP-Funktionen zum Zeichnen von Rechtecken wegen der Angabe der Koordinaten etwas unpraktisch sind, bietet die
Klasse Image Ersatz an: rectangleWH() und filledRectangleWH().
Zusammenfügen mehrerer Bilder
Sie können ein anderes Bild ganz leicht auf das aktuelle setzen:
$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, ImageColor::rgb(52, 132, 210));
// die Koordinaten lassen sich auch in Prozent angeben
$blank->place($logo, '80%', '80%'); // nahe der rechten unteren Ecke platzieren
Beim Platzieren wird der Alphakanal berücksichtigt. Zusätzlich können Sie die Transparenz des platzierten Bildes
beeinflussen und so ein Wasserzeichen erzeugen:
$blank->place($image, '80%', '80%', 25); // die Deckkraft beträgt 25 %
Mit einer solchen API zu arbeiten ist wirklich ein Vergnügen!
Methodenübersicht
static fromBlank (int $width,
int $height, ?ImageColor $color=null): Image
Erzeugt ein neues Truecolor-Bild mit den angegebenen Abmessungen. Die Standardfarbe ist Schwarz.
static fromFile (string $file,
int &$detectedFormat=null, string &$warnings=null): Image
Liest ein Bild aus einer Datei und gibt seinen Typ in $detectedFormat zurück. Wenn Sie
$warnings übergeben, werden darin nicht fatale Warnungen des Bilddecoders abgelegt, statt sie als PHP-Warnung
auszulösen; gibt es keine, bleibt der Wert null.
static fromString (string $s,
int &$detectedFormat=null, string &$warnings=null): Image
Liest ein Bild aus einem String und gibt seinen Typ in $detectedFormat zurück. Wenn
Sie $warnings übergeben, werden darin nicht fatale Warnungen des Bilddecoders abgelegt, statt sie als PHP-Warnung
auszulösen; gibt es keine, bleibt der Wert null.
static rgb (int $red,
int $green, int $blue, int $transparency=0): array
Diese Funktion wurde durch die Klasse ImageColor ersetzt, siehe Farben.
static typeToExtension (int
$type): string
Gibt die Dateiendung für den angegebenen Typ zurück.
Berechnet die Abmessungen des Rechtecks, das den Text in einer bestimmten Schrift und Größe umschließt. Gibt ein
assoziatives Array mit den Schlüsseln left, top, width und height zurück.
Der linke Rand kann negativ sein, wenn der Text mit einem linken Unterschneidungsüberhang beginnt.
affine (array $affine, ?array
$clip=null): Image
Gibt ein Bild zurück, das das affin transformierte Ausgangsbild enthält, unter Verwendung eines optionalen
Ausschnittbereichs. (mehr)
alphaBlending (bool $on): void
Erlaubt zwei verschiedene Modi zum Zeichnen auf Truecolor-Bildern. Im Blending-Modus bestimmt der Alphakanal der Farbe, die
allen Zeichenfunktionen wie setPixel() übergeben wird, wie stark die darunterliegende Farbe durchscheinen darf. Die
vorhandene Farbe an dieser Stelle wird dadurch automatisch mit der Zeichenfarbe gemischt und das Ergebnis im Bild gespeichert. Das
resultierende Pixel ist deckend. Im Nicht-Blending-Modus wird die Zeichenfarbe wortwörtlich samt ihrer Alphakanal-Information
kopiert und ersetzt das Zielpixel. Auf Palettenbildern steht der Blending-Modus nicht zur Verfügung. (mehr)
antialias (bool $on): void
Aktiviert die schnellen Zeichenmethoden mit Antialiasing für Linien und Drahtgitter-Polygone. Alphakomponenten werden nicht
unterstützt. Es arbeitet mit einer direkten Blend-Operation und funktioniert nur mit Truecolor-Bildern.
Antialiasing-Primitive mit transparenter Hintergrundfarbe können zu unerwarteten Ergebnissen führen. Die Blend-Methode
behandelt die Hintergrundfarbe wie jede andere Farbe. Die fehlende Unterstützung der Alphakomponente erlaubt kein Antialiasing
auf Alpha-Basis. (mehr)
arc (int $centerX, int $centerY, int
$width, int $height, int $startAngle, int $endAngle, ImageColor $color): void
Zeichnet einen Kreisbogen mit dem Mittelpunkt an den angegebenen Koordinaten. (mehr)
colorAllocate (int $red, int $green,
int $blue): int
Gibt einen Farbbezeichner zurück, der die aus den angegebenen RGB-Komponenten zusammengesetzte Farbe repräsentiert. Die
Methode muss für jede Farbe aufgerufen werden, die im Bild verwendet werden soll. (mehr)
colorAllocateAlpha (int $red, int
$green, int $blue, int $alpha): int
Verhält sich identisch zu colorAllocate(), ergänzt um den Transparenzparameter $alpha. (mehr)
colorAt (int $x, int $y): int
Gibt den Farbindex des Pixels an der angegebenen Stelle im Bild zurück. Bei einem Truecolor-Bild gibt die Funktion den
RGB-Wert dieses Pixels als ganze Zahl zurück. Verwenden Sie Bitverschiebung und Maskierung, um an die einzelnen Werte der Rot-,
Grün- und Blau-Komponente zu kommen: (mehr)
colorClosest (int $red, int $green,
int $blue): int
Gibt den Index der Farbe in der Palette des Bildes zurück, die dem angegebenen RGB-Wert am „nächsten“ ist. Der
„Abstand“ zwischen der gewünschten Farbe und jeder Farbe der Palette wird so berechnet, als wären die RGB-Werte Punkte im
dreidimensionalen Raum. (mehr)
colorClosestAlpha (int $red, int
$green, int $blue, int $alpha): int
Gibt den Index der Farbe in der Palette des Bildes zurück, die dem angegebenen RGB-Wert und dem $alpha-Wert am
„nächsten“ ist. (mehr)
colorClosestHWB (int $red, int $green,
int $blue): int
Ermittelt den Index der Farbe, deren Farbton, Weiß- und Schwarzanteil der angegebenen Farbe am nächsten kommt. (mehr)
colorDeallocate (int $color): void
Gibt eine Farbe frei, die zuvor mit colorAllocate() oder colorAllocateAlpha() reserviert wurde. (mehr)
colorExact (int $red, int $green,
int $blue): int
Gibt den Index der angegebenen Farbe in der Palette des Bildes zurück. (mehr)
colorExactAlpha (int $red, int $green,
int $blue, int $alpha): int
Gibt den Index der angegebenen Farbe samt Alpha in der Palette des Bildes zurück. (mehr)
colorMatch (Image $image2): void
Gleicht die Farben der Palettenversion eines Bildes stärker an die Truecolor-Version an. (mehr)
colorResolve (int $red, int $green,
int $blue): int
Gibt einen Farbindex für die gewünschte Farbe zurück, entweder die exakte Farbe oder die nächstmögliche Alternative. (mehr)
colorResolveAlpha (int $red, int
$green, int $blue, int $alpha): int
Gibt einen Farbindex für die gewünschte Farbe zurück, entweder die exakte Farbe oder die nächstmögliche Alternative. (mehr)
colorSet (int $index, int $red, int
$green, int $blue, int $alpha=0): void
Setzt den angegebenen Index in der Palette auf die angegebene Farbe. (mehr)
colorsForIndex (int $index): array
Ermittelt die Farbe für einen angegebenen Index. (mehr)
colorsTotal(): int
Gibt die Anzahl der Farben in der Palette des Bildes zurück. (mehr)
colorTransparent (?int
$color=null): int
Ermittelt oder setzt die transparente Farbe im Bild. (mehr)
Wendet eine Faltungsmatrix auf das Bild an, mit dem angegebenen Koeffizienten und Offset. (mehr)
Erfordert die Bundled GD extension, funktioniert also möglicherweise nicht überall.
copy (Image $src, int $dstX, int $dstY,
int $srcX, int $srcY, int $srcW, int $srcH): void
Kopiert einen Teil von $src in das Bild, beginnend bei den Koordinaten $srcX, $srcY, mit
der Breite $srcW und der Höhe $srcH. Der so definierte Ausschnitt wird an die Koordinaten
$dstX und $dstY kopiert. (mehr)
copyMerge (Image $src, int $dstX, int
$dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void
Kopiert einen Teil von $src in das Bild, beginnend bei den Koordinaten $srcX, $srcY, mit
der Breite $srcW und der Höhe $srcH. Der so definierte Ausschnitt wird an die Koordinaten
$dstX und $dstY kopiert. (mehr)
copyMergeGray (Image $src, int $dstX,
int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void
Kopiert einen Teil von $src in das Bild, beginnend bei den Koordinaten $srcX, $srcY, mit
der Breite $srcW und der Höhe $srcH. Der so definierte Ausschnitt wird an die Koordinaten
$dstX und $dstY kopiert.
Diese Funktion ist identisch mit copyMerge(), nur bewahrt sie beim Zusammenführen den Farbton der Quelle, indem
sie die Zielpixel vor dem Kopieren in Graustufen umwandelt. (mehr)
copyResampled (Image $src, int $dstX,
int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int
$srcH): void
Kopiert einen rechteckigen Ausschnitt eines Bildes in ein anderes Bild und interpoliert die Pixelwerte dabei weich, sodass
insbesondere beim Verkleinern eines Bildes viel Schärfe erhalten bleibt.
Mit anderen Worten: copyResampled() nimmt aus $src einen rechteckigen Bereich der Breite
$srcW und der Höhe $srcH an der Position ($srcX,$srcY) und setzt ihn in einen
rechteckigen Bereich des Bildes mit der Breite $dstW und der Höhe $dstH an der Position
($dstX,$dstY).
Unterscheiden sich die Koordinaten sowie Breite und Höhe von Quelle und Ziel, wird der Bildausschnitt entsprechend gestreckt
oder gestaucht. Die Koordinaten beziehen sich auf die linke obere Ecke. Mit dieser Funktion lassen sich auch Bereiche innerhalb
desselben Bildes kopieren, überlappen sich die Bereiche jedoch, ist das Ergebnis unvorhersehbar. (mehr)
copyResized (Image $src, int $dstX,
int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int
$srcH): void
Kopiert einen rechteckigen Ausschnitt eines Bildes in ein anderes Bild. Mit anderen Worten: copyResized() nimmt
aus $src einen rechteckigen Bereich der Breite $srcW und der Höhe $srcH an der Position
($srcX,$srcY) und setzt ihn in einen rechteckigen Bereich des Bildes mit der Breite $dstW
und der Höhe $dstH an der Position ($dstX,$dstY).
Unterscheiden sich die Koordinaten sowie Breite und Höhe von Quelle und Ziel, wird der Bildausschnitt entsprechend gestreckt
oder gestaucht. Die Koordinaten beziehen sich auf die linke obere Ecke. Mit dieser Funktion lassen sich auch Bereiche innerhalb
desselben Bildes kopieren, überlappen sich die Bereiche jedoch, ist das Ergebnis unvorhersehbar. (mehr)
Schneidet das Bild auf den angegebenen rechteckigen Bereich zu. Die Abmessungen lassen sich als ganze Zahlen in Pixeln oder als
Strings in Prozent angeben (z. B. '50%').
filledRectangle (int $x1, int $y1,
int $x2, int $y2, ImageColor $color): void
Erzeugt im Bild ein mit $color gefülltes Rechteck, das am Punkt ($x1, $y1) beginnt und
bei ($x2, $y2) endet. Der Punkt (0, 0) ist die linke obere Ecke des Bildes. (mehr)
filledRectangleWH (int $x, int $y,
int $width, int $height, ImageColor $color): void
Erzeugt im Bild ein mit $color gefülltes Rechteck, das am Punkt ($x, $y) beginnt und
die Breite $width sowie die Höhe $height hat. Der Punkt (0, 0) ist die linke obere Ecke des Bildes.
fillToBorder (int $x, int $y,
ImageColor $borderColor, ImageColor $color): void
Führt eine Flächenfüllung aus, deren Rand durch die Farbe $borderColor bestimmt ist. Startpunkt der Füllung
ist ($x, $y) (links oben ist 0, 0), gefüllt wird der Bereich mit der Farbe $color. (mehr)
filter (int $filtertype, int
…$args): void
Wendet den angegebenen Filter $filtertype auf das Bild an. (mehr)
flip (int $mode):
void
Spiegelt das Bild gemäß dem angegebenen $mode. (mehr)
ftText (float $size, float $angle, int
$x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array
Zeichnet ein offenes Polygon in das Bild. Anders als bei polygon() wird zwischen dem letzten und dem ersten Punkt
keine Linie gezogen. (mehr)
paletteCopy (Image $source): void
Kopiert die Palette von $source in das Bild. (mehr)
paletteToTrueColor(): void
Wandelt ein palettenbasiertes Bild in ein Truecolor-Bild um. (mehr)
place (Image $image, int|string $left=0,
int|string $top=0, int $opacity=100): Image
Kopiert $image an den Koordinaten ($left, $top) in das aktuelle Bild. Die Koordinaten
lassen sich als ganze Zahlen in Pixeln oder als Strings in Prozent angeben (z. B. '50%').
rectangle (int $x1, int $y1, int $x2,
int $y2, ImageColor $color): void
Erzeugt ein Rechteck an den angegebenen Koordinaten. (mehr)
rectangleWH (int $x, int $y, int
$width, int $height, ImageColor $color): void
Erzeugt ein Rechteck an den angegebenen Koordinaten anhand von Breite und Höhe.
resize (int|string $width, int|string $height,
int $mode=Image::OrSmaller): Image
Ändert die Größe des Bildes, siehe mehr Informationen. Die Abmessungen lassen sich als
ganze Zahlen in Pixeln oder als Strings in Prozent angeben (z. B. '50%').
Erlaubt es, die Auflösung eines Bildes in DPI (dots per inch) zu setzen und auszulesen. Wird keiner der optionalen Parameter
angegeben, wird die aktuelle Auflösung als indiziertes Array zurückgegeben. Wird nur $resX angegeben, werden die
horizontale und die vertikale Auflösung auf diesen Wert gesetzt. Werden beide optionalen Parameter angegeben, werden die
horizontale und die vertikale Auflösung jeweils auf diese Werte gesetzt.
Die Auflösung dient nur als Metainformation, wenn Bilder aus Formaten gelesen oder in Formate geschrieben werden, die diese
Art von Information unterstützen (derzeit PNG und JPEG). Auf Zeichenoperationen hat sie keinen Einfluss. Die Standardauflösung
neuer Bilder beträgt 96 DPI. (mehr)
Dreht das Bild um den angegebenen Winkel $angle in Grad. Das Drehzentrum ist die Mitte des Bildes, und das
gedrehte Bild kann andere Abmessungen haben als das ursprüngliche. (mehr)
Erfordert die Bundled GD extension, funktioniert also möglicherweise nicht überall.
save (string $file, ?int $quality=null,
?int $type=null): void
Speichert das Bild in eine Datei.
Die Kompressionsqualität liegt im Bereich 0–100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30) sowie
0–9 für PNG (Standard 9). Wenn sich der Typ nicht aus der Dateiendung ergibt, können Sie ihn über eine der Konstanten
ImageType angeben.
saveAlpha (bool $saveflag): void
Setzt das Flag, das bestimmt, ob beim Speichern von PNG-Bildern die vollständige Alphakanal-Information gespeichert wird
(statt einer einfarbigen Transparenz).
Nette schaltet dieses Flag im Konstruktor von Image ein, ein über fromFile(),
fromString() oder fromBlank() geladenes oder erzeugtes Bild behält seinen Alphakanal also. Beachten
Sie, dass im Standard-Blending-Modus das Alpha einer gezeichneten Farbe nur zum Mischen des Ergebnisses dient und nicht
gespeichert wird. Soll die gezeichnete Transparenz erhalten bleiben, rufen Sie also zuerst alphaBlending(false) auf.
(mehr)
scale (int $newWidth, int $newHeight=-1,
int $mode=IMG_BILINEAR_FIXED): Image
Skaliert ein Bild mit dem angegebenen Interpolationsalgorithmus. (mehr)
Die Kompressionsqualität liegt im Bereich 0–100 für JPEG (Standard 85), WEBP (Standard 80) und AVIF (Standard 30) sowie
0–9 für PNG (Standard 9).
setBrush (Image $brush): void
Setzt das Pinselbild, das alle Funktionen zum Zeichnen von Linien (etwa line() und polygon())
verwenden, wenn mit den speziellen Farben IMG_COLOR_BRUSHED oder IMG_COLOR_STYLEDBRUSHED gezeichnet
wird. (mehr)
setClip (int $x1, int $y1, int $x2,
int $y2): void
Setzt das aktuelle Beschneidungsrechteck, also den Bereich, außerhalb dessen keine Pixel gezeichnet werden. (mehr)
Setzt die Interpolationsmethode, die sich auf die Methoden rotate() und affine() auswirkt. (mehr)
getInterpolation(): int
Gibt die aktuelle Interpolationsmethode zurück, die die Methoden rotate() und affine()
verwenden.
setPixel (int $x, int $y, ImageColor
$color): void
Zeichnet ein Pixel an der angegebenen Koordinate. (mehr)
setStyle (array $style): void
Setzt den Stil, den alle Funktionen zum Zeichnen von Linien (etwa line() und polygon()) verwenden,
wenn mit der speziellen Farbe IMG_COLOR_STYLED gezeichnet wird, oder für Linien aus Bildern mit der Farbe
IMG_COLOR_STYLEDBRUSHED. (mehr)
setThickness (int $thickness): void
Setzt die Stärke der Linien, die beim Zeichnen von Rechtecken, Polygonen, Bögen usw. gezogen werden, auf
$thickness Pixel. (mehr)
setTile (Image $tile): void
Setzt das Kachelbild, das alle Funktionen zum Füllen von Bereichen (etwa fill() und filledPolygon())
verwenden, wenn mit der speziellen Farbe IMG_COLOR_TILED gefüllt wird.
Eine Kachel ist ein Bild, mit dem ein Bereich in einem sich wiederholenden Muster gefüllt wird. Als Kachel lässt sich jedes
Bild verwenden, und indem Sie mit colorTransparent() den Index der transparenten Farbe des Kachelbildes setzen,
entsteht eine Kachel, durch die bestimmte Teile des darunterliegenden Bereichs durchscheinen. (mehr)
sharpen(): Image
Schärft das Bild.
Erfordert die Bundled GD extension, funktioniert also möglicherweise nicht überall.