NAME

Image::BoxModel - Module for defining boxes on an image and putting things on them

SYNOPSIS

 use Image::BoxModel;
  
 #Define an object
 my  $image = new Image::BoxModel (
        width   => 800, 
        height  => 400, 
        lib             => 'GD',                        #[IM|GD]
        precise => '1'          #IM only: IM-backend will draw antialiased lines instead of rounding to integers before drawing.
                                                #I don't know, if this is of interest to anyone..
        verbose => '1',         #If you want to see which modules and submodules do what. 
                                                #Be prepared to see many messages :-)
 );
                                
 #Define a box named "title" on the upper border
 print $image -> Box(position =>"top", height=>120, name=>"title", background =>'red'); 
 
 #Put some rotated text on the "title"-box and demonstrate some options. 
 #(verdana.ttf needs to be present in the same directory)
 print $image -> Text(
        box     => "title", 
        text    =>"Hello World!\nAligned right, positioned in the center (default)\nslightly rotated.", 
        textsize=>"16",
        rotate  => "10" , 
        font    => './FreeSans.ttf', #must be present in the same directory. See PORTABILITY below.
        fill    => "yellow", 
        background=>"green", 
        align   =>"Right"
 );
 
 print $image -> Box(position =>"left", width=>200, name=>"text_1", background =>'blue');       
 print $image -> Text(
        box             => "text_1", text =>"Some 'North-West'-aligned text.\n:-)", 
        textsize        => "12", 
        background      =>"yellow", 
        position        =>"NorthWest"
 );
 
 print $image -> Text(text => "Some more text on the free space.",textsize => 12, rotate=> "-30");
 
 #Save image to file
 $image -> Save(file=> "01_hello_world_$image->{lib}.png");

More examples are in examples/

DESCRIPTION

OBJECTIVES

Have a way to draw things on images using the same code with different libraries.

Use OO-style design to make the implementation of new library backends (library wrappers) easy. Image::Magick and GD present at the moment.

Use a box model to cut the original image into smaller rectangles. Afterwards objects can be drawn onto these boxes.

ANOTHER IMAGING / CHARTING / WHATEVER MODULE?

There are many Charting Modules and many Font Modules as well. There are many concepts about how to layout elements on an image / page.

This module will try hard to make the life of the user easier and the life of the developer more fun.

It has backends for graphic libraries so that you can draw images using the same code with different libraries.

Example: One user (me ;-) starts writing a perl script which produces some charts. Because Image::Magick is common to me, I use it. After some time I find out that GD would be much faster and is able to do everything I need. I have to rewrite much of my code because GD does many things different from how IM does them. ..And now someone tells me about the Imager-module from the CPAN!

With this module it is (should be) possible to just replace $image->{lib} in the constructor method and keep the rest of the code.

PORTABILITY

If you want to write portable code, you have to stick with the following things: (Portability between OSes and between backend libs)

Don't use fontconfig

You can profit from the wonderful possibilties offered by fontconfig, if you use this module on a system with fontconfig and GD as backend lib. Anyhow, if you change the backend to Image::Magick later or take your code to a system without fontconfig, it will produce errors.

Perhaps these considerations will lead to removing fontconfig support from Image::BoxModel. Perhaps 'font' will be mandatory for 'Text' and 'Annotate'. Perhaps there will be a possibilty to specify a default font.

Copy the font files into your projects directory tree

There is never a guarantee that fonts are present on a different system or on a different machine. You don't know if they are in the same place.

Always use the 'font' parameter with 'Text' and 'Annotate'

To be safe that the font is found (or an error is displayed), use

 font=>'path/to/my/font.ttf'

as a parameter with every 'Text' or 'Annotate' call.

Of course, it is much more conventient to rely on the default settings of fontconfig or some libraries internal magic, but it beaks portability very easily.

Don't use absolute paths

Yes, of course not. ;-)

It is tempting to use absolute paths to find fonts. Don't. Don't repeat my mistakes. :-)

Don't use library-methods

It is possible to use every method of the chosen library through the objects library-object:

$image->{IM} -> Edge(radius => "10");

This of course only works with Image::Magick. First, because there will be no {IM} if using GD und second, because GD doesn't know about 'Edge'. On the other hand, this code will only work with GD:

 $image->{GD} -> arc(50,50,95,75,0,360,$image->Colors(color=>'blue'));

There may be cases in which you will want to use library-specific code. Image::BoxModel doesn't implement all features of all libraries. Besides, this would be quite difficult.

FUTURE

Charts: being done

More graphic primitives

Vector graphic backend (The problem is, the module "thinks" in bitmaps, so it is not completely clear to me how to transfer this into vectors..)

Imager backend

Any more ideas?

QUESTIONS

Would it make sense to be able and cut off nonrectangular boxes? / Would it be desirable to cut off boxes which result in a nonrectangular remaining free space? (Define a rectangle in the upper left corner. Then the free field would be a concave hexagon. This produces some problems later: defining new boxes / find out if object is in the box)

How to translate the used bitmap model into the vector model? In the bitmap model the smallest unit is one pixel, which defines rather a area of the image with a certain size. In the world of vectors there is no smallest unit (is there?) and a point has no size.

EXAMPLES

There is a growing set of sample programs in the examples/ directory together with their respective images. This should allow you to understand how things work and verify if your copy of the module works as expected. To ensure they work even if you don't install the module into your system, they use a "use lib ("../lib"); Dunno if this is appropriate.

SEE:

README for installation & dependencies

Image::BoxModel::Lowlevel - basic functionality

Image::BoxModel::Text - direct and save drawing of text

Image::BoxModel::Chart - charts (incomplete)

Image::BoxModel::Color - mini-tutorial on how to use colors

BUGS

oh, please ;-)

Bug reports are welcome.

AUTHOR

Matthias Bloch, <lt>matthias at puffin ch<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by :m)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Image::BoxModel

perl -MCPAN -e shell
install Image::BoxModel