oracular (3) Imager::TrimColorList.3pm.gz
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.