NAME
    Plack::Middleware::Image::Scale - Resize jpeg and png images on the fly

VERSION
    version 0.004

SYNOPSIS
        ## example1.psgi
    
        builder {
            enable 'ConditionalGET';
            enable 'Image::Scale';
            enable 'Static', path => qr{^/images/};
            $app;
        };

    A request to /images/foo_40x40.png will use images/foo.(png|jpg|gif) as
    original, scale it to 40x40 px size and convert to PNG format.

        ## example2.psgi

        my $thumber = builder {
            enable 'ConditionalGET';
            enable 'Image::Scale',
                width => 200, height => 100,
                flags => { fill => 'ff00ff' };
            Plack::App::File->new( root => 'images' );
        };

        builder {
            mount '/thumbs' => $thumber;
            mount '/' => $app;
        };

    A request to /thumbs/foo_x.png will use images/foo.(png|jpg|gif) as
    original, scale it small enough to fit 200x100 px size, fill extra
    borders (top/down or left/right, depending on the original image aspect
    ratio) with cyan background, and convert to PNG format. Also clipping is
    available, see below.

DESCRIPTION
    Scale and convert images to the requested format on the fly. By default
    the size and other scaling parameters are extracted from the request
    URI. Scaling is done with Image::Scale.

    The original image is not modified or even accessed directly by this
    module. The converted image is not cached, but the request can be
    validated (If-Modified-Since) against original image without doing the
    image processing, or even reading the file content from the filesystem.
    This middleware should be used together a cache proxy, that caches the
    converted images for all clients, and implements content validation.

    The response headers (like Last-Modified or ETag) are from the original
    image, but body is replaced with a PSGI content filter to do the image
    processing. The original image is fetched from next middleware layer or
    application with a normal PSGI request. You can use
    Plack::Middleware::Static, or Catalyst::Plugin::Static::Simple for
    example.

    See below for various size/format specifications that can be used in the
    request URI, and "ATTRIBUTES" for common configuration options that you
    can give as named parameters to the "enable".

    The default match pattern for URI is
    "*...**basename*_*width*x*height*-*flags*.*ext*".

    If URI doesn't match, the request is passed through. Any number of flags
    can be specified, separated with "-". Flags can be boolean (exists or
    doesn't exist), or have a numerical value. Flag name and value are
    separated with a zero-width word to number boundary. For example "z20"
    specifies flag "z" with value 20.

  basename
    Original image is requested from URI *basename*.*orig_ext*, where
    *orig_ext* is list of filename extensions. See "orig_ext".

  width
    Width of the output image. If not defined, it can be anything (to
    preserve the image aspect ratio).

  height
    Height of the output image. If not defined, it can be anything (to
    preserve the image aspect ratio).

  flags: fill
    Image aspect ratio is preserved by scaling the image to fit within the
    specified size. This means scaling to the smaller or the two possible
    sizes that preserve aspect ratio. Extra borders of background color are
    added to fill the requested image size exactly.

        /images/foo_400x200-fill.png

    If fill has a value, it specifies the background color to use. Undefined
    color with png output means transparent background.

        /images/foo_40x20-fill0xff0000.png  ## red background

  flags: crop
    Image aspect ratio is preserved by scaling and cropping from middle of
    the image. This means scaling to the bigger of the two possible sizes
    that preserve the aspect ratio, and then cropping to the exact size.

  flags: z
    Zoom the specified width or height N percent bigger. For example "z20"
    to zoom 20%. The zooming applies only to width and/or height defined in
    the URI, and does not change the crop size. Image is always cropped to
    the specified pixel width, height or both.

        /images/foo_40x-crop-z20.png

ATTRIBUTES
  match
    Only matching URIs are processed with this module. The match is done
    against PATH_INFO. Non-matching requests are delegated to the next
    middleware layer or application.

    Must be a RegexpRef, or CodeRef, that may return 3 values (regexp
    captures or normal return values). The request path is passed to the
    CodeRef in $_, and can be rewritten during match. This is used to strip
    off the image parameters from the URI. Rewritten URI is used for
    fetching the original image.

    First and second captures are the desired width and height of the
    resulting image. Third capture is an optional flag string. See
    "DESCRIPTION".

  orig_ext
    ArrayRef of possible original image formats. See "fetch_orig".

  memory_limit
    Memory limit for the image scaling in bytes, as defined in Image::Scale.

  jpeg_quality
    JPEG quality, as defined in Image::Scale.

  width
    Use this to set and override image width.

  height
    Use this to set and override image height.

  flags
    Use this to set and override image processing flags.

METHODS
  call
    Process the request. The original image is fetched from the backend if
    "path" match as specified. Normally you should use
    Plack::Middleware::Static or similar backend, that returns a filehandle
    or otherwise delayed body. Content-Type of the response is set according
    the request.

    The body of the response is replaced with a streaming body that
    implements a content filter to do the actual resizing for the original
    body. This means that if response body gets discarded due to header
    validation (If-Modified-Since or If-None-Match for example), the body
    never needs to be processed.

    However, if the original image has been modified, for example the
    modification date has been changed, the streaming body gets passed to
    the HTTP server (or another middleware layer that needs to read it in),
    and the conversion happens.

  fetch_orig
    The original image is fetched from the next layer or application. All
    possible extensions defined in "orig_ext" are used in order, to search
    for the original image. All other responses except a straight 404 (as
    returned by Plack::Middleware::Static for example) are considered
    matches.

  body_scaler
    Create a content filter callback to do the conversion with specified
    arguments. The callback binds to a closure with a buffer and the
    image_scale arguments. The callback will buffer the response and call
    "image_scale" after an EOF.

  image_scale
    Do the actual scaling and cropping of the image. Arguments are width,
    height and flags, as parsed in "call".

    See "DESCRIPTION" for description of various sizes and flags.

CAVEATS
    The cropping requires Imager. This is a run-time dependency, and
    fallback is not to crop the image to the desired size.

SEE ALSO
    Image::Scale

    Imager

    Plack::App::ImageMagick

AUTHOR
    Panu Ervamaa <pnu@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Panu Ervamaa.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.