Signatur
Beschreibung
imagecolorsforindex() ermittelt die RGBA-Farbwerte, die einem gegebenen Farbindex in der Palette eines GD-Bildes zugeordnet sind. Das zurückgegebene Array enthält die Schlüssel red, green, blue und alpha, jeweils als Integer-Werte.
Die Funktion ist besonders nützlich, wenn man mit palettenbasierten Bildern (z. B. GIF oder PNG-8) arbeitet und die tatsächlichen Farbwerte eines Pixels analysieren möchte. Mit imagecolorat() lässt sich zunächst der Farbindex eines Pixels ermitteln, der dann an imagecolorsforindex() übergeben werden kann, um die genauen Farbkomponenten zu erhalten.
Der Alpha-Wert liegt im Bereich 0 (vollständig opak) bis 127 (vollständig transparent) – Achtung: diese Skala ist umgekehrt zum CSS-Standard. Die RGB-Werte liegen jeweils im Bereich 0–255.
Bei True-Color-Bildern enthält der Rückgabewert von imagecolorat() die Farbinformation bereits direkt kodiert; imagecolorsforindex() dekodiert diese Werte korrekt auch für True-Color-Bilder.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Ein gültiges GD-Bildobjekt, das z. B. durch imagecreatefrompng(), imagecreatefromgif() oder imagecreatetruecolor() erzeugt wurde. |
|
| $color Pflicht | int | Der Farbindex, dessen Farbwerte ermittelt werden sollen. Dieser wird typischerweise durch imagecolorat() für einen bestimmten Pixel ermittelt. |
Rückgabewert
red, green, blue (je 0–255) und alpha (0–127). Wird ein ungültiger Farbindex übergeben, wird ein Fehler ausgelöst.Beispiele
Farbwerte eines Pixels aus einem PNG-Bild auslesen
<?php
// Ein bestehendes PNG-Bild laden
$image = imagecreatefrompng('beispiel.png');
// Den Farbindex des Pixels an Position (10, 20) ermitteln
$colorIndex = imagecolorat($image, 10, 20);
// Die tatsächlichen RGBA-Werte aus dem Index ermitteln
$colorValues = imagecolorsforindex($image, $colorIndex);
echo "Rot: " . $colorValues['red'] . PHP_EOL;
echo "Grün: " . $colorValues['green'] . PHP_EOL;
echo "Blau: " . $colorValues['blue'] . PHP_EOL;
echo "Alpha: " . $colorValues['alpha'] . PHP_EOL;
imagedestroy($image);Alle Palettenfarben eines GIF-Bildes ausgeben
<?php
// Ein GIF-Bild laden (palettenbasiert)
$image = imagecreatefromgif('animation.gif');
// Anzahl der Farben in der Palette ermitteln
$anzahlFarben = imagecolorstotal($image);
echo "Palette enthält {$anzahlFarben} Farbe(n):" . PHP_EOL;
for ($i = 0; $i < $anzahlFarben; $i++) {
$farbe = imagecolorsforindex($image, $i);
echo sprintf(
"Index %3d: R=%3d G=%3d B=%3d A=%3d%s",
$i,
$farbe['red'],
$farbe['green'],
$farbe['blue'],
$farbe['alpha'],
PHP_EOL
);
}
imagedestroy($image);// Wichtig · Fallstricke
Alpha-Skala beachten: Der Alpha-Wert verwendet eine PHP-eigene Skala von 0 (vollständig opak) bis 127 (vollständig transparent). Dies ist das Gegenteil der gängigen CSS/HTML-Konvention (0 = transparent, 1 = opak). Beim Vergleich mit anderen Systemen muss dieser Unterschied berücksichtigt werden.
Ungültige Indizes: Wird ein Farbindex übergeben, der außerhalb des gültigen Bereichs für die Palette des Bildes liegt, gibt die Funktion einen Fehler (E_WARNING) aus. Der Gültigkeitsbereich kann mit imagecolorstotal() geprüft werden.
Ab PHP 8.0 ist der erste Parameter vom Typ GdImage statt der früher verwendeten Ressource.