--- name: "Imager::TrimColorList" section: "3pm" platform: "linux" package: "libimager-perl" version: "1.027+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Imager::TrimColorList" --- # Imager::TrimColorList(3pm) represent a list of color ranges for Imager's trim() method. ## 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 \ ## 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.