Home

Overview

DIMS is a webservice that allows for dynamic image manipulation. It allows for easy image resizing and thumbnail generation directly in HTML pages, eliminating the need to pre-compute different image sizes and store their locations for use on a page.

Features

• Faster and smaller byte size thumbnail generation.
• Overall performance improvements.
• Extended API (and more modular for future additions).
• Ability to reference files locally as well as remotely.
• Ability to specify order of operations.
• More advanced geometry specification.
• Crop operation now accepts x, y offsets.
• Improved timeout resolution (now on both downloads and imagemagick operations).
• Improved resource constraints. (can set max memory imagemagick will use).
• Improved log messages.
• Cache header forwarding from source image.

Dependencies

ImageMagick 6.6.x: This is the engine used for image manipulation.

libcurl 7.18.x: This is used to fetch remote images.

Webservice API

Apache Configuration

DIMS Server Status

To see general information about a running DIMS server view the /dims-status/ URL. This URL contains information about the version of DIMS, the libraries it’s linked against and counts of successes/failures.

Example:

ALIVE

Uptime:  21 hours 21 minutes 29 seconds
Restart time: Sunday, 17-Aug-2008 12:25:31 EDT

mod_dims version: 3.0 ($Revision: 52209 $)
ImageMagick version: ImageMagick 6.4.2 08/16/08 Q8 http://www.imagemagick.org
libcurl version: libcurl/7.18.2 zlib/1.2.3

Details
-------
Successful requests: 2156243
Failed requests: 16

Download timeouts: 14
Imagemagick Timeouts: 2

Developer Information

Extending mod_dims

Adding new ImageMagick commands to mod_dims is very
straighforward. Every mod_dims image manipulation operation is
implemented as a dims_operation_func function. This function
signature is defined as:

Function Signature
apr_status_t (dims_operation_func) (dims_request_rec *d, char *args, char **err)

Arguments
dims_request_rec *d
The current DIMS request information. This contains the MagickWand, request_rec and other information that may be useful. See mod_dims.h for a complete definition of this struct.
char *args
The args provided for this command. For example if /thumbnail/78x100/ was our operation/arguments, *args would be a string containing 78x100
char **err
This is used to pass back a static string error message in case of an error.

To extend mod_dims implement a new dims_operation_func in mod_dims_ops.c, declare it in mod_dims.h and finally register it in the dims_init function in mod_dims.c.

The dims_operation_func implementation should return one of the DIMS_ status codes defined mod_dims.h. If an error occurred the **err pointer can be set to a static error message that will be logged. Returning anything other than DIMS_SUCCESS@ will result in the NOIMAGE image being returned to the user.

Here is an example:

First implement our new function. For this example we will add the blur command.

apr_status_t
dims_blur_operation (dims_request_rec *d, char *args, char **err) {
    MagickStatusType flags;
    GeometryInfo geometry;

    flags = ParseGeometry(args, &geometry);
    if ((flags & RhoValue) == 0) {
        *err = "Parsing blur arguments failed";
        return DIMS_FAILURE;
    }                

    MAGICK_CHECK(MagickBlurImage(d->wand, geometry.rho, 3), d);

    return DIMS_SUCCESS;
}

The MAGICK_CHECK macro will check to make sure the operation was
successful and did not timeout. If either of those occur it will return an
appropriate status code to force a NOIMAGE image to be returned to the user.

Now declare this new function in mod_dims.h by adding it to the list of dim_operation_func.

dims_operation_func 
    dims_resize_operation,
    .
    .
    . 
    dims_blur_operation;

Finally register this new function in dims_init in the
mod_dims.c file. This lets the DIMS handler know to call the new
dims_blur_operation function when it encounters the blur operation
in the URL.

ops = apr_hash_make(p);
apr_hash_set(ops, "resize", APR_HASH_KEY_STRING, dims_resize_operation);
.
.
.
apr_hash_set(ops, "blur", APR_HASH_KEY_STRING, dims_blur_operation);

That’s it. Now the new operation blur can be used by a DIMS webservice call. For example:

http://127.0.0.1:8001/dims3/TEST/blur/25/http://media.parker.beetlebug.org/archive/2009/03/17/DSC_D300_1872.web.jpg

Troubleshooting/Errors

There are three classes of errors in mod_dims;

• Errors caused during downloading of a source image. These come directly from libcurl and are logged as-is.
• Errors caused during an ImageMagick operation. These come directly from ImageMagik and are logged as-is.
• Errors caused during processing of a request by mod_dims. These fall into the category of bad input checking, bad config, etc.

ImageMagick Timeout Error Format

[client <client ip address> Imagemagick operation, '<operation>', timed out after 4 ms

would be a message similar to Resize/Image or Save/Image.

Example:

[client 127.0.0.1] Imagemagick operation, 'Resize/Image', timed out after 45773 ms. (max: 20000), on request: /03-slipknot-082707.jpg/PGMC/resize/91300x9883!/

General Error Format

Errors will be in the following format in Apache’s error log:

[client <client ip address>] <source> error, '<source error message>', on request: <request uri>

Examples:

[client 10.181.182.244] Imagemagick error, 'no decode delegate for this image format @'', on request: /20080803WI55426251_WI.jpg/TEST/thumbnail/78x100/

[client 10.181.182.244] mod_dims error, 'Parsing resize geometry failed.', on reques: /test.jpg/resize/100/

[client 10.181.182.244] libcurl error, 'Timeout was reached', on request: http://o.aolcdn.com/feedgallery/music/i/s/slipknot/03-slipknot-082707.jpg

Common libcurl Error Messages

These messages are usually self explanatory. The URL that failed will be logged along with this message.

"Couldn't connect to server"

"Couldn't resolve DNS"

"Timeout was reached"

Common mod_dims Error Messages

"Requested URL has hostname that is not in the whitelist. (aaolcdn.com)"
The hostname of a remote URL did not match any hostnames or prefix globs in the whitelist.
"Application ID is not valid"
The client id for the request was not found in the list of clients.
"Parsing thumbnail geometry failed"
Request URL has an invalid geometry (e.g. 78×1a00 instead of 78×100).
"Parsing crop geometry failed"
Request URL has invalid geometry.
"Failed to read image"
This occurs if ImageMagick had trouble reading the image. Check to make sure MAGICK_HOME is exported in the Apache start script.
"Unable to stat image file"
This occurs when a local request is unable to find the image to resize.

Common ImageMagick Error Messages

"Memory allocation failed"
This should rarely occur, if ever, but usually when it does it’s the result of an ImageMagick timeout. It does not necessary mean the process has run out of memory. In low numbers this error can safely be ignored.
"unrecognized image format"

"no decode delegate for this image format"
This happens when ImageMagick doesn’t know how to read a source image. If this happens a lot the referrer should be checked and if necessary notify the owner of that page that they are using an invalid format. If the format appears valid check that the actual image really is that format by downloading it and verifying it in an image editor. If it is valid notify the developers of mod_dims.
"zero-length blob not permitted"
This may occur if there was a failure to download the source image or potentially if the source image was zero bytes. If this happens a lot the owner of the page making the request should be notified.
"Unsupported marker type 0x03"
This may occur if the image is corrupted. The “0×03” may be different depending on the corruption.

Other more serious errors

Any errors that have Assertion failed are results of bugs in the code and
can be considered serious.

Assertion failed: (wand->signature == WandSignature), function MagickGetImageFormat, file wand/magick-image.c, line 4137.