Image toolkits


Functions

 image_get_available_toolkits ()
 image_get_toolkit ()
 image_toolkit_invoke ($method, $params=array())
 image_get_info ($file)
 image_scale_and_crop ($source, $destination, $width, $height)
 image_scale ($source, $destination, $width, $height)
 image_resize ($source, $destination, $width, $height)
 image_rotate ($source, $destination, $degrees, $background=0x000000)
 image_crop ($source, $destination, $x, $y, $width, $height)
 image_gd_info ()
 image_gd_settings ()
 image_gd_settings_validate ($form, &$form_state)
 image_gd_check_settings ()
 image_gd_resize ($source, $destination, $width, $height)
 image_gd_rotate ($source, $destination, $degrees, $background=0x000000)
 image_gd_crop ($source, $destination, $x, $y, $width, $height)
 image_gd_open ($file, $extension)
 image_gd_close ($res, $destination, $extension)

Detailed Description

Drupal's image toolkits provide an abstraction layer for common image file manipulations like scaling, cropping, and rotating. The abstraction frees module authors from the need to support multiple image libraries, and it allows site administrators to choose the library that's best for them.

PHP includes the GD library by default so a GD toolkit is installed with Drupal. Other toolkits like ImageMagic are available from contrib modules. GD works well for small images, but using it with larger files may cause PHP to run out of memory. In contrast the ImageMagick library does not suffer from this problem, but it requires the ISP to have installed additional software.

Image toolkits are installed by copying the image.ToolkitName.inc file into Drupal's includes directory. The toolkit must then be enabled using the admin/settings/image-toolkit form.

Only one toolkit maybe selected at a time. If a module author wishes to call a specific toolkit they can check that it is installed by calling image_get_available_toolkits(), and then calling its functions directly.

Function Documentation

image_crop ( $  source,
$  destination,
$  x,
$  y,
$  width,
$  height 
)

Crop an image to the rectangle specified by the given rectangle.

Parameters:
$source The file path of the source image.
$destination The file path of the destination image.
$x The top left co-ordinate, in pixels, of the crop area (x axis value).
$y The top left co-ordinate, in pixels, of the crop area (y axis value).
$width The target width, in pixels.
$height The target height, in pixels.
Returns:
TRUE or FALSE, based on success.

image_gd_check_settings (  ) 

Verify GD2 settings (that the right version is actually installed).

Returns:
A boolean indicating if the GD toolkit is avaiable on this machine.

image_gd_close ( $  res,
$  destination,
$  extension 
)

GD helper to write an image resource to a destination file.

Parameters:
$res An image resource created with image_gd_open().
$destination A string file path where the iamge should be saved.
$extension A string containing one of the following extensions: gif, jpg, jpeg, png.
Returns:
Boolean indicating success.

image_gd_crop ( $  source,
$  destination,
$  x,
$  y,
$  width,
$  height 
)

Crop an image using the GD toolkit.

image_gd_info (  ) 

Retrieve information about the toolkit.

image_gd_open ( $  file,
$  extension 
)

GD helper function to create an image resource from a file.

Parameters:
$file A string file path where the iamge should be saved.
$extension A string containing one of the following extensions: gif, jpg, jpeg, png.
Returns:
An image resource, or FALSE on error.

image_gd_resize ( $  source,
$  destination,
$  width,
$  height 
)

Scale an image to the specified size using GD.

image_gd_rotate ( $  source,
$  destination,
$  degrees,
$  background = 0x000000 
)

Rotate an image the given number of degrees.

image_gd_settings (  ) 

Retrieve settings for the GD2 toolkit.

image_gd_settings_validate ( $  form,
&$  form_state 
)

Validate the submitted GD settings.

image_get_available_toolkits (  ) 

Return a list of available toolkits.

Returns:
An array of toolkit name => descriptive title.

image_get_info ( $  file  ) 

Get details about an image.

Drupal only supports GIF, JPG and PNG file formats.

Returns:
FALSE, if the file could not be found or is not an image. Otherwise, a keyed array containing information about the image: 'width' - Width in pixels. 'height' - Height in pixels. 'extension' - Commonly used file extension for the image. 'mime_type' - MIME type ('image/jpeg', 'image/gif', 'image/png'). 'file_size' - File size in bytes.

image_get_toolkit (  ) 

Retrieve the name of the currently used toolkit.

Returns:
String containing the name of the selected toolkit, or FALSE on error.

image_resize ( $  source,
$  destination,
$  width,
$  height 
)

Resize an image to the given dimensions (ignoring aspect ratio).

Parameters:
$source The file path of the source image.
$destination The file path of the destination image.
$width The target width, in pixels.
$height The target height, in pixels.
Returns:
TRUE or FALSE, based on success.

image_rotate ( $  source,
$  destination,
$  degrees,
$  background = 0x000000 
)

Rotate an image by the given number of degrees.

Parameters:
$source The file path of the source image.
$destination The file path of the destination image.
$degrees The number of (clockwise) degrees to rotate the image.
$background An hexidecimal integer specifying the background color to use for the uncovered area of the image after the rotation. E.g. 0x000000 for black, 0xff00ff for magenta, and 0xffffff for white.
Returns:
TRUE or FALSE, based on success.

image_scale ( $  source,
$  destination,
$  width,
$  height 
)

Scales an image to the given width and height while maintaining aspect ratio.

The resulting image can be smaller for one or both target dimensions.

Parameters:
$source The file path of the source image.
$destination The file path of the destination image.
$width The target width, in pixels.
$height The target height, in pixels.
Returns:
TRUE or FALSE, based on success.

image_scale_and_crop ( $  source,
$  destination,
$  width,
$  height 
)

Scales an image to the exact width and height given. Achieves the target aspect ratio by cropping the original image equally on both sides, or equally on the top and bottom. This function is, for example, useful to create uniform sized avatars from larger images.

The resulting image always has the exact target dimensions.

Parameters:
$source The file path of the source image.
$destination The file path of the destination image.
$width The target width, in pixels.
$height The target height, in pixels.
Returns:
TRUE or FALSE, based on success.

image_toolkit_invoke ( $  method,
$  params = array() 
)

Invokes the given method using the currently selected toolkit.

Parameters:
$method A string containing the method to invoke.
$params An optional array of parameters to pass to the toolkit method.
Returns:
Mixed values (typically Boolean indicating successful operation).