NAME

Image::Quantize - quantize image data into 256 or fewer colours

SYNOPSIS

    use Image::Quantize;

DESCRIPTION

Image::Quantize offers an interface to a library called libimagequant which reduces the number of colours used by an image to 256 or less. At the moment it can only be used with PNG images.

The reduction in the number of colours, also known as "quantization" or "palettization", reduces the size of the PNG image.

METHODS

new

    Image::Quantize->new

This creates a new Image::Quantize object which can be fed image data.

It may be called with the same options as "set":

    Image::Quantize->new (max_colors => 42);

set

All setters can be accessed like this:

     $quantizer->set (dithering_level => $y);

get

All getters can be accessed like this:

     my $dl = $quantizer->get ('dithering_level');

max_colors

    $quantizer->max_colors ($x)

This sets the maximum possible number of colours which may be used in quantizing image data.

quality

    $quantizer->quality ($min, $max)

This sets the quality to $min and $max.

Get the quality:

    my ($min, $max) = $quantizer->quality ();

Internally this calls `liq_set_quality` and `liq_get_quality`.

dithering_level

    $quantizer->dithering_level ($x)

This overrides the default dithering level. The default can be restored with

default_dithering_level

    $quantizer->default_dithering_level ();

The default dithering depends on the speed chosen. The default speed is 3.

speed

Set the speed:

    $quantizer->speed ($x)

Get the speed:

    my $speed = $quantizer->speed ();

This calls `liq_set_speed`. The default speed is 3, and the value of the speed is an integer from 1 to 10.

min_opacity

    $quantizer->min_opacity ($x)

calls `liq_set_min_opacity`.

min_posterization

    $quantizer->min_posterization ($x)

calls `liq_set_min_posterization`.

quantization_error

    my $qe = $quantizer->quantization_error ()

calls `liq_get_quantization_error`.

output_gamma

    $quantizer->output_gamma ($x)

calls `liq_set_output_gamma`. Called without argument it returns value from `liq_get_output_gamma`, e.g.

     my $gamma = $quantizer->output_gamma ();

quantize

The main routine looks like this:

    my $qpng = $quantizer->quantize ($png);

This handles all of the jive to do with getting memory out of the PNG, ensuring that the image is RGBA using libpng transforms, etc. An alternative interface,

quantize_in_place

    $quantizer->quantize_in_place ($png);

replaces the image data in $png with quantized data.

(unimplemented)

quantize_file

Also

     $quantizer->quantize_file (in => 'in.png', out => 'out.png');

saves having to think about files, PNG objects etc. for the casual user who wants to quantize a bunch of files.

All of the setters can be added as options after `$png`:

    my $qpng = $quantizer->quantize ($png, dithering_level => $y);

This just calls the Perl setting routine. I would like to have it so that these were local only to `$png` but libimagequant doesn't seem to provide `liq_get_dithering_level` - maybe hack that into it.

`liq_image_create_rgba` is handled within $quantizer->quantize ();, not user-visible. `liq_quantize_image` is also handled by the quantize method.

`liq_get_palette` is handled within `quantize` method.

set_log_callback

Logging can be handled like

    sub do_something
    {
           my ($message, $user_data) = @_;
    }
    $quantizer->set_log_callback (\& do_something);

and cancelled with

    $quantizer->set_log_callback ();

Image::Quantize is a base class, and then a subclass Image::Quantize::PNG handles PNG images. No other image types are currently planned. Image::Quantize::PNG is bundled into Image::Quantize, and uses Image::PNG::Libpng objects for reading and writing as shown in the synopsis above.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

The Perl parts of this distribution are Copyright (C) 2014 by Ben Bullock and may be used, distributed, modified under the same terms as Perl itself. All the files in the distribution ending in .c and .h are part of libimagequant except for image-quantize-perl.c and are under the following copyright licence.

The copyright statement for libimagequant is as follows:

Copyright (C) 1989, 1991 by Jef Poskanzer. Copyright (C) 1997, 2000, 2002 by Greg Roelofs; based on an idea by Stefan Schneider. Copyright 2009-2013 by Kornel Lesinski.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty.

cpanm Image::Quantize

perl -MCPAN -e shell
install Image::Quantize