NAME

Image::BMP - Bitmap parser/viewer

SYNOPSIS

 use Image::BMP;

 # Example one:
 my $img = new Image::BMP(
        file            => 'some.bmp',
        debug           => 1,
        );
 $img->view_ascii;

 # Example two:
 my $img2 = new Image::BMP;
 $img2->open_file('another.bmp');
 my $color = $img2->xy(100,100);        # Get pixel at 100,100
 my ($r,$g,$b) = $img2->xy_rgb(100,200);

DESCRIPTION

Image::BMP objects can parse and even ascii view bitmaps of the .BMP format. It can read most of the common forms of this format.

It can be used to:

Just get image info, don't read the whole image:

 my $img = new Image::BMP(file => 'some.bmp');
 print "Resolution: $img->{Width} x $img->{Height}\n";

View images

  (See C<SYNOPSIS> example one)

Read images and poke at pixels

  (See C<SYNOPSIS> example two)

Parse through all pixel data

  (See C<ADD_PIXEL> below)

It does not currently write bmap data, simply because I didn't have a use for that yet. Convince me and I'll add it.

IMAGE INFO

The following data/keys are read when opening an image:

  FileSize, DataOffset, HeaderSize, Width, Height,
  Planes, BitCount, ColorBytes, Compression,
    (compression enum: RGB, RLE8, RLE4, BITFIELDS)
  ImageSize, XpixelsPerM, YpixelsPerM, ColorsUsed, ColorsImportant

METHODS

$img = new Image::BMP(%options);

Constructs a new Image::BMP object:

$img->open_file($filename);

Opens a file and reads the initial image information and colormap.

$img->open_pipe($command);

Opens a pipe to a command that outputs a bitmap (and reads image info/colormap). Example:

  $img->open_pipe("convert some.jpg bmp:-");

$img->close;

Close a file.

$img->load; $img->load($file);

Read the image in. Uses the file in %options if not specified.

$color = $img->colormap($index);

Lookup an index in the colormap;

$color = $img->xy($x,$y); $img->xy($x,$y,$color);

Lookup or set a pixel in the image by color. (Calls load if necessary)

$index = $img->xy_index($x,$y); $img->xy_index($x,$y,$index);

Lookup or set a pixel in the image by index. (Calls load if necessary)

($r,$g,$b) = $img->xy_rgb($x,$y); $img->xy_rgb($x,$y,$r,$g,$b);

Lookup or set a pixel in the image by rgb values. (Calls load if necessary)

$img->view_ascii;

Do a print of the image in crude ASCII fashion. Useful for debugging of small images. For kicks, open an xterm, set the font to "unreadable" and view the output. (Calls load if necessary)

$img->debug( [$val] )

Get/set the debug setting. Values are:

0. quiet

1. Minimal info

2. Colorspace

3. Pixel data

Generally only debug=0 or =1 are useful.

$img->remember_image( [$val] )

Get/set the remember_image setting. See ADD_PIXEL below.

$img->add_pixel( [$code] )

Get/set the add_pixel subroutine pointer.

ADD_PIXEL

Instead of having the object read the image into memory (or in addition to), you can process all the image data yourself by supplying a callback function:

 sub my_add {
   my ($img,$x,$y,$r,$g,$b) = @_;
   print "add pixel $x,$y = $r,$g,$b\n";
 }
 my $img = new Image::BMP(file => 'some.bmp', add_pixel = \&my_add);
 $img->load;

It may be useful to note that most bitmaps are read from left to right and bottom to top (x from 0 to width, y from height to 0), though the compression can skip values.

If you supply an add_pixel callback then load will not store the image data for efficiency. This means, however, that view_ascii, xy and xy_rgb will not work. You can use add_pixel and still save the image in memory by setting remember_image.

LIMITATIONS

4-bit RLE compression

I haven't seen an image like this yet, it wouldn't be hard to add.

bitfields compression

I don't even know what that is..

RLE 'delta' compression

This isn't tested yet - I haven't seen an image that uses this portion of RLE compression, so it currently does what I think is right and then prints a message asking you to send me the image/results.

COPYRIGHT

  Copyright 2004 <a href="http://GetDave.com/">David Ljung Madison</a>.  All rights reserved.
  See: <a href="http://MarginalHacks.com/">MarginalHacks.com</a>