1Imager::TrimColorList(3U)ser Contributed Perl DocumentatiIomnager::TrimColorList(3)
2
6 Imager::TrimColorList - represent a list of color ranges for Imager's
7 trim() method.
8
10 use Imager::TrimColorList;
11 # empty list
13 my $tcl = Imager::TrimColorList->new;
14 # add an entry in a variety of forms
16 $tcl->add($entry);
17 # add an explicit color object entry
19 $tcl->add_color($c1, $c2);
20 # add an explicit floating color object entry
22 $tcl->add_fcolor($cf1, $cf2);
23 # number of entries
25 my $count = $tcl->count;
26 # fetch an entry
28 my $entry = $tcl->get($index);
29 # fetch all entries
31 my @all = $tcl->all;
32 # make a list and populate it
34 my $tcl = Imager::TrimColorList->new($entry1, $entry2, ...);
35 # dump contents of the list as a string
37 print $tcl->describe;
38
40 An Imager::TrimColorList represents a list of color ranges to supply to
41 the trim() method.
42 Each range can be either an 8-bit color range, ie. Imager::Color
44 objects, or a floating point color range, ie. Imager::Color::Float
45 objects, these can be mixed freely in a single list but each range must
46 be 8-bit or floating point.
47 You can supply an entry in a small variety of forms:
49 • a simple color object of either type, or something convertible to a
51 color object such as a color name such as "red", a hex color such
52 as "#FFF". Any of the forms that Imager::Color supports should
53 work here except for the array form. This becomes a range of only
54 that color.
55 $tcl->add("#000");
57 $tcl->add(Imager::Color->new(0, 0, 0));
58 $tcl->add(Imager::Color::Float->new(0, 0, 0));
59 • an arrayref containing a single color object, or something
61 convertible to a color object. This becomes a range of only that
62 color.
63 $tcl->add([ "#000" ]);
65 $tcl->add([ Imager::Color->new(0, 0, 0) ]);
66 $tcl->add([ Imager::Color::Float->new(0, 0, 0) ]);
67 • an arrayref containing two color objects of the same type, ie. both
69 Imager::Color objects or convertible to Imager::Color objects, or
70 two Imager::Color::Float objects. This becomes a range between
71 those two colors inclusive.
72 $tcl->add([ "#000", "#002" ]);
74 $tcl->add([ Imager::Color->new(0, 0, 0), Imager::Color->new(0, 0, 2) ]);
75 $tcl->add([ Imager::Color::Float->new(0, 0, 0), Imager::Color::Float->new(0, 0, 2/255) ]);
76 • an arrayref containing a color object of either type and a number
78 representing the variance within the color space on either side of
79 the specified color to include.
80 $tcl->add([ "#000", 0.01 ])
82 $tcl->add([ Imager::Color->new(0, 0, 0), 0.01 ]);
83 $tcl->add([ Imager::Color::Float->new(0, 0, 0), 0.01 ]);
84 A range specified this way with an 8-bit color clips at the top and
86 bottom of the sample ranges, so the example 8-bit range above goes
87 from (0, 0, 0) to (2, 2, 2) inclusive, while the floating point
88 range isn't clipped and results in the floating color range (-0.01,
89 -0.01, -0.01) to (0.01, 0.01, 0.01) inclusive.
90
92 new()
93 new($entry1, ...)
94 Class method. Create a new Imager::TrimColorList object and
95 optionally add some color ranges to it.
96 Returns an optionally populated Imager::TrimColorList object, or an
98 empty list (or undef) or failure.
99 add($entry)
101 Add a single range entry. Note that this accepts a single value
102 which can be a color or convertible to a color, or a reference to
103 an array as described above.
104 Returns a true value on success and a false value on failure.
106 add_color($color1, $color2)
108 Add a single 8-bit color range going from the $color1 object to the
109 $color2 object inclusive. Both parameters must be Image::Color
110 objects or an exception is thrown.
111 add_fcolor($fcolor1, $fcolor2)
113 Add a single floating point color range going from the $fcolor1
114 object to the $fcolor2 object inclusive. Both parameters must be
115 Image::Color::Float objects or an exception is thrown.
116 count()
118 Fetch the number of color ranges stored in the object.
119 get($index)
121 Fetch the color range at the given index. This returns a reference
122 to an array containing either two Imager::Color objects or two
123 Imager::Color::Float objects.
124 Returns undef if $index is out of range and does not set
126 "Imager->errstr".
127 all()
129 Fetch all ranges from the object.
130 describe()
132 Return a string describing the color range as code that can create
133 the object.
134 clone()
136 Duplicate the object.
137 auto()
139 Automatically produce a trim color list based on an input image.
140 This is used to implement 'auto' for image trim() and trim_rect()
142 methods.
143 Parameters:
145 • "image" - the image to base the color list on. Required.
147 • "auto" - the mechanism used to produce the color list, one of:
149 • 1 - a "best" mechanism is selected, this is currently the
151 "center" method, but it subject to change.
152 • "center", "centre" - the pixels at the center of each side
154 of the image are used.
155 Default: 1.
157 • "tolerance" - used to control the range of pixel colors to be
159 accepted as part of the color list. Default: 0.01.
160 • "name" - used internally to attribute errors back to the
162 original method. Default: "auto".
163 If any method returns an error you can fetch a diagnostic from
165 "Imager->errstr".
166
168 Imager::TrimColorList objects are properly duplicated when new perl
169 threads are created.
170
172 Tony Cook <tonyc@cpan.org>
173
175 Originally the range handling for this was going to be embedded in the
176 trim() method, but this meant that every called that used color ranges
177 would pay some cost as the range list was checked for names (vs color
178 objects) and non-standard forms such as single colors and the color
179 plus variance.
180 The object allows a simple test for the trim() "colors" parameter that
182 doesn't pay that cost, and still allows a caller to use the explicit
183 convention.
184perl v5.36.0 2022-07-22 Imager::TrimColorList(3)