Die fertigen Filter von GD reichen für vieles. Sobald aber ein Effekt gefragt ist, den IMG_FILTER_GAUSSIAN_BLUR und seine Geschwister nicht kennen, ist Schluss. Dann bleibt der Weg eine Ebene tiefer, und der ist überraschend kurz.
Im Bild wandert ein kleines Raster über das Bild und errechnet daraus je einen neuen Bildpunkt. Genau das ist eine Faltung, und mehr steckt nicht dahinter.
Was PHP imageconvolution() macht
PHP imageconvolution() legt eine 3x3-Matrix über jeden Bildpunkt, multipliziert die neun Nachbarn mit den Werten der Matrix und macht aus der Summe den neuen Farbwert. Welcher Effekt dabei herauskommt, entscheiden allein diese neun Zahlen.
<?php
$bild = imagecreatefromjpeg('produkt.jpg');
$schaerfen = [
[ 0, -1, 0],
[-1, 5, -1],
[ 0, -1, 0],
];
imageconvolution($bild, $schaerfen, 1, 0);
imagejpeg($bild, 'produkt-scharf.jpg', 90);
imagedestroy($bild);
PHP imageconvolution() arbeitet dabei immer auf dem ganzen Bild und verändert es an Ort und Stelle. Die Mitte der Matrix verstärkt den Bildpunkt selbst, die vier direkten Nachbarn ziehen ab. Wo im Bild ein Kontrast liegt, wird er dadurch stärker. Auf einer gleichmäßigen Fläche heben sich die Werte gegenseitig auf, dort passiert nichts.
Syntax und Parameter der Function
Die englische Beschreibung nennt beide Zahlen, die neben der Matrix über das Ergebnis entscheiden:
imageconvolution(
GdImage $image,
array $matrix,
float $divisor,
float $offset
): bool
/* image - an image resource, returned by one of the image
creation functions
matrix - a 3x3 convolution matrix, given as three arrays
of three float values each
divisor - the divisor of the result of the convolution,
used for normalization
offset - color offset, added to each channel after the
division
return - true on success or false on failure
The same 3x3 matrix is applied to every pixel of the image.
Typical effects built this way are sharpening, blurring,
embossing and edge detection. Larger matrices are not
supported by the gd library.
The imageconvolution function requires PHP compiled with GD
support; the manual lists it under the image functions.
Example, the syntax of a sharpening matrix:
$matrix3x3 = [[0,-1,0], [-1,5,-1], [0,-1,0]];
The code below applies exactly this matrix. */
Der Divisor hält die Helligkeit stabil, der Offset verschiebt sie absichtlich. Beide werden gern auf gut Glück gesetzt, und dann sieht das Ergebnis aus wie ein Fehler.
Die Matrix: ein Array aus Float-Werten
Der zweite Parameter ist ein Array mit genau drei Einträgen, von denen jeder wieder ein Array mit drei Werten ist. Andere Größen nimmt die Funktion nicht an. Ein 5x5-Array führt nicht etwa zu einem größeren Radius, sondern zu einem ValueError.
<?php
/* Richtig: drei Arrays mit je drei Werten. */
$matrix3x3 = [
[0.5, 1.0, 0.5],
[1.0, 2.0, 1.0],
[0.5, 1.0, 0.5],
];
/* Float ist ausdruecklich erlaubt, nicht nur Integer.
Genau darueber laesst sich die Staerke feinstufig regeln. */
imageconvolution($bild, $matrix3x3, 8, 0);
Dass die Werte Float sein dürfen, ist die wichtigste Eigenschaft dieses Arrays. Mit ganzen Zahlen ist ein Effekt entweder ganz da oder gar nicht. Mit 0.5 und 1.5 lässt sich die Stärke stufenlos einstellen, und genau das können die fertigen Filter von GD nicht.
Divisor und Offset für die matrix3x3 wählen
PHP imageconvolution() rechnet die neun Produkte zusammen und teilt die Summe anschließend. Der Divisor ist deshalb in aller Regel die Summe aller neun Matrixwerte. Ergibt die Summe 9, wird auch durch 9 geteilt, und das Bild behält seine Helligkeit. Ist die Summe null, würde eine Division scheitern, deshalb steht dort dann eine 1.
<?php
$weich = [
[1, 1, 1],
[1, 1, 1],
[1, 1, 1],
];
/* Summe 9, also Divisor 9. Mit Divisor 1 waere das
Ergebnis neunmal zu hell und damit fast weiss. */
imageconvolution($bild, $weich, 9, 0);
Der Offset kommt nach der Division dazu und wirkt auf alle drei Farbkanäle gleich. Bei Matrizen, deren Summe null ergibt, landet das Ergebnis sonst im Schwarzen, weil negative Werte abgeschnitten werden. Ein Offset von 127 hebt so ein Bild in den mittleren Grauton, und genau davon lebt der Relief-Effekt weiter unten.
flowchart TD
A[Bildpunkt und 8 Nachbarn] --> B
B[Mit Matrixwerten multiplizieren] --> C
C[Neun Ergebnisse addieren] --> D
D[Durch Divisor teilen] --> E
E[Offset addieren] --> F
F[Auf 0 bis 255 begrenzen] --> G
G[Neuer Bildpunkt]
Der letzte Schritt wird oft übersehen. Alles unter null wird zu null, alles über 255 zu 255. Deshalb kippt ein zu groß geratener Divisor nicht in Graustufen, sondern frisst schlicht die Zeichnung weg.
Vier Example-Matrizen: Schärfen, Edge Detection, Relief
Die folgenden vier decken ab, wofür PHP imageconvolution() in der Praxis eingesetzt wird. Alle vier lassen sich unverändert übernehmen.
| Effekt | Matrix | Divisor | Offset | Wozu |
| Schärfen | 0 -1 0 / -1 5 -1 / 0 -1 0 | 1 | 0 | Thumbnails nach dem Verkleinern |
| Weichzeichnen | 1 1 1 / 1 1 1 / 1 1 1 | 9 | 0 | Hintergründe beruhigen |
| Kantenerkennung | -1 -1 -1 / -1 8 -1 / -1 -1 -1 | 1 | 0 | Umrisse freistellen, Vorlagen prüfen |
| Relief | -2 -1 0 / -1 1 1 / 0 1 2 | 1 | 127 | Prägung, Struktur sichtbar machen |
<?php
/* Kantenerkennung: die Mitte zaehlt achtfach, alle Nachbarn
ziehen einfach ab. Auf einer gleichmaessigen Flaeche ergibt
das null, also Schwarz. Nur an Kanten bleibt etwas uebrig. */
$kanten = [
[-1, -1, -1],
[-1, 8, -1],
[-1, -1, -1],
];
imageconvolution($bild, $kanten, 1, 0);
An PHP imageconvolution() ändert sich zwischen diesen vier Beispielen nichts, nur an den Zahlen. Beim Relief ist die Matrix bewusst schief gebaut. Die obere linke Ecke zieht ab, die untere rechte zählt doppelt, und dadurch entsteht der Eindruck von Licht aus einer Richtung. Ohne den Offset von 127 wäre das Ergebnis fast durchgehend schwarz.
PHP imageconvolution() oder imagefilter()?
GD bringt mit imagefilter() fertige Effekte mit, darunter IMG_FILTER_GAUSSIAN_BLUR, IMG_FILTER_EMBOSS und IMG_FILTER_EDGEDETECT. Wer genau diese Wirkung will, ist damit schneller und braucht PHP imageconvolution() nicht.
Interessant wird die Faltung, sobald der Effekt dazwischen liegen soll. Ein Weichzeichner, der nur halb so stark wirkt wie der eingebaute. Eine Schärfung, die nur die Waagerechte betont. Eine Kantenerkennung, die auf feine Linien anspricht und grobe ignoriert. Diese Abstufungen gibt es über die Konstanten nicht, über die neun Zahlen schon. Die fertigen Filter und den restlichen Werkzeugkasten behandelt PHP GD-Bibliothek zum programmatischen Erzeugen und Bearbeiten von Bildern.
<?php
/* Halbe Schaerfe: die Mitte auf 3 statt 5, dafuer
Divisor 1 beibehalten. Zwischen den Konstanten
von imagefilter gibt es diese Stufe nicht. */
$sanft = [
[ 0, -0.5, 0],
[-0.5, 3, -0.5],
[ 0, -0.5, 0],
];
imageconvolution($bild, $sanft, 1, 0);
Die Matrix nimmt Gleitkommazahlen, nicht nur ganze. Das ist die Stellschraube für alles, was zwischen zwei fertigen Filtern liegt.
Alphakanal: Transparenz an der Image-Resource
Bei PNG-Dateien mit Alphakanal hat PHP imageconvolution() einen Stolperstein, den die Dokumentation nur am Rande erwähnt. Die Faltung rechnet mit den Farbkanälen, und der Alphakanal fällt dabei unter den Tisch. Ein freigestelltes Logo hat nach dem Filter einen schwarzen Hintergrund.
<?php
$bild = imagecreatefrompng('logo.png');
/* Beides vor dem Speichern setzen, sonst ist die
Transparenz nach imageconvolution verloren. */
imagealphablending($bild, false);
imagesavealpha($bild, true);
imageconvolution($bild, $schaerfen, 1, 0);
imagepng($bild, 'logo-scharf.png');
Auch damit bleibt die Kante zwischen Motiv und Transparenz hart, weil die Faltung dort mit undefinierten Nachbarn rechnet. Bei Logos mit weichem Rand lohnt es sich, den Filter vor dem Freistellen anzuwenden.
Rückgabewert bool: was die Function meldet
Die Matrix ist auf 3x3 festgelegt. Größere Kernel, wie sie ein echter Gauss-Weichzeichner braucht, kennt die Funktion nicht. Der übliche Ausweg ist, PHP imageconvolution() mehrfach hintereinander anzuwenden: Drei Durchläufe mit der Weichzeichner-Matrix kommen einem größeren Radius nahe.
Und die Funktion arbeitet auf dem gesamten Bild. Einen Ausschnitt zu filtern, geht nur über den Umweg: Bereich in ein eigenes Bild kopieren, filtern, zurückkopieren. Wie sich ein Bereich sauber herauslösen lässt, zeigt PHP imagecrop() zum Zuschneiden von Bildern.
Zur Laufzeit: Jeder Bildpunkt kostet neun Multiplikationen. Bei einem Foto mit drei Millionen Punkten sind das 27 Millionen Rechenschritte je Durchlauf. Das läuft in C und ist deutlich schneller als eine eigene Schleife in PHP, aber für einen Webseitenaufruf ist es trotzdem zu viel. Solche Filter gehören in einen Hintergrundprozess oder auf ein bereits verkleinertes Bild.
Fazit
PHP imageconvolution() ist keine Alternative zu imagefilter(), sondern die Ebene darunter. Neun Zahlen bestimmen den Effekt, der Divisor hält die Helligkeit, der Offset verschiebt sie.
Die vier Matrizen aus der Tabelle decken den Alltag ab und lassen sich abwandeln, sobald man verstanden hat, was die Mitte und was die Nachbarn tun. Zwei Dinge kosten sonst Zeit: Bei PNG mit Transparenz gehören imagealphablending() und imagesavealpha() davor, und ein Filter auf einem unverkleinerten Foto hat in einem Webseitenaufruf nichts verloren.
