Convert an image to indexed color mode with PHP

Indexed color is a technique to display an image with only a few specific colors. With indexed color mode, you can reduce the image file size or achieve amazing image effects.

In the GD library of php, there is a function called imagetruecolortopalette that could converts a truecolor image to a palette image. But using this function, you can’t decide which colors that the output image will contain, instead, you can only set the maximum number of colors that will be retained in the output image. In addition, there is no dither amount control in the this function.

I write the GDIndexedColorConverter library with PHP to achieve advanced indexed color conversion. To archieve image dithering effect, GDIndexedColorConverter uses Floyd–Steinberg dithering algorithm to apply error diffusion of each pixel onto its neighboring pixels.


GDIndexedColorConverter uses some functions of the GD extension, you need to enable GD extension in the PHP configuration file (php.ini).

GDIndexedColorConverter provide a function named convertToIndexedColor to convert an image into indexed color mode, it accepts three parameters(listed below), and return a new image resource of indexed color mode.

  • im (imageresource) The image resource created by the functions of GD library.
  • palette (array) The palette which contains all the specific colors that the indexed-color-mode image will use. This parameter is an array which stores all the colors, each color is an indexed array that consists of red, green and blue color channel values.
  • dither (float) How much the Floyd–Steinberg dithering algorithm will affect the image. This parameter is optional, its default value is 0.75, and the value must be between 0 and 1.

Code example:

// create an image
$image = imagecreatefromjpeg('example.jpg');

// create a gd indexed color converter
$converter = new GDIndexedColorConverter();

// the color palette
$palette = array(
    array(0, 0, 0),
    array(255, 255, 255),
    array(255, 0, 0),
    array(0, 255, 0),
    array(0, 0, 255)

// convert the image to indexed color mode
$new_image = $converter->convertToIndexedColor($image, $palette, 0.8);

// save the new image
imagepng($new_image, 'example_indexed_color.png', 0);


Applying different dither values on indexed-color images, you can get various image effects. For instance, the picture below shows three output images with different dither values(0.2, 0.4, 0.8) and five colors(white, black, red, green and blue). The original image that I use in this example is created by @sage_solar, the image is under Creative Commons License.


To check more information about GDIndexedColorConverter, visit


One thought on “Convert an image to indexed color mode with PHP

  1. De Urn

    It’s great to convert my images to a CGA color profile, to show them on my CGA monitor.
    It takes a lot of time to convert a photo to 4 colors, but the results are great.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s