Image::BMP - Bitmap parser/viewer

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:

quiet
Minimal info
Colorspace
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

-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>

Image::BMP - Bitmap parser/viewer