Image::BMP(3)

NAME
Image::BMP - Bitmap parser/viewer

SYNOPSIS
 use Image::BMP;

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

 # Example two:
 my $img2 = Image::BMP->new();
 $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 = Image::BMP->new(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 = Image::BMP->new(%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( [$file] );
    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) Optional filename as a parameter to save output to a file

$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 = Image::BMP->new(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>