The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
GD-Thumbnail-1.45
River stage one • 1 direct dependent • 1 total dependent
++
/ GD::Thumbnail

NAME

GD::Thumbnail

VERSION

version 1.45

SYNOPSIS

    use GD::Thumbnail;
    my $thumb = GD::Thumbnail->new;
    my $raw   = $thumb->create('test.jpg', 80, 2);
    my $mime  = $thumb->mime;
    warn sprintf "Dimension: %sx%s\n", $thumb->width, $thumb->height;
    open    IMG, ">thumb.$mime" or die "Error: $!";
    binmode IMG;
    print   IMG $raw;
    close   IMG;

or

    use CGI qw(:standard);
    use GD::Thumbnail;
    my $thumb = GD::Thumbnail->new;
    my $raw   = $thumb->create('test.jpg', 80, 2);
    my $mime  = $thumb->mime;
    binmode STDOUT;
    print header(-type => "image/$mime");
    print $raw;

DESCRIPTION

This is a thumbnail maker. Thumbnails are smaller versions of the original image/graphic/picture and are used for preview purposes, where bigger images can take a long time to load. They are also used in image galleries to preview a lot of images at a time.

This module also has the capability to add information strips about the original image. Original image's size (in bytes) and resolution & mime type can be added to the thumbnail's upper and lower parts. This feature can be useful for web software (image galleries or forums).

This is a Yet Another type of module. There are several other thumbnail modules on CPAN, but they simply don't have the features I need, so this module is written to increase the thumbnail generator population on CPAN.

The module can raise an exception if something goes wrong. So, you may have to use an eval block to catch them.

NAME

GD::Thumbnail - Thumbnail maker for GD

METHODS

All color parameters must be passed as a three element array reference:

    $color = [$RED, $GREEN, $BLUE];
    $black = [   0,      0,     0];

new

Object constructor. Accepts arguments in key => value format.

    my $thumb = GD::Thumbnail->new(%args);

dimension_constraint

If set to true, the resulting dimensions will take the original image dimensions into consideration. Disabled by default.

default_text

Can be used to alter the bottom info strip text.

font

Alters the information text font. You can set this to Small, Large, MediumBold, Tiny or Giant (all are case-insensitive). Default value is Tiny, which is best for smaller images. If you want to use bigger thumbnails, you can alter the used font via this argument. It may also be useful for adding size & resolution information to existing images. But beware that GD output size may be smaller than the actual image and image quality may also differ.

force_mime

You can alter the thumbnail mime with this parameter. Can be set to: png, jpeg or gif.

frame

If set to true, a 1x1 pixel border will be added to the final image.

frame_color

Controls the frame color. Default is black.

info_color

Sets the info strip text color. Default is white. You must pass it as a three element array reference containing the red, green, blue values:

    $thumb = GD::Thumbnail->new(
      info_color => [255, 255, 255]
    );

overlay

If you want information strips (see "create"), but you don't want to get a longer image, set this to a true value, and the information strips will not affect the image height (but the actual thumbnail image will be smaller).

square

You'll get a square thumbnail, if this is set to true. If the original image is not a square, the empty parts will be filled with blank (color is the same as strip_color) instead of stretching the image in x or y dimension or clipping it. If, however, square is set to crop, you'll get a cropped square thumbnail.

Beware that enabling this option will also auto-enable the overlay option, since it is needed for a square image.

strip_height_buffer

The y buffer for the strips in pixels.

strip_color

Sets the info strip background color. Default is black. You must pass it as a three element array reference containing the red, green, blue values:

    $thumb = GD::Thumbnail->new(
      strip_color => [255, 0, 0]
    );

ttf_font

The file path to the TTF font, if you want to use that instead of the built-in GD fonts. You also need to unset the font parameter, otherwise it will take precedence.

ttf_ptsize

The point size of the TTF font you want to use. If not set, htne it will default to 18.

create

Creates the thumbnail and returns the raw image data. create() accepts three arguments:

    my $raw = $thumb->create($image    , $max, $info);
    my $raw = $thumb->create('test.jpg',   80, 1    );

image

Can be a file path, a file handle or raw binary data.

max

Defines the maximum width of the thumbnail either in pixels or percentage. You'll get a warning, if info parameter is set and your max value is to small to fit an info text.

info

If info parameter is not set, or it has a false value, you'll get a normal thumbnail image:

     _____________
    | ........... |
    | ........... |
    | ...IMAGE... |
    | ........... |
    | ........... |
    |_____________|

If you set it to 1, original image's dimensions and mime will be added below the thumbnail:

     _____________
    | ........... |
    | ........... |
    | ...IMAGE... |
    | ........... |
    | ........... |
    |_____________|
    | 20x20 JPEG  |
    -------------

If you set it to 2, the byte size of the image will be added to the top of the thumbnail:

     _____________
    |    25 KB    |
    |-------------|
    | ........... |
    | ........... |
    | ...IMAGE... |
    | ........... |
    | ........... |
    |_____________|
    | 20x20 JPEG  |
    -------------

As you can see from the examples above, with the default options, thumbnail image dimension is constant when adding information strips (i.e.: strips don't overlay, but attached to upper and lower parts of thumbnail). Each info strip increases thumbnail height by 8 pixels (if the default tiny GD font Tiny is used).

But see the overlay and square options in "new" to alter this behavior. You may also need to increase max value if square is enabled.

mime

Returns the thumbnail mime. Must be called after "create".

width

Returns the thumbnail width in pixels. Must be called after "create".

height

Returns the thumbnail height in pixels. Must be called after "create".

WARNINGS

You may get a warning, if there is something odd.

  • "Thumbnail width (%d) is too small for an info text"

    max argument to create is too small to fit information. Either disable info parameter or increase max value.

EXAMPLES

You can reverse the strip and info colors and then add a frame to the thumbnail to create a picture frame effect:

    my $thumb = GD::Thumbnail->new(
      strip_color => [255, 255, 255],
      info_color  => [  0,   0,   0],
      square      => 1,
      frame       => 1,
    );
    my $raw = $thumb->create('test.jpg', 100, 2);

If you have a set of images with the same dimensions, you may use a percentage instead of a constant value:

    my $raw = $thumb->create('test.jpg', '10%', 2);

Resulting thumbnail will be 90% smaller (x-y dimensions) than the original image.

CAVEATS

Supported image types are limited with GD types, which include png, jpeg and gif and some others. See GD for more information. Usage of any other image type will be resulted with a fatal error.

SEE ALSO

GD, Image::Thumbnail, GD::Image::Thumbnail, Image::GD::Thumbnail Image::Magick::Thumbnail, Image::Magick::Thumbnail::Fixed.

AUTHOR

Burak Gursoy <burak@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2006 by Burak Gursoy.

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