NAME

       Imager::TrimColorList - represent a list of color ranges for Imager's trim() method.

SYNOPSIS

         use Imager::TrimColorList;

         # empty list
         my $tcl = Imager::TrimColorList->new;

         # add an entry in a variety of forms
         $tcl->add($entry);

         # add an explicit color object entry
         $tcl->add_color($c1, $c2);

         # add an explicit floating color object entry
         $tcl->add_fcolor($cf1, $cf2);

         # number of entries
         my $count = $tcl->count;

         # fetch an entry
         my $entry = $tcl->get($index);

         # fetch all entries
         my @all = $tcl->all;

         # make a list and populate it
         my $tcl = Imager::TrimColorList->new($entry1, $entry2, ...);

         # dump contents of the list as a string
         print $tcl->describe;

DESCRIPTION

       An Imager::TrimColorList represents a list of color ranges to supply to the trim() method.

       Each range can be either an 8-bit color range, ie. Imager::Color objects, or a floating
       point color range, ie. Imager::Color::Float objects, these can be mixed freely in a single
       list but each range must be 8-bit or floating point.

       You can supply an entry in a small variety of forms:

       •   a simple color object of either type, or something convertible to a color object such
           as a color name such as "red", a hex color such as "#FFF".  Any of the forms that
           Imager::Color supports should work here except for the array form.  This becomes a
           range of only that color.

             $tcl->add("#000");
             $tcl->add(Imager::Color->new(0, 0, 0));
             $tcl->add(Imager::Color::Float->new(0, 0, 0));

       •   an arrayref containing a single color object, or something convertible to a color
           object.  This becomes a range of only that color.

             $tcl->add([ "#000" ]);
             $tcl->add([ Imager::Color->new(0, 0, 0) ]);
             $tcl->add([ Imager::Color::Float->new(0, 0, 0) ]);

       •   an arrayref containing two color objects of the same type, ie. both Imager::Color
           objects or convertible to Imager::Color objects, or two Imager::Color::Float objects.
           This becomes a range between those two colors inclusive.

             $tcl->add([ "#000", "#002" ]);
             $tcl->add([ Imager::Color->new(0, 0, 0), Imager::Color->new(0, 0, 2) ]);
             $tcl->add([ Imager::Color::Float->new(0, 0, 0), Imager::Color::Float->new(0, 0, 2/255) ]);

       •   an arrayref containing a color object of either type and a number representing the
           variance within the color space on either side of the specified color to include.

             $tcl->add([ "#000", 0.01 ])
             $tcl->add([ Imager::Color->new(0, 0, 0), 0.01 ]);
             $tcl->add([ Imager::Color::Float->new(0, 0, 0), 0.01 ]);

           A range specified this way with an 8-bit color clips at the top and bottom of the
           sample ranges, so the example 8-bit range above goes from (0, 0, 0) to (2, 2, 2)
           inclusive, while the floating point range isn't clipped and results in the floating
           color range (-0.01, -0.01, -0.01) to (0.01, 0.01, 0.01) inclusive.

METHODS

       new()
       new($entry1, ...)
           Class method.  Create a new Imager::TrimColorList object and optionally add some color
           ranges to it.

           Returns an optionally populated Imager::TrimColorList object, or an empty list (or
           undef) or failure.

       add($entry)
           Add a single range entry.  Note that this accepts a single value which can be a color
           or convertible to a color, or a reference to an array as described above.

           Returns a true value on success and a false value on failure.

       add_color($color1, $color2)
           Add a single 8-bit color range going from the $color1 object to the $color2 object
           inclusive.  Both parameters must be Image::Color objects or an exception is thrown.

       add_fcolor($fcolor1, $fcolor2)
           Add a single floating point color range going from the $fcolor1 object to the $fcolor2
           object inclusive.  Both parameters must be Image::Color::Float objects or an exception
           is thrown.

       count()
           Fetch the number of color ranges stored in the object.

       get($index)
           Fetch the color range at the given index.  This returns a reference to an array
           containing either two Imager::Color objects or two Imager::Color::Float objects.

           Returns undef if $index is out of range and does not set "Imager->errstr".

       all()
           Fetch all ranges from the object.

       describe()
           Return a string describing the color range as code that can create the object.

       clone()
           Duplicate the object.

       auto()
           Automatically produce a trim color list based on an input image.

           This is used to implement 'auto' for image trim() and trim_rect() methods.

           Parameters:

           •   "image" - the image to base the color list on.  Required.

           •   "auto" - the mechanism used to produce the color list, one of:

               •   1 - a "best" mechanism is selected, this is currently the "center" method, but
                   it subject to change.

               •   "center", "centre" - the pixels at the center of each side of the image are
                   used.

               Default: 1.

           •   "tolerance" - used to control the range of pixel colors to be accepted as part of
               the color list.  Default: 0.01.

           •   "name" - used internally to attribute errors back to the original method.
               Default: "auto".

       If any method returns an error you can fetch a diagnostic from "Imager->errstr".

THREADS

       Imager::TrimColorList objects are properly duplicated when new perl threads are created.

AUTHOR

       Tony Cook <tonyc@cpan.org>

HISTORY

       Originally the range handling for this was going to be embedded in the trim() method, but
       this meant that every called that used color ranges would pay some cost as the range list
       was checked for names (vs color objects) and non-standard forms such as single colors and
       the color plus variance.

       The object allows a simple test for the trim() "colors" parameter that doesn't pay that
       cost, and still allows a caller to use the explicit convention.