Imager::TrimColorList3pm

Usage

  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;

Overview

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.