NAME

Catalyst::View::Thumbnail::Simple - Simple Catalyst view class for thumbnailing images

SYNOPSIS

    # in a view class of your application

    package MyApp::View::Thumbnailer; 
    use base 'Catalyst::View::Thumbnail::Simple;
    1;

    # in your controller

    my $raw_image_data = $image->data;

    # scale
    $c->stash( 
        image => \$raw_image_data, 
        image_size => 150 
    );
    $c->forward('View::Thumbnailer');


    # crop into a square and scale
    $c->stash( 
        image => \$raw_image_data, 
        image_size => 300, 
        square => 1 
    );
    $c->forward('View::Thumbnailer');

    # scale and transcode image to png
    $c->stash(
        image => \$raw_image_data,
        image_size => 150,
        image_type => 'png'
    );

DESCRIPTION

This module is a View class for Catalyst that will simply and efficiently create 'thumbnails' or scaled down versions of images using arguably the most sane perl image manipulation library, Imager. The behavior of this module is controlled by stash and config values.

Required stash attributes

image

A scalar reference containing raw image data.

Optional stash attributes

image_size

An integer in pixels of the desired longest side of the image. It will be scaled accordingly, maintaining it's original aspect ratio.

image_type

You can set this attribute to a string (e.g. 'png') to try to force Imager to write an image of a certain file format (note that this may fail). Otherwise the image type is automatically derived from the source image.

square

Set this to true to cause the image to be cropped into a square. See crop() in Imager::Transformations. Note that this takes place before the image is scaled (if image_size is available).

max_image_size

An integer in bytes of the largest size of image you want Imager to read (defaults to 15 megabytes). Note that this can also be set in your application's configuration like so:

    # example in YAML
    View::Thumbnail::Simple:
        max_image_size: 10_485_760

force_read

This module will avoid reading in image data unless necessary for scaling, cropping or transcoding (if the stash values are set, original image dimensions are checked as well as type). This is done to avoid unnecessary re-compression and loss of quality. If you want to force this module to read and write the image data regardless of these variables, set this stash key to a true value.

Optional config parameters

max_image_size

See above section about max_image_size

scaling_qtype

Pick what Imager scaling algo to use, defaults to 'mixing'. Please see the documentation on 'scale()' in Imager::Transformations.

jpeg_quality

An integer between 0-100 used to determine the quality of the image when writing JPEG files, defaults to 100. Please see the JPEG section of Imager::Files.

Returned stash attributes

After generating the thumbnail from the image data, the following stash values will be set:

image

The scaled Imager image object.

image_data

A scalar reference containing the raw data of the scaled image (this could be useful for caching purposes).

Imager read/write formats

Imager requires several libraries (e.g. libpng, libjpeg) for the ability to read some image file types. If you are unsure if you have these dependencies installed, type the following in your command shell to reveal what image types your version of Imager can currently read:

  perl -MImager -e 'print join(q{, }, Imager->read_types) . qq{\n}'

See the Imager perldocs for more information on image formats.

COPYRIGHT & LICENSE

Copyright (C) 2011 <aesop@cpan.org>

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