Signatur
Beschreibung
imagetruecolortopalette() wandelt ein Echtfarbenbild (True-Color) in ein Palettenbild um, das maximal num_colors Farben enthält. Dies ist nützlich, wenn das Bild als GIF gespeichert werden soll, da das GIF-Format auf 256 Farben beschränkt ist.
Der Parameter dither steuert, ob beim Reduktionsprozess ein Dithering-Algorithmus (Floyd-Steinberg) angewendet wird. Dithering erzeugt durch das Mischen benachbarter Pixel den visuellen Eindruck von mehr Farben als tatsächlich vorhanden sind, führt aber zu einem etwas körnigeren Bild. Ohne Dithering wirken Farbübergänge härter, das Ergebnis ist jedoch schärfer.
Die Funktion verändert das Bildobjekt direkt (in-place). Nach der Konvertierung stehen nur noch Palettenfunktionen wie imagecolorset() oder imagecolorsforindex() zur Verfügung. Eine Rückkonvertierung zu True-Color ist mit imagepalettetotruecolor() möglich, wobei jedoch Farbinformationen unwiederbringlich verloren gehen können.
Typische Einsatzgebiete sind das Erzeugen speichersparender Palettenbilder, die Vorbereitung für GIF-Export sowie die Reduktion der Farbtiefe für spezielle Ausgabezwecke.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Das GD-Bildobjekt, das konvertiert werden soll. Muss ein Echtfarbenbild sein (z. B. mit imagecreatetruecolor() erstellt). |
|
| $dither Pflicht | bool | Gibt an, ob Dithering verwendet werden soll. true aktiviert den Floyd-Steinberg-Dithering-Algorithmus für weichere Farbübergänge; false deaktiviert ihn für schärfere, aber härtere Übergänge. |
|
| $num_colors Pflicht | int | Die maximale Anzahl der Farben in der resultierenden Palette. Werte zwischen 1 und 256 sind sinnvoll; für GIF-Kompatibilität sollte der Wert maximal 256 betragen. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. wenn $image kein gültiges GD-Bildobjekt ist oder bereits ein Palettenbild ist).Beispiele
Echtfarbenbild in ein 256-Farben-Palettenbild konvertieren und als GIF speichern
<?php
// Echtfarbenbild laden (z. B. ein JPEG)
$image = imagecreatefromjpeg('foto.jpg');
if ($image === false) {
die('Bild konnte nicht geladen werden.');
}
// In Palettenbild mit 256 Farben konvertieren (mit Dithering)
$result = imagetruecolortopalette($image, true, 256);
if ($result) {
// Als GIF speichern (GIF unterstützt nur Palettenbilder)
imagegif($image, 'ausgabe.gif');
echo 'GIF wurde erfolgreich erstellt.';
} else {
echo 'Konvertierung fehlgeschlagen.';
}
imagedestroy($image);
?>Vergleich: Dithering an vs. aus bei 16 Farben
<?php
// Beispielbild laden
$original = imagecreatefromjpeg('foto.jpg');
// Kopie 1: Konvertierung MIT Dithering
$withDither = imagecreatefromjpeg('foto.jpg');
imagetruecolortopalette($withDither, true, 16);
imagepng($withDither, 'mit_dithering.png');
// Kopie 2: Konvertierung OHNE Dithering
$withoutDither = imagecreatefromjpeg('foto.jpg');
imagetruecolortopalette($withoutDither, false, 16);
imagepng($withoutDither, 'ohne_dithering.png');
echo 'Anzahl Farben (mit Dithering): ' . imagecolorstotal($withDither) . PHP_EOL;
echo 'Anzahl Farben (ohne Dithering): ' . imagecolorstotal($withoutDither) . PHP_EOL;
imagedestroy($original);
imagedestroy($withDither);
imagedestroy($withoutDither);
?>// Wichtig · Fallstricke
Irreversibler Datenverlust: Die Konvertierung von True-Color zu Palette ist verlustbehaftet. Farbinformationen, die nicht in die Palette passen, gehen dauerhaft verloren. Arbeite stets mit einer Kopie des Originals, wenn das Original erhalten bleiben soll.
Bereits konvertierte Bilder: Wird die Funktion auf ein Bild angewendet, das bereits ein Palettenbild ist, gibt sie false zurück. Mit imageistruecolor() kann vorher geprüft werden, ob das Bild ein Echtfarbenbild ist.
GIF-Transparenz: Wenn das Bild einen transparenten Hintergrund hat, sollte vor der Konvertierung mit imagecolortransparent() die Transparenzfarbe gesetzt werden, damit sie korrekt im GIF-Format erhalten bleibt.