view release on metacpan or  search on metacpan

ImageMagick.pm  view on Meta::CPAN

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

    1 ;

=head2 Createing images from scratch

Instead of modifing an existing image you can also create one from the scratch.
You do this by giving the C<-new=1> parameter. In this case Apache::ImageMagick
will not try to read an exiting image form disk, but create an empty one. You 
can use a script to create whatever you like. Here is an example:

In your F<httpd.conf> or F<.htaccess> you should set at least the cache directory
and the script directory:

    PerlSetVar AIMCacheDir /var/images/tmp
    PerlSetVar AIMScriptDir .

The C<'.'> as script directory will cause Apache::ImageMagick to look in the 
directory where the requested image should be for a script. So if you request:

    http://localhost/images/button.gif?-new=1

Apache::ImageMagick will look in the F<images> directory for script named
F<button.gif.pl>, which may look like the following. The script gets an
empty image object along with the other parameters. The scripts creates the
image and Apache::ImageMagick cares about saving the image:


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

    $image->Set(size=>'30x105');
    $image->Read('gradient:#00f685-#0083f8');
    $image->Rotate(-90);
    $image->Raise('6x6');
    $image->Annotate(text=>'Push Me',font=>'/usr/fonts/arial.ttf',fill=>'black',
      gravity=>'Center',pointsize=>18);

    1 ;

Of course you can run normal filters on such a created image, so you might like to use
a script like this, which creates an empty button, add the annotate filter  and sets 
some defaults arguments for it:


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

    $image->Set(size=>'30x105');
    $image->Read('gradient:#00f685-#0083f8');
    $image->Rotate(-90);
    $image->Raise('6x6');

    push @$filters, 'Annotate' ;

    $args -> {font}         = '/usr/fonts/arial.ttf' ;
    $args -> {gravity}      = 'Center' ;
    $args -> {pointsize}    = 18 ;


    1 ;

And request it with:

    http://localhost/images/button.gif?-new=1&text=Push+Me


=head2 Apache configuration directives

The following configuration directives are set via C<PerlSetVar> and used to 
control the operation of Apache::ImageMagick.

=over 4

=item AIMCacheDir

Directory for creating cached image files. Default: Directory of requested image.

=item AIMSourceDir

Directory in which Apache::ImageMagick looks for the source image files. 

Default: Directory of requested image.


=item AIMStripPrefix

This is prefix is stripped from the filename, before it is append to AIMSourceDir.
It's actually a Perl regex.

=item AIMScriptDir

Directory in which Apache::ImageMagick looks for a script that should be executed
to modfiy the parameters before conversion. The name of the script is build
by removing the AIMStripPrefix from the filename, append the result to AIMScriptDir
and appending the extension given with AIMScriptExt. If no AIMStripPrefix is given
the basename of the image is taken, the AIMScriptExt appended and searched in the
AIMScriptDir. The special value '.' means the same directory as the source image
itself. If AIMScriptDir is not set, no script is executed.

Default: No script is executed.

=item AIMScriptExt

Fileextention append to script name.

Default: pl


=item AIMScriptDefault

If given, this script is always executed before the image is created.

Default: No script is executed.

=item AIMCache

Turn caching off. Default: on.

=item AIMParameter

can be used to set defaults and/or force
parameters values. It contains a space spearated list of parameter values pairs. If you
need spaces inside your values, you have to quote the parameter/value pair.

Example:

 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. If there is no !
then the parameter acts as a default value.

=item AIMDebug

Turn this on to get some debug info into the httpd error log. Default: off.

=item AIMCheckMTime

When set the modification time of the source image is compared to the time of
the chached version. If the source is newer the it is recomputed. Default is off.

=item AIMDisableSearch

When set the search for a file with a different format is disabled. Default is
the automatic search and conversion is on.


=back

=head1 Non mod_perl frontend proxy

For performance reasons many people are running a setup with multiple Apache