Image::Imlib2(3pm)

📦

version 2.03 · 5 versions

2.03 · debian trixie, ubuntu resolute (latest)
2.03 · ubuntu stonking
2.03 · ubuntu jammy
2.03 · ubuntu noble
2.03 · debian bookworm

✨ Image::Imlib2 ✨

okay bestie, pull up a chair 🫶 this is Image::Imlib2, part of the User Contributed Perl Documentation. It's the Perl bestie of the Imlib2 image library and she is so capable.

🌸 NAME 🌸

Image::Imlib2 — the interface to the Imlib2 image library, no cap 💅

🎀 SYNOPSIS 🎀

use Image::Imlib2;

# create a new image
my $image = Image::Imlib2->new(200, 200);

# or load an image
$image = Image::Imlib2->load("foo.png");

# Enable the alpha channel support
$image->has_alpha(1);

# set a colour (rgba, so this is transparent orange)
$image->set_color(255, 127, 0, 127);

# draw a rectangle
$image->draw_rectangle(50, 50, 50, 50);

# draw a filled rectangle
$image->fill_rectangle(150, 50, 50, 50);

# draw a line
$image->draw_line(0, 0, 200, 50);

# set quality before saving
$image->set_quality(50);

# save out
$image->save('out.png');

# create a polygon
my $poly = Image::Imlib2::Polygon->new();

# add some points
$poly->add_point(0, 0);
$poly->add_point(100, 0);
$poly->add_point(100, 100);
$poly->add_point(0, 100);

# fill the polygon
$poly->fill();

# draw it closed on image
$image->draw_polygon($poly, 1);

# create a color range
my $cr = Image::Imlib2::ColorRange->new();

# add a color
my ($distance, $red, $green, $blue, $alpha) = (15, 200, 100, 50, 20);
$cr->add_color($distance, $red, $green, $blue, $alpha);

# draw it
my($x, $y, $width, $height, $angle) = (20, 30, 200, 200, 1);
$image->fill_color_range_rectangle($cr, $x, $y,
                                   $width, $height, $angle);

💖 DESCRIPTION 💖

Image::Imlib2 is a Perl port of Imlib2 — a graphics library that handles image file loading and saving, manipulation, arbitrary polygon support, etc. And the way it does ALL of these operations? FAST. 🔥 Like, actually fast. It lets you create colour images using a big pile of graphics primitives and then output them in a whole range of formats. Iconic behaviour honestly ✨

Image::Imlib2::Polygon and Image::Imlib2::ColorRange get described after Image::Imlib2, but don't stress — you're allowed to reference them before their description. It's giving "meet the whole friend group later, you can still say their names now" 😌

Heads up bestie: this is an early version of the author's attempt at a Perl interface to Imlib2. Currently the API is just to test things out. Not everything is supported, but a great deal of functionality already exists. If you think the API could be tweaked to be a bit more intuitive, drop the author a line! 💌

Also important, don't skip this: a development version of Imlib2 must be installed before installing this module. Non-negotiable, fr fr 🙈

🌈 Exported constants 🌈

These bad boys live in your namespace rent-free after use Image::Imlib2. Use them as the direction parameter for the text functions that accept one.

`TEXT_TO_RIGHT`

Text goes to the right. ➡️ the default, the main character, the classic.

`TEXT_TO_LEFT`

Text goes to the left. ⬅️

`TEXT_TO_UP`

Text goes up. ⬆️

`TEXT_TO_DOWN`

Text goes down. ⬇️

`TEXT_TO_ANGLE`

Text goes at an angle. 🌀

👑 METHODS (Image::Imlib2) 👑

`new`

Creates a brand new, blank image 🎨 If you don't pass dimensions, it defaults to 256 x 256.

my $image = Image::Imlib2->new(100, 100);

⚠️ Careful bestie: the contents of this image at creation time are undefined — they could literally be garbage memory 💀 You should clear the image if you need it to be something specific. No assumptions, periodt.

`new_transparent`

Creates a new, fully-transparent image 🫧 Same deal with dimensions: if you don't specify them, it defaults to 256 x 256.

my $image = Image::Imlib2->new_transparent(100, 100);

`new_using_data`

Creates a new image from the pixel data you hand it — and that data has to be a packed string 📦 If the dimensions aren't specified, it defaults to 256 x 256.

my $pixel = pack('CCCC', 255, 127, 0, 255); # ARGB
my $image = Image::Imlib2->new_using_data(100, 100, $pixel x (100*100));

