Signatur
Beschreibung
imagecolorat() liest den Farbwert eines einzelnen Pixels an der angegebenen Position im Bild. Bei Palette-basierten Bildern (z. B. GIF) wird der Farbindex zurückgegeben, der anschließend mit imagecolorsforindex() in RGBA-Komponenten aufgelöst werden kann. Bei Truecolor-Bildern (z. B. PNG oder JPEG) enthält der Rückgabewert die Farb- und Alphainformation in einem einzigen Integer, der bitweise ausgewertet werden muss.
Der Rückgabewert für Truecolor-Bilder ist wie folgt kodiert: (alpha << 24) | (red << 16) | (green << 8) | blue. Der Alphakanal-Anteil reicht von 0 (vollständig opak) bis 127 (vollständig transparent). Rot-, Grün- und Blauanteile liegen jeweils zwischen 0 und 255.
Die Funktion eignet sich besonders für Bildanalysen, z. B. um Farbverteilungen zu berechnen, bestimmte Farbbereiche zu detektieren oder individuelle Pixel auszulesen, bevor sie manipuliert werden. Sie ist ein wichtiges Werkzeug für pixelbasierte Bildverarbeitungsalgorithmen.
Koordinaten außerhalb der Bildgrenzen führen zu einer Warnung und zum Rückgabewert false. Es ist daher ratsam, die Koordinaten vorher gegen die Bildmaße zu prüfen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Ein GD-Bildobjekt, das z. B. von imagecreatetruecolor(), imagecreatefrompng() oder ähnlichen Funktionen erzeugt wurde. |
|
| $x Pflicht | int | Die horizontale Koordinate (Spalte) des Pixels, beginnend bei 0 (links). | |
| $y Pflicht | int | Die vertikale Koordinate (Zeile) des Pixels, beginnend bei 0 (oben). |
Rückgabewert
false zurückgegeben und eine Warnung ausgegeben.Beispiele
Farbkomponenten eines Truecolor-Pixels auslesen
<?php
// Truecolor-Bild erstellen und Pixel einfärben
$image = imagecreatetruecolor(100, 100);
$farbe = imagecolorallocate($image, 200, 100, 50);
imagesetpixel($image, 10, 10, $farbe);
// Farbwert des Pixels auslesen
$wert = imagecolorat($image, 10, 10);
// Einzelne Kanäle aus dem Integer extrahieren
$alpha = ($wert >> 24) & 0x7F;
$rot = ($wert >> 16) & 0xFF;
$gruen = ($wert >> 8) & 0xFF;
$blau = $wert & 0xFF;
echo "Alpha: $alpha, Rot: $rot, Grün: $gruen, Blau: $blau\n";
imagedestroy($image);Farbindex eines Palette-Bildes auflösen
<?php
// Palette-Bild (256 Farben) erstellen
$image = imagecreate(100, 100);
$hintergrund = imagecolorallocate($image, 255, 255, 0); // Gelb als Hintergrund
// Index des Pixels auslesen
$index = imagecolorat($image, 5, 5);
// Index in RGBA-Komponenten auflösen
$farben = imagecolorsforindex($image, $index);
echo "Rot: {$farben['red']}, Grün: {$farben['green']}, Blau: {$farben['blue']}\n";
imagedestroy($image);Koordinaten vor dem Auslesen prüfen
<?php
$image = imagecreatefrompng('beispiel.png');
$x = 50;
$y = 30;
if ($x >= 0 && $x < imagesx($image) && $y >= 0 && $y < imagesy($image)) {
$wert = imagecolorat($image, $x, $y);
$rot = ($wert >> 16) & 0xFF;
$gruen = ($wert >> 8) & 0xFF;
$blau = $wert & 0xFF;
echo "Pixelfarbe: rgb($rot, $gruen, $blau)\n";
} else {
echo "Koordinaten liegen außerhalb des Bildes.\n";
}
imagedestroy($image);// Wichtig · Fallstricke
Truecolor vs. Palette: Das Verhalten von imagecolorat() unterscheidet sich je nach Bildtyp grundlegend. Mit imageistruecolor() lässt sich prüfen, ob ein Bild im Truecolor-Modus vorliegt.
Alpha-Kodierung: Der Alphawert in Truecolor-Bildern ist nicht der übliche 0–255-Bereich, sondern 0–127, wobei 0 vollständig opak und 127 vollständig transparent bedeutet.
Koordinatenprüfung: Koordinaten außerhalb des Bildes verursachen eine PHP-Warnung und geben false zurück. Koordinaten sollten stets mit imagesx() und imagesy() validiert werden, bevor imagecolorat() aufgerufen wird.
Ab PHP 8.0 ist der Parameter $image vom Typ GdImage statt der früher verwendeten Ressource.