view release on metacpan or  search on metacpan

ImageMagick.pm  view on Meta::CPAN

=pod

=head1 NAME

Apache::ImageMagick - Convert and manipulate images on the fly

=head1 SYNOPSIS

 In httpd.conf or .htaccess

 <Location /images>
 PerlFixupHandler Apache::ImageMagick
 PerlSetVar AIMCacheDir /var/aimcache
 </Location>   

 Then request

 http://localhost/images/whatever.gif/Annotate?font=Arial&x=5&gravity=west&text=Hello+world+!
 http://localhost/images/whatever.jpg


=head1 DESCRIPTION

This module uses the Image::Magick library to process an image on the fly. 
It is able to convert the source image to any type you request that is supported
by Image::Magick (e.g. TIFF, PPM, PGM, PPB, GIF, JPEG and more). The requested
fileformat is determinated by the fileextention of the request and 
Apache::ImageMagick will search for an image with the same basename and convert it
automaticly (unless you set C<AIMDisableSearch>).
Addtionaly you can specify (multiple) image manipulation filters in the additional path info,
and format options in the query string. All filters applied in the order they apear in
the path info. A list of available filters can be found at 
http://www.imagemagick.org/www/perl.html#mani . As of this writing there are 67 very 
powerfull filters available.
The parameters you give in the URL are passed to all filters. So the URL

 http://localhost/images/whatever.gif/Frame?color=gold

will request the image whatever.gif and apply the filter C<Frame> and pass the parameter
C<color> with the argument C<gold> to it, so you end up with a golden frame around 
that image. Addtionaly you can give all parameters that allowed in the C<Set> method
(see http://www.imagemagick.org/www/perl.html#seta ), for example to set the
quality of your jpeg image you can use

 http://localhost/images/whatever.jpg?quality=10
 
A filter croaks on parameters it doesn't knows, so there is a problem when you give multiple
filters different parameters. To distiguish the parameters for different filters or
to give the same parameter with different values to two filters you can
prefix the parameter name with the filter name separated by a colon:

 http://localhost/images/whatever.gif/Frame/Shade?Frame:color=gold&Shade:color=true

This will again draw a golden frame and will additonaly add a colored shadow.
The parameters for the C<Set> method a prefixed with C<Set:>

 http://localhost/images/whatever.jpg/Frame/Shade?Frame:color=gold&Shade:color=true&Set:quality=10

The C<AIMParameter> configuration diretive can be used to set defaults and/or force
parameters values. So you can say 

 PerlSetVar AIMParameter "font=/usr/images/fonts/arial.ttf !color=red" 

By prefixing the parameter with an !, the parameter values is foreced, so it 
can't be overridden by parameters passed to the hanlder via th URI.

=head2 Caching

Since conversion takes time Apache::ImageMagick caches the result unless you turn
off caching with the C<AIMCache> directive. If a cached image is found 
Apache::ImageMagick does nothing, but let Apache serve it just like a normal image.
To make cacheing work you normaly have to set the directory where to cache files.
This is done with the C<AIMCacheDir> directive. Of course the directoy must be
writeable by your http daemon. If you set addtionaly the C<AIMCheckMTime>
Apache::ImageMagick always check if the source file is newer then the
cached file. 

=head2 Using Scripts to process images

Another powerfull features of Apache::ImageMagick are scripts. These scripts 
are called after the image is loaded and before any processing takes places.
Such a script can modify all parameters or make operations on the image.
There are two possible sorts of scripts. A per image script, the name is build
by appending the extension given by C<AIMScriptExt> to the filename and searched
in the directory given by C<AIMScriptDir>. So if C<AIMScriptDir> is set to
F</usr/images/scripts> and a request for F<whatever.gif> comes in, Apache::ImageMagick
looks for a script named F</usr/images/scripts/whatever.gif.pl>. If the script is
found it is loaded into memory, compiled and executed. If the script is already in
memory, Apache::ImageMagick checks if the scripts is modified and if not it is only
executed, so the Perl code has to be compiled only when the script changes.
If C<AIMScriptDir> is not set, Apache::ImageMagick doesn't search for a per image
script. There is a second sort of script the default one. The full path of this script
is specfied by the C<AIMScriptDefault> directive and is executed after the per image
script was executed. So it is able to force some default values.
Both sort of scripts takes four parameters. The Apache request record, the Image::Magick
object of the loaded image, an arrayref which contains the names of all filters and a
hashref that contains all arguments. You can use the Apache object to retrives any
information about the request. You can make any operation on the image object and you
can modify the filters and arguments parameters. Here is an example that forces any fontname
to be searched in a certain directory with the extention ttf. This actualy causes 
Image::Magick to use true type fonts:


    use constant FONTPATH    => '/usr/images/fonts/' ; 
    use constant FONTDEFAULT => 'arial' ; 

    my ($r, $image, $filters, $args) = @_ ;

    my $font ;
    if ($args->{font})
        {
        $args->{font} =~ m#(^|.*/)([a-zA-z0-9_]+)# ;
        $font = $2 ;
        }
    else
        {
        $font = FONTDEFAULT ;
        }

    $args -> {font} = FONTPATH . $font . '.ttf' ;