imagecolorset — Funktion · PHP-Referenz

Signatur

imagecolorset(GdImage $image, int $index, int $red, int $green, int $blue, int $alpha = 0): bool

Beschreibung

imagecolorset() ermöglicht es, die Farbe an einem bestimmten Palettenindex eines Palettenbildes (z. B. GIF oder PNG-8) zu überschreiben. Alle Pixel, die auf diesen Index verweisen, erhalten dadurch sofort die neue Farbe – ohne die Pixeldaten selbst anfassen zu müssen.

Diese Funktion ist besonders effizient, wenn man eine einzelne Farbe eines Palettenbildes global ändern möchte, etwa um den Hintergrund oder eine bestimmte Markierungsfarbe auszutauschen. Der gewünschte Index kann vorher mit imagecolorexact() oder imagecolorat() ermittelt werden.

Wichtig: imagecolorset() funktioniert ausschließlich mit Palettenbildern (Bilder mit bis zu 256 Farben). Bei True-Color-Bildern hat die Funktion keine Wirkung. Mit imageistruecolor() lässt sich prüfen, ob ein Bild ein True-Color-Bild ist. Der optionale alpha-Parameter erlaubt es, zusätzlich einen Transparenzwert (0 = vollständig opak, 127 = vollständig transparent) zu setzen.

Parameter

Name	Typ	Default	Beschreibung
$image Pflicht	GdImage		Das GD-Bildobjekt, auf das die Operation angewendet wird. Muss ein Palettenbild sein.
$index Pflicht	int		Der Index in der Farbpalette (0–255), dessen Farbe geändert werden soll.
$red Pflicht	int		Rotwert der neuen Farbe (0–255).
$green Pflicht	int		Grünwert der neuen Farbe (0–255).
$blue Pflicht	int		Blauwert der neuen Farbe (0–255).
$alpha	int	0	Optionaler Alphawert (0 = vollständig opak, 127 = vollständig transparent).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. wenn das Bild ein True-Color-Bild ist oder der Index außerhalb des gültigen Bereichs liegt).

Beispiele

Hintergrundfarbe eines GIF-Bildes ersetzen

<?php
// GIF (Palettenbild) laden
$image = imagecreatefromgif('banner.gif');

// Index der weißen Hintergrundfarbe ermitteln
$index = imagecolorexact($image, 255, 255, 255);

if ($index !== -1) {
    // Weiß durch Hellblau ersetzen
    imagecolorset($image, $index, 173, 216, 230);
    echo "Farbe erfolgreich ersetzt.";
} else {
    echo "Farbe nicht in der Palette gefunden.";
}

// Ergebnis speichern
imagegif($image, 'banner_neu.gif');
imagedestroy($image);
?>

Farbe erfolgreich ersetzt.

Farbe an einem bestimmten Pixel ändern (über Pixelindex)

<?php
// Palettenbild erstellen
$image = imagecreate(100, 100);

// Farben hinzufügen
$hintergrund = imagecolorallocate($image, 255, 0, 0);   // Rot (Index 0)
$vordergrund = imagecolorallocate($image, 0, 0, 255);   // Blau (Index 1)

// Einen Kreis zeichnen
imagefilledellipse($image, 50, 50, 60, 60, $vordergrund);

// Rot (Index 0) durch Grün ersetzen
imagecolorset($image, 0, 0, 255, 0);

// Bild ausgeben
header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);
?>

// Wichtig · Fallstricke

Achtung: imagecolorset() wirkt nur bei Palettenbildern (erstellt mit imagecreate() oder geladen aus GIF/PNG-8-Dateien). Bei True-Color-Bildern (imagecreatetruecolor()) hat die Funktion keine Wirkung und gibt false zurück. Prüfe den Bildtyp vorab mit imageistruecolor().

Da alle Pixel, die auf den betreffenden Palettenindex verweisen, sofort die neue Farbe erhalten, können unerwartete Farbänderungen im gesamten Bild auftreten, wenn der Index für mehrere visuelle Bereiche genutzt wird. Eine sorgfältige Analyse der Palette mit imagecolorsforindex() ist empfehlenswert.

Siehe auch

imagecolorat imagecolorexact imagecolorallocate imagecolorsforindex imageistruecolor imagecolortransparent