Xpm(3) User Contributed Perl Documentation Xpm(3)NAMEImage::Xpm - Load, create, manipulate and save xpm image files.
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
This class module provides basic load, manipulate and save
functionality for the xpm file format. It inherits from "Image::Base"
which provides additional manipulation functionality, e.g.
"new_from_image()". See the "Image::Base" pod for information on adding
your own functionality to all the Image::Base derived classes.
new()
my $i = Image::Xpm->new(-file => 'test.xpm');
my $j = Image::Xpm->new(-width => 12, -height => 18);
my $k = $i->new;
We can create a new xpm image by reading in a file, or by creating an
image from scratch (all the pixels are white by default), or by copying
an image object that we created earlier.
If we set "-file" then all the other arguments are ignored (since
they're taken from the file). If we don't specify a file, "-width" and
"-height" are mandatory and "-cpp" will default to 1 unless specified
otherwise.
"-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 "load"ing and
"save"ing, though it can be overridden 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.
"-cpp"
Characters per pixel. Commonly 1 or 2, default is 1 for images
created by the module; read-only.
See the example for 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 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.
"-ncolours"
The number of unique colours in the palette. The image may not be
using all of them; read-only.
"-cindex"
An hash whose keys are colour names, e.g. '#123456' or 'blue' and
whose values are the palette names, e.g. ' ', '#', etc; read-only.
If you want to add more colours to the image itself simply write
pixels with the new colours using "xy"; if you want to 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, e.g. ' ', '#', etc. and
whose values are hashes of colour type x colour name pairs, e.g. "c
=> red", etc; read-only. If you want to add more colours to the
image itself simply write pixels with the new colours using "xy";
if you want to add more colours to the palette without necessarily
using them in the image 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);
Get any of the object's attributes. Multiple attributes may be
requested in a single call.
See "xy" and "vec" to get/set colours of the image itself.
set()
$i->set(-hotx => 120, -hoty => 32);
Set any of the object's attributes. Multiple attributes may be set in a
single call; some attributes are read-only.
See "xy" and "vec" to get/set colours of the image itself.
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; coordinates start at 0. If the
colour does not exist in the palette it will be added automatically.
When called to set the colour the value returned is characters used for
that colour in the palette; when called to get the colour the value
returned is the colour name, e.g. 'blue' or '#f0f0f0', etc, e.g.
$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.
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. The offset of a
pixel is ((y * width * cpp) + (x * cpp)).
The sort of return value depends on whether we are reading (getting) or
writing (setting) the colour - see "xy" for an explanation.
rgb2colour() and rgb2color()
$i->rgb2colour(0xff, 0x40, 0x80); # Returns #ff4080
Image::Xpm->rgb2colour(10, 20, 30); # Returns #0a141e
Convenience class or object methods which accept three integers and
return a colour name string.
load()
$i->load;
$i->load('test.xpm');
Load the image whose name is given, or if none is given load the image
whose name is in the "-file" attribute.
save()
$i->save;
$i->save('test.xpm');
Save the image using the name given, or if none is given save the image
using the name in the "-file" attribute. The image is saved in xpm
format.
add_colours() and add_colors()
$i->add_colours(qw(#C0C0DD red blue #123456));
These are for adding colours to the palette; you don't need to use them
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; duplicates are
ignored.
NB If you just want to set some pixels in colours that may not be in
the palette, simply do so using "xy" since new colours are added
automatically.
del_colour() and del_color()
$i->del_colour('green');
Delete a colour from the palette; returns undef if the colour isn't in
the palette, false (0) if the colour is in the palette but also in the
image, or 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);
CHANGES
2000/11/09
Added Jerrad Pierce's patch to allow load() to accept filehandles or
strings; will document in next release.
2000/10/19
Fixed bugs in xy() and vec() reported by Pat Gunn.
2000/05/25
Fixed a bug in the test file; fixed a bug in save() which affected xpm
extensions.
2000/05/04
Fixed bugs in xy(), vec(), save() and load(). Improved the test
program.
2000/05/03
Created.
AUTHOR
Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
include the word 'xpm' in the subject line.
COPYRIGHT
Copyright (c) Mark Summerfield 2000. All Rights Reserved.
This module may be used/distributed/modified under the GPL.
perl v5.14.2 2000-11-09 Xpm(3)
