.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::TrimColorList 3pm"
.TH Imager::TrimColorList 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::TrimColorList \- represent a list of color ranges for Imager's trim() method.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  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;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An Imager::TrimColorList represents a list of color ranges to supply
to the \fBtrim()\fR method.
.PP
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.
.PP
You can supply an entry in a small variety of forms:
.IP \(bu 4
a simple color object of either type, or something convertible to a
color object such as a color name such as \f(CW"red"\fR, a hex color such
as \f(CW"#FFF"\fR.  Any of the forms that Imager::Color supports should
work here \fIexcept\fR for the array form.  This becomes a range of only
that color.
.Sp
.Vb 3
\&  $tcl\->add("#000");
\&  $tcl\->add(Imager::Color\->new(0, 0, 0));
\&  $tcl\->add(Imager::Color::Float\->new(0, 0, 0));
.Ve
.IP \(bu 4
an arrayref containing a single color object, or something convertible
to a color object.  This becomes a range of only that color.
.Sp
.Vb 3
\&  $tcl\->add([ "#000" ]);
\&  $tcl\->add([ Imager::Color\->new(0, 0, 0) ]);
\&  $tcl\->add([ Imager::Color::Float\->new(0, 0, 0) ]);
.Ve
.IP \(bu 4
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.
.Sp
.Vb 3
\&  $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) ]);
.Ve
.IP \(bu 4
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.
.Sp
.Vb 3
\&  $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 ]);
.Ve
.Sp
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.
.SH METHODS
.IX Header "METHODS"
.IP \fBnew()\fR 4
.IX Item "new()"
.PD 0
.IP "new($entry1, ...)" 4
.IX Item "new($entry1, ...)"
.PD
Class method.  Create a new Imager::TrimColorList object and
optionally add some color ranges to it.
.Sp
Returns an optionally populated Imager::TrimColorList object, or an
empty list (or undef) or failure.
.IP add($entry) 4
.IX Item "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.
.Sp
Returns a true value on success and a false value on failure.
.ie n .IP "add_color($color1, $color2)" 4
.el .IP "add_color($color1, \f(CW$color2\fR)" 4
.IX Item "add_color($color1, $color2)"
Add a single 8\-bit color range going from the \f(CW$color1\fR object to the
\&\f(CW$color2\fR object inclusive.  Both parameters must be Image::Color
objects or an exception is thrown.
.ie n .IP "add_fcolor($fcolor1, $fcolor2)" 4
.el .IP "add_fcolor($fcolor1, \f(CW$fcolor2\fR)" 4
.IX Item "add_fcolor($fcolor1, $fcolor2)"
Add a single floating point color range going from the \f(CW$fcolor1\fR
object to the \f(CW$fcolor2\fR object inclusive.  Both parameters must be
Image::Color::Float objects or an exception is thrown.
.IP \fBcount()\fR 4
.IX Item "count()"
Fetch the number of color ranges stored in the object.
.IP get($index) 4
.IX Item "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.
.Sp
Returns undef if \f(CW$index\fR is out of range and does not set \f(CW\*(C`Imager\->errstr\*(C'\fR.
.IP \fBall()\fR 4
.IX Item "all()"
Fetch all ranges from the object.
.IP \fBdescribe()\fR 4
.IX Item "describe()"
Return a string describing the color range as code that can create the
object.
.IP \fBclone()\fR 4
.IX Item "clone()"
Duplicate the object.
.IP \fBauto()\fR 4
.IX Item "auto()"
Automatically produce a trim color list based on an input image.
.Sp
This is used to implement 'auto' for image \fBtrim()\fR and \fBtrim_rect()\fR
methods.
.Sp
Parameters:
.RS 4
.IP \(bu 4
\&\f(CW\*(C`image\*(C'\fR \- the image to base the color list on.  Required.
.IP \(bu 4
\&\f(CW\*(C`auto\*(C'\fR \- the mechanism used to produce the color list, one of:
.RS 4
.IP \(bu 4
\&\f(CW1\fR \- a "best" mechanism is selected, this is currently the \f(CW\*(C`center\*(C'\fR
method, but it subject to change.
.IP \(bu 4
\&\f(CW\*(C`center\*(C'\fR, \f(CW\*(C`centre\*(C'\fR \- the pixels at the center of each side of the
image are used.
.RE
.RS 4
.Sp
Default: \f(CW1\fR.
.RE
.IP \(bu 4
\&\f(CW\*(C`tolerance\*(C'\fR \- used to control the range of pixel colors to be
accepted as part of the color list.  Default: 0.01.
.IP \(bu 4
\&\f(CW\*(C`name\*(C'\fR \- used internally to attribute errors back to the original
method.  Default: \f(CW\*(C`auto\*(C'\fR.
.RE
.RS 4
.RE
.PP
If any method returns an error you can fetch a diagnostic from \f(CW\*(C`Imager\->errstr\*(C'\fR.
.SH THREADS
.IX Header "THREADS"
Imager::TrimColorList objects are properly duplicated when new perl
threads are created.
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>
.SH HISTORY
.IX Header "HISTORY"
Originally the range handling for this was going to be embedded in the
\&\fBtrim()\fR 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.
.PP
The object allows a simple test for the \fBtrim()\fR \f(CW\*(C`colors\*(C'\fR parameter
that doesn't pay that cost, and still allows a caller to use the
explicit convention.