Xbm(3pm)

✨ NAME ✨

Image::Xbm — load, create, manipulate and save xbm image files 💖

okay so hi bestie, this is Xbm(3pm) from the User Contributed Perl Documentation corner of the internet, and it's lowkey iconic 🌸

---

🌈 SYNOPSIS 🌈

use Image::Xbm ;

my $j = Image::Xbm->new( -file, 'balArrow.xbm' ) ;

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

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

my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;

my $q = $p->new_from_string( "H##", "#-#", "###" ) ;

my $s = $q->serialse ; # Compresses a little too.
my $t = Image::Xbm->new_from_serialsed( $s ) ;

$i->xybit( 5, 8, 1 ) ;           # Set a bit
print '1' if $i->xybit( 9, 3 ) ; # Get a bit
print $i->xy( 4, 5 ) ;           # Will print black or white

$i->vec( 24, 0 ) ;            # Set a bit using a vector offset
print '1' if $i->vec( 24 ) ;  # Get a bit using a vector offset

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

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

print "equal\n" if $i->is_equal( $j ) ;

print $j->as_string ;

#####-
###---
###---
#--#--
#---#-
-----#

print $j->as_binstring ;

1111101110001110001001001000100000010000

wanna peek at an xbm file straight from the command line? say less 👑

% perl -MImage::Xbm -e'print Image::Xbm->new(-file,shift)->as_string' file

and wanna make one from the command line? also say less 💅

% perl -MImage::Xbm -e'Image::Xbm->new_from_string("###\n#-#\n-#-")->save("test.xbm")'

---

💜 DESCRIPTION 💜

So this class module gives you the basic load / manipulate / save trio for the xbm file format. It inherits from Image::Base, which is the one serving up all the extra manipulation functionality, like new_from_image(). If you wanna know how to bolt your own functionality onto every single Image::Base derived class, go read the Image::Base pod, bestie 🦋

🌸 new() 🌸

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

Three ways to manifest a new xbm image: read one in from a file, build one from scratch (every bit is unset by default, no cap), or copy an image object you already made earlier.

Heads up fr: if you set -file then all the other arguments get ignored, because they're taken from the file anyway. And if you don't give a file, then -width and -height are mandatory — no width, no height, no image 🫶

• -file — the name of the file to read when creating the image. May contain a full path. This is also the default name used for loading and saveing, though you can totally override it when you load or save.
• -width — the width of the image; taken from the file or set when the object is created; read-only.
• -height — the height of the image; taken from the file or set when the object is created; read-only.
• -hotx — the x-coord of the image's hotspot; taken from the file or set when the object is created. Set to -1 if there is no hotspot.
• -hoty — the y-coord of the image's hotspot; taken from the file or set when the object is created. Set to -1 if there is no hotspot.
• -bits — the bit vector that stores the image; read-only.

🎀 new_from_string() 🎀

my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;
my $q = $p->new_from_string( "H##", "#-#", "###" ) ;
my $r = $p->new_from_string( $p->as_string ) ;

Create a new bitmap from a string, or from an array or list of strings. Want different characters? Bet:

Image::Xbm->set( -setch => 'X', -unsetch => ' ' ) ;
my $s = $p->new_from_string( "XXX", "X X", "XhX" ) ;

You can also drop a hotspot in there by making one of the characters a 'H' (that's a set bit hotspot) or an 'h' (that's an unset bit hotspot) — and you can swap those characters out too by setting -sethotch and -unsethotch respectively ✨

🧚 new_from_serialised() 🧚

my $i = Image::Xbm->new_from_serialised( $s ) ;

Creates an image from a string that was created with the serialse() method. Since those strings are a little more compressed than xbm files or Image::Xbm objects, they might come in handy if you're storing a lot of bitmaps, or transferring bitmaps over comms links 📡

💫 serialise() 💫

my $s = $i->serialise ;

Creates a string version of the image which can be completely recreated using the new_from_serialised method.

