# phpman > perldoc > Image::Xbm

## NAME
    [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown) - Load, create, manipulate and save xbm image files.

## SYNOPSIS
        use [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown) ;

        my $j = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new( -file, 'balArrow.xbm' ) ;

        my $i = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new( -width => 10, -height => 16 ) ;

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

        my $p = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new_from_string( "###\n#-#\n###" ) ;

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

        my $s = $q->serialse ; # Compresses a little too.
        my $t = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->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

    View an xbm file from the command line:

        % perl -[MImage::Xbm](https://www.chedong.com/phpMan.php/perldoc/MImage%3A%3AXbm/markdown) -e'print [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new(-file,shift)->as_string' file

    Create an xbm file from the command line:

        % perl -[MImage::Xbm](https://www.chedong.com/phpMan.php/perldoc/MImage%3A%3AXbm/markdown) -e'[Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new_from_string("###\n#-#\n-#-")->save("test.xbm")'

## DESCRIPTION
    This class module provides basic load, manipulate and save functionality for the xbm file
    format. It inherits from "[Image::Base](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3ABase/markdown)" which provides additional manipulation functionality,
    e.g. "new_from_image()". See the "[Image::Base](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3ABase/markdown)" pod for information on adding your own
    functionality to all the "[Image::Base](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3ABase/markdown)" derived classes.

  new()
        my $i = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new( -file => 'test.xbm' ) ;
        my $j = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new( -width => 12, -height => 18 ) ;
        my $k = $i->new ;

    We can create a new xbm image by reading in a file, or by creating an image from scratch (all
    the bits are unset 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.

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

    "-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](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->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. If you want to use
    different characters you can:

        [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->set( -setch => 'X', -unsetch => ' ' ) ;
        my $s = $p->new_from_string( "XXX", "X X", "XhX" ) ;

    You can also specify a hotspot by making one of the characters a 'H' (set bit hotspot) or 'h'
    (unset bit hotspot) -- you can use different characters by setting "-sethotch" and "-unsethotch"
    respectively.

  new_from_serialised()
        my $i = [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->new_from_serialised( $s ) ;

    Creates an image from a string created with the "serialse()" method. Since such strings are a
    little more compressed than xbm files or [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown) objects they might be useful if storing a
    lot of bitmaps, or for transferring bitmaps over comms links.

  serialise()
        my $s = $i->serialise ;

    Creates a string version of the image which can be completed 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. Multiple attributes may be requested in a single call.

    See "xy" and "vec" to get/set bits 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. Except for
    "-setch" and "-unsetch" all attributes are object attributes; some attributes are read-only.

    See "xy" and "vec" to get/set bits of the image itself.

  class attributes
        [Image::Xbm](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3AXbm/markdown)->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 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.

    If you get a colour you will always get 'black' or 'white'.

  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 is 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 is saved in xbm format, e.g.

        #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. Note that hotspots and filenames
    are ignored, so we compare width, height and the actual bits only.

  as_string()
        print $i->as_string ;

    Returns the image as a string, e.g.

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

    The characters used may be changed by "set"ting the "-setch" and "-unsetch" characters. If you
    give "as_string" a parameter it will print out the hotspot if present using "-sethotch" or
    "-unsethotch" as appropriate, e.g.

        print $n->as_string( 1 ) ;

        H##
        #-#
        ###

  as_binstring()
        print $i->as_binstring ;

    Returns the image as a string of 0's and 1's, e.g.

        1111101110001110001001001000100000010000

## CHANGES
    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](https://www.chedong.com/phpMan.php/perldoc/Image%3A%3ABase/markdown), 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.

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

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