Signatur
Beschreibung
imageconvolution() ermöglicht es, beliebige 3×3-Faltungsoperationen (Convolutions) auf ein GD-Bild anzuwenden. Eine Faltungsmatrix (auch Kernel genannt) definiert, wie jeder Pixel in Abhängigkeit seiner Nachbarpixel neu berechnet wird. Der Parameter $divisor normiert die Summe der Matrixwerte, und $offset verschiebt den resultierenden Farbwert additiv.
Typische Einsatzbereiche sind Schärfen (Sharpening), Weichzeichnen (Blur), Kantenerkennung (Edge Detection), Prägen (Emboss) und Reliefeffekte. Die Funktion bietet damit eine flexible Alternative zu den fest verdrahteten Filterfunktionen wie imagefilter().
Die Matrix muss exakt ein 3×3-Array sein (äußeres Array mit 3 Elementen, jedes ein Array mit 3 numerischen Werten). Wählt man als Divisor die Summe aller positiven Matrixwerte, bleibt die Gesamthelligkeit des Bildes erhalten.
Hinweis: Diese Funktion ist nur verfügbar, wenn PHP mit der eingebundenen GD-Bibliothek (Bundled GD) kompiliert wurde. Bei externen GD-Bibliotheken steht sie möglicherweise nicht zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Ein gültiges GD-Bildobjekt, das z. B. mit imagecreatetruecolor(), imagecreatefromjpeg() oder einer ähnlichen Funktion erstellt wurde. |
|
| $matrix Pflicht | array | Eine 3×3-Matrix als verschachteltes Array der Form [[a,b,c],[d,e,f],[g,h,i]]. Alle Werte müssen numerisch (int oder float) sein. |
|
| $divisor Pflicht | float | Divisor, durch den die Summe der gefalteten Pixelwerte geteilt wird. Üblicherweise die Summe der Matrixwerte, um die Helligkeit zu erhalten. Ein Wert von 1.0 lässt die Werte unverändert. |
|
| $offset Pflicht | float | Offset-Wert, der nach der Division zum Ergebnis addiert wird. Kann verwendet werden, um dunkle Ergebnisse (z. B. bei Kantenerkennung) aufzuhellen. Typisch ist 0 oder 127. |
Rückgabewert
true bei Erfolg zurück, oder false bei einem Fehler (z. B. ungültige Matrix, nicht unterstützte GD-Version).Beispiele
Schärfe-Filter mit benutzerdefiniertem Kernel
<?php
// Bild laden
$image = imagecreatefromjpeg('foto.jpg');
// Schärfe-Kernel (Sharpening)
$sharpen = [
[ 0, -1, 0],
[-1, 5, -1],
[ 0, -1, 0]
];
// Divisor = 1 (Summe der Matrixwerte: 0-1+0-1+5-1+0-1+0 = 1)
$result = imageconvolution($image, $sharpen, 1, 0);
if ($result) {
header('Content-Type: image/jpeg');
imagejpeg($image);
} else {
echo 'Fehler beim Anwenden der Faltungsmatrix.';
}
imagedestroy($image);
?>Kantenerkennung mit Offset zur Aufhellung
<?php
// Bild laden
$image = imagecreatefromjpeg('foto.jpg');
// Kantenerkennung: Laplace-Operator
$edges = [
[-1, -1, -1],
[-1, 8, -1],
[-1, -1, -1]
];
// Divisor 1, Offset 127 damit negative Werte sichtbar werden
$result = imageconvolution($image, $edges, 1, 127);
if ($result) {
header('Content-Type: image/png');
imagepng($image);
} else {
echo 'Fehler beim Anwenden der Faltungsmatrix.';
}
imagedestroy($image);
?>Gauß'scher Weichzeichner (3×3)
<?php
$image = imagecreatefromjpeg('foto.jpg');
// Gauss-Blur-Kernel
$blur = [
[1, 2, 1],
[2, 4, 2],
[1, 2, 1]
];
// Divisor = Summe aller Werte = 16
imageconvolution($image, $blur, 16, 0);
header('Content-Type: image/jpeg');
imagejpeg($image, null, 90);
imagedestroy($image);
?>// Wichtig · Fallstricke
Bundled GD erforderlich: imageconvolution() ist nur mit der in PHP eingebetteten GD-Bibliothek verfügbar. Bei einer extern gelinkten GD-Bibliothek steht die Funktion nicht zur Verfügung. Die Verfügbarkeit lässt sich mit function_exists('imageconvolution') prüfen.
Matrixformat: Die Matrix muss exakt aus 3 Zeilen mit je 3 numerischen Werten bestehen. Ein falsches Format führt zu false als Rückgabewert. Fehlende oder überzählige Elemente werden nicht automatisch ergänzt oder ignoriert.
Divisor = 0: Ein Divisor von 0 führt zu einer Division durch Null und sollte unbedingt vermieden werden. PHP gibt in diesem Fall einen Fehler aus.
Performance: Bei großen Bildern kann die Faltungsoperation rechenintensiv sein. Für einfache Standardoperationen (Blur, Schärfen) ist imagefilter() mit vordefinierten Konstanten wie IMG_FILTER_GAUSSIAN_BLUR oft schneller.