=encoding UTF-8

=head1 NAME

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

=head1 SYNOPSIS

    use Image::Quantize;

=head1 DESCRIPTION

Image::Quantize is an interface to the C library "libimagequant".

=head1 METHODS

This is an XS module which uses [libimagequant](http://pngquant.org/lib/) to quantize PNG and other images.

All of the PNG handling is done by Image::PNG::Libpng rather than by the code from pngquant, so we just use libimagequant to handle quantization. Because it is not PNG specific, we just call it Image::Quantize and then a subclass Image::Quantize::PNG handles the PNG stuff.

=head2 new

    Image::Quantize->new

corresponds to `liq_attr_create`. Arguments include

* max_colors
* speed
* dithering_level
* quality
* min_opacity
* min_posterization

which correspond to the setters described below.

DESTROY calls `liq_attr_destroy`.

=head2 set

All setters can be accessed like this:

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

=head2 get

All getters can be accessed like this:

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

The above is Perl which accesses the following XS mirrors of libimagequant. I copy the names but `s/^liq_[gs]et_//` and use context to imply set or get.

=head2 max_colors

    $quantizer->max_colors ($x)

calls `liq_set_max_colors`.

=head2 quality

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

calls `liq_set_quality`.

=head2 dithering_level

    $quantizer->dithering_level ($x)

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

=head2 default_dithering_level

    $quantizer->default_dithering_level ();

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

=head2 speed

    $quantizer->speed ($x)

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

=head2 min_opacity

    $quantizer->min_opacity ($x)

calls `liq_set_min_opacity`.

=head2 min_posterization

    $quantizer->min_posterization ($x)

calls `liq_set_min_posterization`.

=head2 quantization_error

    my $qe = $quantizer->quantization_error ()

calls `liq_get_quantization_error`.

=head2 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 ();

=head2 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,

=head2 quantize_in_place

    $quantizer->quantize_in_place ($png);

replaces the image data in $png with quantized data.

(unimplemented)

=head2 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.

=head2 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.

