=encoding UTF-8

=head1 NAME

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

=head1 SYNOPSIS

    use Image::Quantize;

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

=head1 METHODS

=head2 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 L</set>:

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

=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');

=head2 max_colors

    $quantizer->max_colors ($x)

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

=head2 quality

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

This sets the quality to C<$min> and C<$max>.

Get the quality:

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

Internally this calls `liq_set_quality` and `liq_get_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

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.

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

=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head1 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 F<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.
