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.