Xpm(3pm)

🦋 Xpm — like, the whole vibe

okay bestie, sit down, hydrate, because we're about to talk about Image::Xpm — the Perl module that loads, creates, manipulates and saves xpm image files. this is from the User Contributed Perl Documentation section of the manual (that's the <3pm> part, iykyk) and honestly? it ate. let's get into it 💅

---

✨ SYNOPSIS ✨

use Image::Xpm;

my $j = Image::Xpm->new(-file, 'Camel.xpm');

my $i = Image::Xpm->new(-width => 10, -height => 16);

my $h = $i->new; # Copy of $i

$i->xy(5, 8, 'red');       # Set a colour (& add to palette if necessary)
print $i->xy(9, 3);        # Get a colour

$i->xy(120, 130, '#1256DD');
$i->xy(120, 130, $i->rgb2colour(66, 0x4D, 31));

$i->vec(24, '#808080');    # Set a colour using a vector offset
print $i->vec(24);         # Get a colour using a vector offset

print $i->get(-width);     # Get and set object attributes
$i->set(-height, 15);

$i->load('test.xpm');
$i->save;

# Changing just the palette
$i->add_colours(qw(red green blue #123456 #C0C0C0));
$i->del_colour('blue');

---

🌸 DESCRIPTION 🌸

so this class module gives you the basic load, manipulate and save functionality for the xpm file format. no cap. and here's the tea: it inherits from Image::Base, which is the parent that hooks you up with extra manipulation functionality, like new_from_image(). if you wanna add your own functionality to all the Image::Base derived classes, go read the Image::Base pod. periodt.

---

🎀 new()

my $i = Image::Xpm->new(-file => 'test.xpm');
my $j = Image::Xpm->new(-width => 12, -height => 18);
my $k = $i->new;

three ways to pop a new xpm image into existence, bestie:

1. read one in from a file 🍓
2. build one from scratch — and yes, all the pixels are white by default, she's a blank canvas ✨
3. copy an image object you already made earlier, main character energy 👑

heads up: if you set -file, then all the other arguments are ignored (because everything gets taken from the file instead). if you don't specify a file, then -width and -height are mandatory, and -cpp will default to 1 unless you say otherwise. fr fr.

the options, one by one 💖

• -file — the name of the file to read when creating the image. can contain a full path. this is also the default name used for loading and saveing, though you can override it whenever you load or save. she's flexible like that.
• -width — the width of the image. taken from the file, or set when the object is created. read-only, so don't try it.
• -height — the height of the image. taken from the file, or set when the object is created. also read-only. twins.
• -cpp — characters per pixel. commonly 1 or 2, and the default is 1 for images created by the module. read-only. (peep the example section if you wanna know how to change an image's cpp 👀)
• -hotx — the x-coord of the image's hotspot; taken from the file or set when the object is created. set it to -1 if there's no hotspot.
• -hoty — the y-coord of the image's hotspot; taken from the file or set when the object is created. set it to -1 if there's no hotspot.
• -ncolours — the number of unique colours in the palette. ngl, the image might not even be using all of them. read-only.
• -cindex — a hash whose keys are colour names (like '#123456' or 'blue') and whose values are the palette names (like ' ', '#', etc). read-only. if you wanna add more colours to the image itself, just write pixels with the new colours using xy; if you wanna add more colours to the palette without necessarily using them in the image, use add_colours.
• -palette — a hash whose keys are the palette names (like ' ', '#', etc) and whose values are hashes of colour type x colour name pairs, e.g. c => red, etc. read-only. same deal as above: to add colours to the image itself, just write pixels with xy; to add colours to the palette without necessarily using them, use add_colours.
• -pixels — a string of palette names which constitutes the data for the image itself. read-only.
• -extname — the name of the extension text, if any. commonly XPMEXT. read-only.
• -extlines — the lines of text of any extensions. read-only.
• -comments — an array (possibly empty) of comment lines that were in a file that was read in. they will be written out, although we make no guarantee regarding their placement 🙈 read-only.

---

🧚 get()

my $width = $i->get(-width);
my ($hotx, $hoty) = $i->get(-hotx, -hoty);

grab any of the object's attributes. and the best part? you can request multiple attributes in a single call, no need to spam her. ✨

if you're trying to get/set the colours of the image itself, that's a xy and vec situation, not this.

---

💜 set()

$i->set(-hotx => 120, -hoty => 32);

set any of the object's attributes. multiple attributes, single call, we love efficiency. just know that some attributes are read-only so don't come for them.

again, for colours of the image itself → xy and vec.

---

🌈 xy()

$i->xy(4, 11, '#123454');    # Set the colour at point 4,11
my $v = $i->xy(9, 17);       # Get the colour at point 9,17

get/set colours using x, y coordinates. and listen — coordinates start at 0, not 1, okay? and if the colour doesn't exist in the palette, it gets added automatically. she's helpful like that 🫶

when you call it to set the colour, the value returned is the characters used for that colour in the palette. when you call it to get the colour, the value returned is the colour name — like 'blue' or '#f0f0f0', etc. so:

$colour = xy($x, $y);            # e.g. #123456
$cc     = xy($x, $y, $colour);   # e.g. !

we don't normally pick up the return value when setting the colour, but like, you can.

---

⭐ vec()

$i->vec(43, 0);      # Unset the bit at offset 43
my $v = $i->vec(87); # Get the bit at offset 87

get/set bits using vector offsets, and those offsets start at 0 too. the offset of a pixel is:

((y * width * cpp) + (x * cpp))

the sort of return value depends on whether we're reading (getting) or writing (setting) the colour — go check xy for the full explanation, bestie.

---

💀 rgb2colour() and rgb2color()

$i->rgb2colour(0xff, 0x40, 0x80);    # Returns #ff4080
Image::Xpm->rgb2colour(10, 20, 30);  # Returns #0a141e

convenience class or object methods — your choice. they accept three integers and hand you back a colour name string. iconic behaviour, honestly.

(and yes, both spellings exist because we're inclusive of our American besties 🦋)

---

🔥 load()

$i->load;
$i->load('test.xpm');

load the image whose name is given. or, if no name is given, load the image whose name lives in the -file attribute. easy.

---

👑 save()

$i->save;
$i->save('test.xpm');

save the image using the name given. or, if no name is given, save using the name in the -file attribute. the image gets saved in xpm format. obviously 💅

---

🍓 add_colours() and add_colors()

$i->add_colours(qw(#C0C0DD red blue #123456));

these are for adding colours to the palette. and before you ask — no, you don't need them just to set a pixel's colour, use xy for that.

add one or more colour names, either as hex strings or as literal colour names. these are always added as type 'c' colours, and duplicates are ignored.

NB: if you just wanna set some pixels in colours that may not be in the palette, simply do so using xy, since new colours are added automatically. no need to overcomplicate your life.

---

🎀 del_colour() and del_color()

$i->del_colour('green');

delete a colour from the palette. and here's the return-value lore, pay attention:

• returns undef if the colour isn't in the palette
• returns false (0) if the colour is in the palette but also in the image
• returns true (1) if the colour has been deleted (i.e. it was in the palette but not in use in the image) 🎉

---

💖 EXAMPLE 💖

Changing the -cpp of an image:

my $i = Image::Xpm(-file => 'test1.xpm'); # test1.xpm has cpp == 1
my $j = $i->new_from_image('Image::xpm', -cpp => 2);
$j->save('test2.xpm');

# Could have written 2nd line above as:
my $j = $i->new_from_image(ref $i, -cpp => 2);

look at her go. cpp glow-up ✨

---

🌟 AUTHOR 🌟

Mark Summerfield. you can contact him as <summer@perlpress.com> — but please, include the word 'xpm' in the subject line, he's asking nicely 🙏

---

🌈 COPYRIGHT 🌈

Copyright (c) Mark Summerfield 2000. All Rights Reserved.

This module may be used/distributed/modified under the GPL.

---

okay that's the whole page, bestie. and for the cute sign-off: this beauty is documented as part of perl v5.40.1, dated 2024-11-11 — so yeah, she's current, she's maintained, she's the moment. go make some pixels 💅🎀🦋✨