Signatur
Beschreibung
imagecolorclosesthwb() durchsucht die Farb-Palette eines GD-Bildes und liefert den Index der Farbe zurück, die dem angegebenen RGB-Tripel im HWB-Farbraum (Hue = Farbton, White = Weißanteil, Black = Schwarzanteil) am nächsten liegt. Im Gegensatz zu imagecolorclosest(), das den euklidischen Abstand im RGB-Raum nutzt, arbeitet diese Funktion mit einem Abstandsmaß, das dem menschlichen Farbempfinden besser entspricht.
Die Funktion ist besonders nützlich, wenn man mit Palette-Bildern (Typ GD/PNG mit maximal 256 Farben) arbeitet und eine möglichst wahrnehmungsgetreue Annäherung an eine Wunschfarbe benötigt. Sie eignet sich gut zum Reduzieren von Farbtiefen oder zum Mappen von Farben auf eine vorhandene, beschränkte Palette.
Beachte, dass imagecolorclosesthwb() ausschließlich auf Palette-Bildern sinnvoll ist. Auf Echtfarb-Bildern (Truecolor) liefert sie stets -1, da diese keine eingeschränkte Palette besitzen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Ein GdImage-Objekt, wie es von Funktionen wie imagecreate() oder imagecreatefromgif() zurückgegeben wird. |
|
| $red Pflicht | int | Der Rotanteil der gesuchten Farbe als Ganzzahl im Bereich von 0 bis 255. |
|
| $green Pflicht | int | Der Grünanteil der gesuchten Farbe als Ganzzahl im Bereich von 0 bis 255. |
|
| $blue Pflicht | int | Der Blauanteil der gesuchten Farbe als Ganzzahl im Bereich von 0 bis 255. |
Rückgabewert
-1 zurückgegeben.Beispiele
Nächste Palettenfarbe für ein gegebenes RGB per HWB suchen
<?php
// Palette-Bild erstellen (8-Bit, max. 256 Farben)
$image = imagecreate(200, 100);
// Einige Farben in der Palette registrieren
$rot = imagecolorallocate($image, 255, 0, 0);
$gruen = imagecolorallocate($image, 0, 255, 0);
$blau = imagecolorallocate($image, 0, 0, 255);
$gelb = imagecolorallocate($image, 255, 255, 0);
// Welche Palettenfarbe liegt Orange (255, 165, 0) im HWB-Sinne am nächsten?
$index = imagecolorclosesthwb($image, 255, 165, 0);
echo "Nächster Palettenindex: " . $index . PHP_EOL;
// Farbe des gefundenen Index ausgeben
$farbe = imagecolorsforindex($image, $index);
echo "Gefundene Farbe: R={$farbe['red']} G={$farbe['green']} B={$farbe['blue']}" . PHP_EOL;
imagedestroy($image);
?>Farben einer Vorlage auf reduzierte Palette mappen
<?php
// Ursprüngliches Truecolor-Bild laden
$tc = imagecreatefrompng('foto.png');
// Palette-Bild mit 16 Farben erstellen
$palette = imagecreate(imagesx($tc), imagesy($tc));
imagecopy($palette, $tc, 0, 0, 0, 0, imagesx($tc), imagesy($tc));
truecolortopalette($palette, true, 16);
// Gesuchte Farbe: ein gedämpftes Lila
$index = imagecolorclosesthwb($palette, 180, 100, 200);
$gefunden = imagecolorsforindex($palette, $index);
echo sprintf(
"Nächste Palettenfarbe: R=%d G=%d B=%d (Index %d)",
$gefunden['red'], $gefunden['green'], $gefunden['blue'], $index
) . PHP_EOL;
imagedestroy($tc);
imagedestroy($palette);
?>// Wichtig · Fallstricke
Truecolor-Bilder: Auf Truecolor-Bildern (erstellt mit imagecreatetruecolor()) gibt die Funktion stets -1 zurück, da diese keine endliche Palette besitzen. In diesem Fall sollte stattdessen direkt mit imagecolorat() und imagecolorsforindex() gearbeitet werden.
Leere Palette: Wenn dem Bild noch keine Farben mit imagecolorallocate() zugewiesen wurden, liefert die Funktion ebenfalls -1.
Der HWB-Abstand spiegelt die menschliche Wahrnehmung von Farbähnlichkeit besser wider als der euklidische Abstand im RGB-Raum; bei sichtbarer Qualität auf reduzierten Paletten ist imagecolorclosesthwb() daher oft imagecolorclosest() vorzuziehen.