Signatur
Beschreibung
imagesetpixel() färbt exakt einen Pixel im Bild-Objekt $image an der Koordinate ($x, $y) mit der gewünschten Farbe ein. Die Funktion ist das grundlegendste Zeichenwerkzeug der GD-Bibliothek und damit die Basis für alle höheren Zeichenoperationen.
Typische Anwendungsfälle sind das manuelle Rendern eigener Grafikalgorithmen (z. B. fraktale Kurven, Mandelbrot-Mengen, benutzerdefinierte Zeichenpfade) oder das pixelgenaue Nachbearbeiten einzelner Bildpunkte. Für das massenhafte Lesen oder Schreiben von Pixeln sollte man jedoch die effizienteren Funktionen imagecopyresampled() oder imagefilter() in Betracht ziehen, da imagesetpixel() bei großen Bildern durch den Overhead pro Aufruf langsam werden kann.
Koordinatenursprung ist die obere linke Ecke des Bildes mit (0, 0). Der Farb-Parameter muss ein mit imagecolorallocate() oder imagecolorallocatealpha() erzeugter Farbindex sein, oder ein über imagecolorexact() ermittelter Wert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Ein GD-Bildobjekt, das z. B. mit imagecreatetruecolor(), imagecreatefromjpeg() oder einer ähnlichen Funktion erzeugt wurde. |
|
| $x Pflicht | int | Die horizontale Koordinate des Pixels (0 = linker Rand). | |
| $y Pflicht | int | Die vertikale Koordinate des Pixels (0 = oberer Rand). | |
| $color Pflicht | int | Ein Farbindex, der zuvor mit imagecolorallocate() oder imagecolorallocatealpha() erzeugt wurde. Bei True-Color-Bildern kann auch ein direkt berechneter RGBA-Integer übergeben werden. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. wenn die Koordinaten außerhalb des Bildbereichs liegen oder das Bildobjekt ungültig ist).Beispiele
Einzelnen farbigen Pixel in ein neues Bild setzen
<?php
// Ein 100x100 True-Color-Bild erstellen
$bild = imagecreatetruecolor(100, 100);
// Hintergrundfarbe: Weiß
$weiss = imagecolorallocate($bild, 255, 255, 255);
imagefill($bild, 0, 0, $weiss);
// Einen roten Pixel in der Mitte setzen
$rot = imagecolorallocate($bild, 255, 0, 0);
imagesetpixel($bild, 50, 50, $rot);
// Bild als PNG ausgeben
header('Content-Type: image/png');
imagepng($bild);
imagedestroy($bild);Einfaches Fraktal (Diagonale Linie) mit imagesetpixel zeichnen
<?php
// Ein 200x200 True-Color-Bild erstellen
$bild = imagecreatetruecolor(200, 200);
// Schwarzen Hintergrund erzeugen
$schwarz = imagecolorallocate($bild, 0, 0, 0);
imagefill($bild, 0, 0, $schwarz);
// Gelbe Diagonale von (0,0) bis (199,199) zeichnen
$gelb = imagecolorallocate($bild, 255, 255, 0);
for ($i = 0; $i < 200; $i++) {
imagesetpixel($bild, $i, $i, $gelb);
}
// Bild als PNG ausgeben
header('Content-Type: image/png');
imagepng($bild);
imagedestroy($bild);Mandelbrot-Menge mit imagesetpixel visualisieren
<?php
$breite = 400;
$hoehe = 300;
$bild = imagecreatetruecolor($breite, $hoehe);
$schwarz = imagecolorallocate($bild, 0, 0, 0);
$weiss = imagecolorallocate($bild, 255, 255, 255);
imagefill($bild, 0, 0, $schwarz);
for ($px = 0; $px < $breite; $px++) {
for ($py = 0; $py < $hoehe; $py++) {
$cx = ($px / $breite) * 3.5 - 2.5;
$cy = ($py / $hoehe) * 2.0 - 1.0;
$x = 0.0;
$y = 0.0;
$iteration = 0;
$maxIter = 50;
while ($x * $x + $y * $y <= 4 && $iteration < $maxIter) {
$xNeu = $x * $x - $y * $y + $cx;
$y = 2 * $x * $y + $cy;
$x = $xNeu;
$iteration++;
}
if ($iteration === $maxIter) {
imagesetpixel($bild, $px, $py, $weiss);
}
}
}
header('Content-Type: image/png');
imagepng($bild);
imagedestroy($bild);// Wichtig · Fallstricke
Performance: Da imagesetpixel() pro Aufruf einen einzelnen Pixel setzt, ist es bei großen Bildern oder komplexen Algorithmen sehr langsam. Für Massenoperationen sollte man, wenn möglich, auf imagecopy(), imagefilter() oder dedizierte Zeichenfunktionen wie imageline() zurückgreifen.
Koordinatengrenzen: Koordinaten außerhalb des Bildbereichs führen dazu, dass die Funktion false zurückgibt und keinen Pixel setzt. Eine Prüfung der Grenzen vor dem Aufruf ist empfehlenswert, wenn die Koordinaten dynamisch berechnet werden.
Palettenbilder vs. True-Color: Bei Palettenbildern (erstellt mit imagecreate()) muss die Farbe zuerst explizit mit imagecolorallocate() reserviert werden; bei True-Color-Bildern kann man auch direkt einen berechneten Ganzzahlwert übergeben.