⭐ get() ⭐

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

Get any of the object's attributes. You can request multiple attributes in a single call, efficient queen 👑

See xy and vec if you wanna get/set bits of the image itself.

🌟 set() 🌟

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

Set any of the object's attributes. Multiple attributes, one call, we love to see it. Except for -setch and -unsetch, all attributes are object attributes; some attributes are read-only though, so don't come for them.

See xy and vec if you wanna get/set bits of the image itself.

🦋 class attributes 🦋

Image::Xbm->set( -setch => 'X' ) ;
$i->set( -setch => '@', -unsetch => '*' ) ;

• -setch — the character to print set bits as when using as_string, default is '#'. This is a class attribute accessible from the class or an object via get and set.
• -unsetch — the character to print set bits as when using as_string, default is '-'. This is a class attribute accessible from the class or an object via get and set.
• -sethotch — the character to print set bits as when using as_string, default is 'H'. This is a class attribute accessible from the class or an object via get and set.
• -unsethotch — the character to print set bits as when using as_string, default is 'h'. This is a class attribute accessible from the class or an object via get and set.

🔥 xybit() 🔥

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

Get/set bits using x, y coordinates; coordinates start at 0 💅

🌸 xy() 🌸

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

Get/set bits using colours using x, y coordinates; coordinates start at 0.

If you set with a colour of 'black' or a numeric value > 0 or a string not matching /^#0+$/ then the bit will be set, otherwise it will be cleared.

And if you get a colour you will always get 'black' or 'white'. No in-between, periodt.

🌈 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; offsets start at 0.

💖 load() 💖

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

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

🎀 save() 🎀

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

Save the image using the name given, or if none is given, save the image using the name in the -file attribute. The image gets saved in xbm format, like:

#define test_width 6
#define test_height 6
static unsigned char test_bits[] = {
 0x1f, 0x07, 0x07, 0x09, 0x11, 0x20 } ;

✨ is_equal() ✨

print "equal\n" if $i->is_equal( $j ) ;

Returns true (1) if the images are equal, false (0) otherwise. But listen — hotspots and filenames are ignored, so we're comparing width, height and the actual bits only. Don't be surprised, iykyk 🙈

💜 as_string() 💜

print $i->as_string ;

Returns the image as a string, like:

#####-
###---
###---
#--#--
#---#-
-----#

The characters used may be changed by setting the -setch and -unsetch characters. And if you give as_string a parameter it will print out the hotspot if present, using -sethotch or -unsethotch as appropriate, like:

print $n->as_string( 1 ) ;

H##
#-#
###

🫶 as_binstring() 🫶

print $i->as_binstring ;

Returns the image as a string of 0's and 1's, like:

1111101110001110001001001000100000010000

---

👑 CHANGES 👑

2024/11/10

Allow filehandles in new()

2016/02/23 (Slaven Rezic)

Make sure macro/variable names are always sane.

More strict parsing of bits.

2000/11/09

Added Jerrad Pierce's patch to allow load() to accept filehandles or strings; will document in next release.

2000/05/05

Added new_from_serialised() and serialise() methods.

2000/05/04

Made xy() compatible with Image::Base, use xybit() for the earlier functionality.

2000/05/01

Improved speed of vec(), xy() and as_string().

Tried use integer to improve speed but according to Benchmark it made the code slower so I dropped it; interestingly perl 5.6.0 was around 25% slower than perl 5.004 with and without use integer.

2000/04/30

Created.

---

💌 AUTHOR 💌

Mark Summerfield. I can be contacted as <summer@perlpress.com> — please include the word 'xbm' in the subject line. (fr fr, the subject line thing is not a suggestion 💀)

---

🌟 COPYRIGHT 🌟

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

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

---

okay that's the whole page bestie, you're officially an xbm girlie now 💅🦋🌸 — this was Xbm(3pm) from perl v5.40.1, dated 2024-11-11, mwah 😘