`load`

Loads an existing graphics file and creates a new image object from it 🖼️ It reads quite a few different image formats, so it's versatile like that.

my $image = Image::Imlib2->load("foo.png");

`save`

Saves the current image out 💾 Currently it saves as PNG if the format hasn't been set using image_set_format().

$image->save("out.png");

`image_set_format` (format)

Sets the image format for all your future save operations 👀 format is a string and may be "jpeg", "tiff", "png", etc. How many formats you actually get depends on how you built imlib2 — so it's giving "your mileage may vary" energy.

$image->image_set_format("jpeg"); # Convert image to JPG

`set_quality`

Sets the quality of the saved picture 🎚️ Lower the quality to get smaller filesizes. Tiny file, tiny quality, that's the tradeoff bestie.

$image->set_quality(50);

`set_color` (r, g, b, a) or `set_colour` (r, g, b, a)

Sets the colour that the drawing primitives will use 🖌️ You give it red, green, blue and alpha components, and they should all range from 0 to 255. The alpha component is the transparency dial: 0 is fully transparent (so drawing with it will be pointless, you'd literally be drawing nothing), 127 is half-transparent, and 255 is fully opaque.

Many examples, because we love examples:

$image->set_colour(255, 255, 255, 255); # white
$image->set_colour(  0,   0,   0, 255); # black
$image->set_colour(127, 127, 127, 255); # 50% gray
$image->set_colour(255,   0,   0, 255); # red
$image->set_colour(  0, 255,   0, 255); # green
$image->set_colour(  0,   0, 255, 255); # blue
$image->set_colour(255, 127,   0, 127); # transparent orange

⚠️ Warning: this sets a global variable for the draw color. It's not a per-image little secret, it's a global mood. Choose wisely 💅

`draw_point` (x, y)

Colours a single point in the image with the currently-selected colour ✏️ Quick reminder on the coordinate system: (0, 0) is at the top left, (50, 0) is to the right of the top left, (0, 50) is below the top left, and (50, 50) is to the bottom right of the top left. Yes it's giving math class, but it's easy math 🍓

$image->draw_point(50, 50);

`query_pixel` (x, y)

Returns the colour of a pixel in the image 🔍 It hands you back the red, green, blue and alpha components:

my($r, $g, $b, $a) = $image->query_pixel(50,50);

`draw_line` (x1, y1, x2, y2)

Draws a line between two points in the currently-selected colour 📏 The example below draws between the (0, 0) and (100, 100) points:

$image->draw_line(0, 0, 100, 100);

`draw_rectangle` (x, y, w, h)

Draws the outline of a rectangle — top left point at (x, y), width w, height h, in the current colour 🟦 (It's a hollow one bestie, if you want it filled see fill_rectangle.)

$image->draw_rectangle(0, 0, 50, 50);

`fill_rectangle` (x, y, w, h)

Draws a filled rectangle — top left point at (x, y), width w, height h, in the current colour 🟪 Solid. Substantial. Ate.

$image->fill_rectangle(0, 0, 50, 50);

`draw_ellipse` (x, y, w, h)

Draws an ellipse with center (x, y), horizontal amplitude of w and vertical amplitude of h, in the current colour ⭕ Fun fact: setting w and h to the same value draws a circle. Circle moment 🫶

$image->draw_ellipse(100, 100, 50, 50);

`fill_ellipse` (x, y, w, h)

Draws a filled ellipse with center (x, y), horizontal amplitude of w and vertical amplitude of h, in the current colour 🔴 And yep — setting w and h to the same value draws a filled circle.

$image->fill_ellipse(100, 100, 50, 50);

`add_font_path` (dir)

Adds the directory path to the end of the current list of directories to scan for truetype (TTF) fonts 📚 It's the "and also check here" move.

$image->add_font_path("./ttfonts");

`load_font` (font)

Loads a truetype font from the first directory in the font path that contains that font 🔤 The font name format is "font_name/size". For example, if there's a font file called cinema.ttf somewhere in the font path, you might use "cinema/20" to load a 20 pixel sized font of cinema. So cute, so specific.

Note that this font will be used from now on, much like set_colour does for colours 🎀

$image->load_font("cinema/20");

⚠️ Warning: this sets a global variable for the current font. Global again! She's everywhere 💀

`get_text_size` (text, direction, angle)

Returns the width and height in pixels that the text string would use up if it were drawn with the current font 📐 direction and angle are optional and default to TEXT_TO_RIGHT and 0, respectively.

my($w, $h) = $image->get_text_size("Imlib2 and Perl!");
my($w1, $w2) = $image->get_text_size("Crazy text",
                                     TEXT_TO_UP, 1);

`draw_text` (x, y, text, direction, angle)

Draws the text using the current font and colour onto the image at position (x, y) ✍️ direction and angle are optional and default to TEXT_TO_RIGHT and 0, respectively.

$image->draw_text(50, 50, "Groovy, baby, yeah!");
$image->draw_text(50, 50, "Sweet, baby, yeah!",
                  TEXT_TO_UP, 1.571);

`autocrop`

Creates a duplicate of the image which is automatically cropped to remove the background colour from the outside of the image ✂️ It's giving "trim the dead ends bestie".

my $cropped_image = $image->autocrop;

`autocrop_dimensions`

Returns the x, y, width and height rectangle in an image which would hold the results of the autocrop method 📏 So you can peek before you commit.

my($x, $y, $w, $h) = $image->autocrop_dimensions;

`crop` (x, y, w, h)

Creates a duplicate of an x, y, width, height rectangle in the current image and returns another image 🖼️ Snip snip.

my $cropped_image = $image->crop(0, 0, 50, 50);

`blend` (source_image, merge_alpha, sx, sy, sw, sh, dx, dy, dw, dh)

Blends the source rectangle x, y, width, height from the source_image onto the current image at the destination x, y location, scaled to the width and height specified 🫱🫲 If merge_alpha is set to 1 it will also modify the destination image alpha channel — otherwise the destination alpha channel is left untouched.

$image->blend($cropped_image, 0, 0, 0, 50, 50, 200, 0, 50, 50);

`blur` (radius)

Blurs the image 🌫️ A radius of 0 has no effect. 1 and above determine the blur matrix radius, which determines how much to blur the image. Go higher, get fuzzier.

$image->blur(1);

`sharpen` (radius)

Sharpens the image 🔪 The radius affects how much to sharpen by.

$image->sharpen(1);

`clone` ()

Creates an exact duplicate of the current image 👯 Twin energy. Identical. No notes.

$cloned = $image->clone;

`draw_polygon` (polygon, closed)

Draws polygon (of type Imlib2::Image::Polygon) on the image 🔺 The polygon is drawn closed if closed is 1 and open if closed is 0.

$image->draw_polygon($poly, 1);

`fill_color_range_rectangle` (color_range, x, y, w, h, angle);

Uses the color range color_range to fill a rectangle with points x, y, x+width, y+width 🌈 Gradient rectangle, we love to see it.

$image->fill_color_range_rectangle($cr, 10, 20, 100, 150, 0);

`image_orientate` (steps)

Rotates the image by steps*90 degrees 🔄 So to rotate by 90 degrees set it to 1, for 180 degrees set it to 2, etc.

$image->image_orientate(1);                    # Rotate by 90 degrees.

`create_rotated_image` (radians)

Creates a new image, rotated from the original by a number of radians 🌀 For example, to rotate 45 degrees:

my $rotated = $image->create_rotated_image(45 / 360 * 3.141519*2);

`create_scaled_image` (x, y)

Creates a new image, scaled from the original to the dimensions given in x and y 📐 If x or y is 0, then it retains the aspect ratio given in the other one. Respectful of proportions, we stan.

$image2=$image->create_scaled_image(100,100);  # Scale to 100x100 pixels

`create_transparent_image` (alpha)

Creates a new image, based upon the original but with a fixed alpha value 👻 This creates a transparent image that you can then blend onto other images. Alpha ranges from 0 to 255:

my $new = $image->create_transparent_image(64);

(…and that's where create_transparent_image's little demo wraps up, bestie 💖 onward!)

`create_blended_image` (percent)

Okay so this one makes you a brand new image that is percent% of source1 and (100-percent)% of source2. It's the classic move for fading between two images. Percent lives in the 0 to 100 range, no cap:

my $new = $source1->create_blended_image($source2, 50);

`flip_horizontal` ()

Flips/mirrors the image horizontally — left becomes right, right becomes left. ✨

$image->flip_horizontal();

`flip_vertical` ()

Same energy, but vertically — top and bottom swap places. 💅

$image->flip_vertical();

`flip_diagonal` ()

Flips/mirrors the current image diagonally. This is your quick-and-dirty route to 90 degree rotations if you use it alongside a horizontal or vertical flip. 🔥

$image->flip_diagonal();

`has_alpha` (BOOLEAN)

Queries and/or sets the alpha support flag for the image. Fun fact: alpha is on by default when you create an image. 🫶

if ($image->has_alpha) {
   # do something requiring alpha support
}
# Enable the alpha channel
$image->has_alpha(1);

`set_cache_size` (INT)

So by default, Imlib2 will not cache any images loaded from disk. Ngl, that's just how it is. 🙈

But if you do set a cache size, then Imlib2 will cache all loaded images (up to this size) and will use this cache to avoid loading images from disk. Slay.

This sets the size of the image cache. Heads up: reducing this value will cause the cache to be emptied. And you can turn caching off entirely by setting this to zero.

Even without a cache, as long as you have a reference to an image in memory, that image will be returned immediately without checking the disk. ✨

Image::Imlib2->set_cache_size(1024 * 1024);
my $image = Image::Imlib2->load("foo.jpg"); # image loaded from disk
... later, somewhere else, after $image has gone away ...
my $image = Image::Imlib2->load("foo.jpg"); # same image, even if changed on disk
... later, somewhere else, after $image has gone away ...
Image::Imlib2->set_cache_size(0);
my $image  = Image::Imlib2->load("foo.jpg"); # image loaded from disk
my $image2 = Image::Imlib2->load("foo.jpg"); # same image as before, not reloaded

`get_cache_size` ()

Returns the maximum size of the Image cache. That's it, that's the method. 🎀

`set_changes_on_disk` ()

You call this on an Image::Imlib2 instance that you've loaded from disk, and it tells imlib that it should take extra care when caching the image for this filename. Next time the load method is called for this image's file name, Imlib will check the modification time for the file on disk compared to the cached version and take appropriate action. 👑

my $image = Image::Imlib2->load("foo.jpg");
$image->set_changes_on_disk();

...later...

# reloads image from disk if mod time has changed (otherwise use cached)
my $image = Image::Imlib2->load("foo.jpg");

Calling this method on a loaded image tells Imlib2 to look at the disk and compare mtimes with its loaded copy. By default, this is not the case, so even if a file changes on disk, it won't be re-loaded. Wild, right? 😭

`will_blend` (BOOL)

Changes the setting for whether drawing blends with existing pixels in the image or overwrites those pixels. Defaults to true. Returns the new value. And if you pass no argument at all, it just returns the current value. 💜

Warning: this sets a global variable for blending. Not me reminding you twice. 👀

`find_colour`

This returns the x and y coordinates for the first pixel of the current colour it finds in the image. If it doesn't find the colour, it returns undef. 🦋

# find a red pixel
$i->set_colour(255, 0, 0, 255);
my($rx, $ry) = $i->find_red;

`fill`

This flood fills the image, starting at the x and y coordinates and filling every pixel under it with the current colour. It's giving bucket tool. 🪣✨

$i->fill($x, $y);

🌈 METHODS (Image::Imlib2::Polygon) 🌈

`new`

This will create a new polygon for use with Image::Imlib2::draw_polygon. 💅

my $poly = Image::Imlib2::Polygon->new();

`add_point` (x, y)

Adds a point to the polygonal construct. One point at a time, bestie. 🎀

$poly->add_point(10,10);

`fill`

Fills polygon in the current context. Periodt.

$poly->fill();

🎨 METHODS (Image::Imlib2::ColorRange) 🎨

`new`

Creates a new color range. Fresh start, main character energy. ⭐

my $cr = Image::Imlib2::ColorRange->new();

`add_color` (distance, red, green, blue, alpha)

Similar to set_colour, but adds the color to the color range at the specified distance. 🌸

$cr->add_color(10, 255, 127, 0, 66);

Warning: this sets a global variable for the draw color. Yeah. Global. We don't make the rules. 💀

`width`

Returns the current width of the image. 🔥

my $width = $image->width;

`height`

Returns the current height of the image. 🔥

my $height = $image->height;

💀 DEPRECATED METHOS 💀

(yes, the heading says "METHOS", we're keeping it exactly as it is, it's iconic now)

`get_width`

Returns the current width of the image. Use width() instead. This one is deprecated, so like… let it go. 🫶

my $width = $image->get_width;

`get_height`

Returns the current height of the image. Use height() instead. Also deprecated. Also let it go. 🫶

my $height = $image->get_height;

👑 AUTHOR 👑

Leon Brocard, acme@astray.com

📜 COPYRIGHT 📜

🌈 LICENSE 🌈

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's the whole page, bestie — part 2, done, dusted, ate and left no crumbs. 💅 This doc drop came to you from perl v5.40.1, dated 2025-05-14, filed under Image::Imlib2(3pm). Go forth and manipulate some pixels. 🎀✨🦋

📦 where this page comes from

debian trixie: libimage-imlib2-perl 2.03-3 · GPL-1.0-or-later OR Artistic-1.0-Perl
ubuntu resolute: libimage-imlib2-perl 2.03-3 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Image::Imlib2(3pm)

✨ Image::Imlib2 ✨

🌸 NAME 🌸

🎀 SYNOPSIS 🎀

💖 DESCRIPTION 💖

🌈 Exported constants 🌈

TEXT_TO_RIGHT

TEXT_TO_LEFT

TEXT_TO_UP

TEXT_TO_DOWN

TEXT_TO_ANGLE

👑 METHODS (Image::Imlib2) 👑

new

new_transparent

new_using_data

load

save

image_set_format (format)

set_quality

set_color (r, g, b, a) or set_colour (r, g, b, a)

draw_point (x, y)

query_pixel (x, y)

draw_line (x1, y1, x2, y2)

draw_rectangle (x, y, w, h)

fill_rectangle (x, y, w, h)

draw_ellipse (x, y, w, h)

fill_ellipse (x, y, w, h)

add_font_path (dir)

load_font (font)

get_text_size (text, direction, angle)

draw_text (x, y, text, direction, angle)

autocrop

autocrop_dimensions

crop (x, y, w, h)

blend (source_image, merge_alpha, sx, sy, sw, sh, dx, dy, dw, dh)

blur (radius)

sharpen (radius)

clone ()

draw_polygon (polygon, closed)

fill_color_range_rectangle (color_range, x, y, w, h, angle);

image_orientate (steps)

create_rotated_image (radians)

create_scaled_image (x, y)

create_transparent_image (alpha)

create_blended_image (percent)

flip_horizontal ()

flip_vertical ()

flip_diagonal ()

has_alpha (BOOLEAN)

set_cache_size (INT)

get_cache_size ()

set_changes_on_disk ()

will_blend (BOOL)

find_colour

fill

🌈 METHODS (Image::Imlib2::Polygon) 🌈

new

add_point (x, y)

fill

🎨 METHODS (Image::Imlib2::ColorRange) 🎨

new

add_color (distance, red, green, blue, alpha)

width

height

💀 DEPRECATED METHOS 💀

get_width

get_height

👑 AUTHOR 👑

📜 COPYRIGHT 📜

🌈 LICENSE 🌈

`TEXT_TO_RIGHT`

`TEXT_TO_LEFT`

`TEXT_TO_UP`

`TEXT_TO_DOWN`

`TEXT_TO_ANGLE`

`new`

`new_transparent`

`new_using_data`

`load`

`save`

`image_set_format` (format)

`set_quality`

`set_color` (r, g, b, a) or `set_colour` (r, g, b, a)

`draw_point` (x, y)

`query_pixel` (x, y)

`draw_line` (x1, y1, x2, y2)

`draw_rectangle` (x, y, w, h)

`fill_rectangle` (x, y, w, h)

`draw_ellipse` (x, y, w, h)

`fill_ellipse` (x, y, w, h)

`add_font_path` (dir)

`load_font` (font)

`get_text_size` (text, direction, angle)

`draw_text` (x, y, text, direction, angle)

`autocrop`

`autocrop_dimensions`

`crop` (x, y, w, h)

`blend` (source_image, merge_alpha, sx, sy, sw, sh, dx, dy, dw, dh)

`blur` (radius)

`sharpen` (radius)

`clone` ()

`draw_polygon` (polygon, closed)

`fill_color_range_rectangle` (color_range, x, y, w, h, angle);

`image_orientate` (steps)

`create_rotated_image` (radians)

`create_scaled_image` (x, y)

`create_transparent_image` (alpha)

`create_blended_image` (percent)

`flip_horizontal` ()

`flip_vertical` ()

`flip_diagonal` ()

`has_alpha` (BOOLEAN)

`set_cache_size` (INT)

`get_cache_size` ()

`set_changes_on_disk` ()

`will_blend` (BOOL)

`find_colour`

`fill`

`new`

`add_point` (x, y)

`fill`

`new`

`add_color` (distance, red, green, blue, alpha)

`width`

`height`

`get_width`

`get_height`