Imager...lorList(3pm)

💖 Imager::TrimColorList — the perl manpage, but make it cute 💖

okay bestie so this is Imager::TrimColorList, from the perl manual pages (that's the 3pm vibe iykyk), and it's literally the color-range list you hand to Imager's trim() method. yes. that one. let's go ✨

---

🌸 NAME 🌸

Imager::TrimColorList — it represents a list of color ranges for Imager's trim() method. that's the whole job. and it slays at it 💅

---

✨ SYNOPSIS ✨

here's the whole group chat in code form, no cap:

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 🎀

so an Imager::TrimColorList is literally just a list of color ranges that you pass to the trim() method. that's it, that's the vibe 🫶

each range is either an 8-bit color range (ie. Imager::Color objects) or a floating point color range (ie. Imager::Color::Float objects). you can mix them freely in one list — no gatekeeping here — but each individual range has to be one or the other. pick a lane for each range, bestie 💀

and you can feed an entry in a bunch of forms, so let's go through them one by one:

• a simple color object of either type, or honestly anything that converts to a color object — like a color name such as "red", or a hex color such as "#FFF". pretty much any form Imager::Color supports should work here, except the array form. this becomes a range of only that one color. iconic ✨

$tcl->add("#000");
$tcl->add(Imager::Color->new(0, 0, 0));
$tcl->add(Imager::Color::Float->new(0, 0, 0));

• an arrayref holding a single color object, or something convertible to one. again, that's a range of just that color. simple, clean, ate 💅

$tcl->add([ "#000" ]);
$tcl->add([ Imager::Color->new(0, 0, 0) ]);
$tcl->add([ Imager::Color::Float->new(0, 0, 0) ]);

• an arrayref with two color objects of the same type — like both Imager::Color objects (or things 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 with a color object of either type plus a number — the number is the variance within the color space, on either side of the color you gave, that gets included. so you're like "this color and also its little friends" 🙈

$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 ]);

⚠️ okay important, listen: a range specified this way with an 8-bit color clips at the top and bottom of the sample ranges. so that 8-bit example up there goes from (0, 0, 0) to (2, 2, 2) inclusive. meanwhile the floating point range isn't clipped and gives you the floating color range (-0.01, -0.01, -0.01) to (0.01, 0.01, 0.01) inclusive. not me warning you about clipping, but here we are 😭

---

💜 METHODS 💜

🦋 new()

🦋 new($entry1, ...)

class method, periodt. it creates a shiny new Imager::TrimColorList object and optionally adds some color ranges to it while it's at it.

it returns an optionally populated Imager::TrimColorList object… or an empty list (or undef) on failure. so like, check your return values bestie 💀

---

⭐ add($entry)

adds a single range entry. heads up though — this takes one value, and that value can be a color, something convertible to a color, or a reference to an array as described up in the description.

returns a true value on success and a false value on failure. slay 🫶

---

🔥 add_color($color1, $color2)

adds one 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 gets thrown. yes, Image::Color — that's exactly how it's written in the original, i'm not touching it, don't come for me 👑 (just, yk, you probably mean Imager::Color. iykyk. but it says what it says 💅)

---

🌈 add_fcolor($fcolor1, $fcolor2)

adds one 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. same deal as above, literally written like that in the original 🎀

---

🍓 count()

fetches the number of color ranges stored in the object. that's it. math era ✨

---

🧚 get($index)

fetches the color range at the given index. it 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 it does not set "Imager->errstr". so don't go looking for the error string, it's not there 🙈

---

💖 all()

fetches all the ranges from the object. the whole squad. 🫶

---

🌸 describe()

returns a string describing the color range as code that can create the object. it's giving self-documenting 🎀

---

👑 clone()

duplicates the object. two of them. twins. 💅

---

💀 auto()

automatically produces a trim color list based on an input image. main character energy fr fr 🔥

this is what implements 'auto' for the image trim() and trim_rect() methods.

parameters:

• "image" — the image to base the color list on. required. no image, no list, no cap.
• "auto" — the mechanism used to produce the color list, one of:
  • 1 — a "best" mechanism gets selected. it's currently the "center" method, but it's subject to change. so don't get too attached 😭
  • "center", "centre" — the pixels at the center of each side of the image get used. (and yes, both spellings, we're international 🌍)

default: 1.

• "tolerance" — controls the range of pixel colors that get accepted as part of the color list. default: 0.01.
• "name" — used internally to attribute errors back to the original method. default: "auto".

---

💜 oh and real quick: 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. thread-safe queen behavior, we love to see it 🌈

---

✍️ AUTHOR ✍️

Tony Cook <tonyc@cpan.org>

---

📜 HISTORY 📜

originally, the range handling for all this was gonna be embedded right in the trim() method — but that meant every caller that used color ranges would pay a cost. like, every time. because the range list had to be checked for names (vs color objects) and for non-standard forms like single colors and the color-plus-variance situation. a whole vibe tax 💀

so instead, the object lets trim()'s "colors" parameter be a simple test that doesn't pay that cost — and callers can still use the explicit convention if they want. best of both worlds, periodt ✨

---

okay that's the whole page bestie, go trim some images and be iconic 💅🦋💖

— xoxo, your unix bestie · perl v5.42.3 · dated 2026-08-19 · part of the Imager...lorList(3pm) manual page 🎀