Developers > Kernel Documentation > Data Handling >

ExSite::Image - image manager

Provides a few basic image management tools for the ExSite CMS. This is just a simple wrapper/API to whatever underlying image processing tools are going to do the heavy lifting, so it is easy to replace or extend with more powerful tools if needed.

This version tries to use Image::Info for fetching image attributes, and the convert shell command for modifying the image itself. NB: the convert command is part of the ImageMagick suite; so we could have just used the ImageMagick perl module instead. But the functions we require are relatively simple, so the massive ImageMagick module is a bit redundant for now.

To start working with a new image:

    my $img = new ExSite::Image($name,$rawdata);   # OR
my $img = new ExSite::Image($encoded_data);

To get the image attributes:

    my $info = $img->info;  # $info is a hash ref

To get the image size:

    my ($x,$y) = $img->dim;

There are two ways to change the image size: scale() (maintains aspect ratio) and resize() (ignores aspect ratio).

To scale the image size:

    my $stat = $img->scale(500,500,$flag);
    # $flag > 0   scale up to that size, if smaller
# $flag == 0 scale to that size
# $flag < 0 scale down to that size, if larger
# retain aspect ratio in all cases

To scale the image to exactly the passed dimensions (the edges may get cropped to achieve the new dimensions without distorting the original image):

    my $imgdata = $img->scale_crop($x,$y);

# $x: image width
# $y: image height

To thumbnail an image (preserve aspect ratio):

    my $stat = $img->thumb;  # equivalent to $img->scale(100,100,-1);

To get a square thumbnail (some cropping may be involved):

    my $imgdata = $img->square_thumb($width);

To force an exact resize without regard to aspect ratio, use resize:

    my $stat = $this->resize($newwidth,$newheight);

To get image raw data:
    my $imgdata = $img->get;

To get image data in exsite binary file encoding format:

    my $imgdata = $img->encode;

To get the size of the image data in bytes:

    my $nbyte = $img->size;

To shrink the file size of the image:


You can pass the following options in the hash: width, height (maximum width and height of the image), dim (maximum width OR height), and size (maximum file size in kilobytes).

In all cases, the quality of the image is set to 75% (mostly meaningful for JPGs), which will help shrink high-quality photos for web presentation without appreciable loss in quality. shrink() also strips any profiles out of the image.

With width, height, and dim, the image is scaled down to reduce its size. With size, the image is further scaled until it falls below the given size. However, if after 5 iterations, it cannot be shrunk to the requested size, it stops and returns what it has at that point. A return code of 1 is returned if the size objective is met; 0 otherwise.

Preparation of Images for the Web

Only GIF, PNG, and a subset of JPG images are widely accepted by browsers. Some JPGs are not web-friendly (namely ones with CMYK color encoding).

To test whether this is a web-ready image:

    if ($img->web_ready) { ...

If the image is not web ready, then you can convert it to a web-ready JPG format:


This can be used as a function call, if you prefer; it returns the number of bytes in the new JPEG file if the conversion succeeded, 0 if not.

The other thing that is often needed to prepare web images is just to scale them to a reasonable size. Images from digital cameras tend to be too large for web display, and images may also be large in terms of file size due to high quality settings, embedded profiles, and other factors.

You can use the scale function to force the image dimensions down to a specific size, or you can use the shrink function to set upper limits on both image dimensions and file size:

height => 500,
width => 300,
dim => 400, # used if height or width is not specified
size => 40, # kilobytes

If an image was uploaded in a non-lossy format like PNG, then the file size might be shrinkable much farther if converted to a JPEG first. However, for some types of line art, PNG and GIF can give excellent compression.