Index: modules/user/user.test
===================================================================
RCS file: /cvs/drupal/drupal/modules/user/user.test,v
retrieving revision 1.28
diff -u -r1.28 user.test
--- modules/user/user.test	9 Feb 2009 07:36:15 -0000	1.28
+++ modules/user/user.test	16 Feb 2009 01:08:53 -0000
@@ -568,7 +568,9 @@
 
         $this->drupalLogin($this->user);
 
-        $image = current($this->drupalGetTestFiles('image'));
+        // Images are sorted first by size then by name. We need an image
+        // bigger than 1 KB so we'll grab the last one.
+        $image = end($this->drupalGetTestFiles('image'));
         $info = image_get_info($image->filename);
 
         // Set new variables: valid dimensions, invalid filesize.
Index: modules/system/image.gd.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/image.gd.inc,v
retrieving revision 1.3
diff -u -r1.3 image.gd.inc
--- modules/system/image.gd.inc	30 Dec 2008 16:43:19 -0000	1.3
+++ modules/system/image.gd.inc	16 Feb 2009 01:08:52 -0000
@@ -15,7 +15,12 @@
  * Retrieve information about the toolkit.
  */
 function image_gd_info() {
-  return array('name' => 'gd', 'title' => t('GD2 image manipulation toolkit'));
+  if (image_gd_check_settings()) {
+    return array(
+      'name' => 'gd',
+      'title' => t('GD2 image manipulation toolkit'),
+    );
+  }
 }
 
 /**
@@ -76,146 +81,231 @@
 
 /**
  * Scale an image to the specified size using GD.
+ *
+ * @param $image
+ *   An image object. The $image->resource, $image->info['width'], and
+ *   $image->info['height'] values will be modified by this call.
+ * @param $width
+ *   The new width of the resized image, in pixels.
+ * @param $height
+ *   The new height of the resized image, in pixels.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
-function image_gd_resize($source, $destination, $width, $height) {
-  if (!file_exists($source)) {
-    return FALSE;
-  }
+function image_gd_resize(stdClass $image, $width, $height) {
+  $res = image_gd_create_tmp($image, $width, $height);
 
-  $info = image_get_info($source);
-  if (!$info) {
+  if (!imagecopyresampled($res, $image->resource, 0, 0, 0, 0, $width, $height, $image->info['width'], $image->info['height'])) {
     return FALSE;
   }
 
-  $im = image_gd_open($source, $info['extension']);
-  if (!$im) {
-    return FALSE;
-  }
-
-  $res = imagecreatetruecolor($width, $height);
-  if ($info['extension'] == 'png') {
-    $transparency = imagecolorallocatealpha($res, 0, 0, 0, 127);
-    imagealphablending($res, FALSE);
-    imagefilledrectangle($res, 0, 0, $width, $height, $transparency);
-    imagealphablending($res, TRUE);
-    imagesavealpha($res, TRUE);
-  }
-  elseif ($info['extension'] == 'gif') {
-    // If we have a specific transparent color.
-    $transparency_index = imagecolortransparent($im);
-    if ($transparency_index >= 0) {
-      // Get the original image's transparent color's RGB values.
-      $transparent_color = imagecolorsforindex($im, $transparency_index);
-      // Allocate the same color in the new image resource.
-      $transparency_index = imagecolorallocate($res, $transparent_color['red'], $transparent_color['green'], $transparent_color['blue']);
-      // Completely fill the background of the new image with allocated color.
-      imagefill($res, 0, 0, $transparency_index);
-      // Set the background color for new image to transparent.
-      imagecolortransparent($res, $transparency_index);
-      // Find number of colors in the images palette.
-      $number_colors = imagecolorstotal($im);
-      // Convert from true color to palette to fix transparency issues.
-      imagetruecolortopalette($res, TRUE, $number_colors);
-    }
-  }
-  imagecopyresampled($res, $im, 0, 0, 0, 0, $width, $height, $info['width'], $info['height']);
-  $result = image_gd_close($res, $destination, $info['extension']);
-
-  imagedestroy($res);
-  imagedestroy($im);
-
-  return $result;
+  imagedestroy($image->resource);
+  // Update image object.
+  $image->resource = $res;
+  $image->info['width'] = $width;
+  $image->info['height'] = $height;
+  return TRUE;
 }
 
 /**
  * Rotate an image the given number of degrees.
+ *
+ * @param $image
+ *   An image object. The $image->resource, $image->info['width'], and
+ *   $image->info['height'] values will be modified by this call.
+ * @param $degress
+ *   The number of degrees to rotate the image.
+ * @param $background
+ *   The color of the exposed background when rotating.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
-function image_gd_rotate($source, $destination, $degrees, $background = 0x000000) {
-  if (!function_exists('imageRotate')) {
-    return FALSE;
+function image_gd_rotate(stdClass $image, $degrees, $background = NULL) {
+  $width = $image->info['width'];
+  $height = $image->info['height'];
+
+  // Convert the hexadecimal background value to a color index value.
+  if (isset($background)) {
+    $rgb = array();
+    for ($i = 16; $i >= 0; $i -= 8) {
+      $rgb[] = (($background >> $i) & 0xFF);
+    }
+    $background = imagecolorallocatealpha($image->resource, $rgb[0], $rgb[1], $rgb[2], 0);
   }
+  // Set the background color as transparent if $background is NULL.
+  else {
+    // Get the current transparent color.
+    $background = imagecolortransparent($image->resource);
 
-  $info = image_get_info($source);
-  if (!$info) {
-    return FALSE;
+    // If no transparent colors, use white.
+    if ($background == 0) {
+      $background = imagecolorallocatealpha($image->resource, 255, 255, 255, 0);
+    }
   }
 
-  $im = image_gd_open($source, $info['extension']);
-  if (!$im) {
-    return FALSE;
+  // Images are assigned a new color pallete when rotating, removing any
+  // transparency flags. For GIF images, keep a record of the transparent color.
+  if ($image->info['extension'] == 'gif') {
+    $transparent_index = imagecolortransparent($image->resource);
+    if ($transparent_index != 0) {
+      $transparent_gif_color = imagecolorsforindex($image->resource, $transparent_index);
+    }
   }
 
-  $res = imageRotate($im, $degrees, $background);
-  $result = image_gd_close($res, $destination, $info['extension']);
+  $image->resource = imagerotate($image->resource, 360 - $degrees, $background);
+
+  // GIFs need to reassign the transparent color after performing the rotate.
+  if (isset($transparent_gif_color)) {
+    $background = imagecolorexactalpha($image->resource, $transparent_gif_color['red'], $transparent_gif_color['green'], $transparent_gif_color['blue'], $transparent_gif_color['alpha']);
+    imagecolortransparent($image->resource, $background);
+  }
 
-  return $result;
+  $image->info['width'] = imagesx($image->resource);
+  $image->info['height'] = imagesy($image->resource);
+  return TRUE;
 }
 
 /**
  * Crop an image using the GD toolkit.
+ *
+ * @param $image
+ *   An image object. The $image->resource, $image->info['width'], and
+ *   $image->info['height'] values will be modified by this call.
+ * @param $x
+ *   The starting x offset at which to start the crop, in pixels.
+ * @param $y
+ *   The starting y offset at which to start the crop, in pixels.
+ * @param $width
+ *   The width of the cropped area, in pixels.
+ * @param $height
+ *   The height of the cropped area, in pixels.
+ * @return
+ *   TRUE or FALSE, based on success.
  */
-function image_gd_crop($source, $destination, $x, $y, $width, $height) {
-  $info = image_get_info($source);
-  if (!$info) {
+function image_gd_crop(stdClass $image, $x, $y, $width, $height) {
+  $res = image_gd_create_tmp($image, $width, $height);
+
+  if (!imagecopyresampled($res, $image->resource, 0, 0, $x, $y, $width, $height, $width, $height)) {
     return FALSE;
   }
 
-  $im = image_gd_open($source, $info['extension']);
-  $res = imageCreateTrueColor($width, $height);
-  imageCopy($res, $im, 0, 0, $x, $y, $width, $height);
-  $result = image_gd_close($res, $destination, $info['extension']);
-
-  imageDestroy($res);
-  imageDestroy($im);
+  // Destroy the original image and return the modified image.
+  imagedestroy($image->resource);
+  $image->resource = $res;
+  $image->info['width'] = $width;
+  $image->info['height'] = $height;
+  return TRUE;
+}
 
-  return $result;
+/**
+ * Convert an image resource to grayscale.
+ *
+ * Note that transparent GIFs loose transparency when desaturated.
+ *
+ * @param $image
+ *   An image object. The $image->resource value will be modified by this call.
+ * @return
+ *   TRUE or FALSE, based on success.
+ */
+function image_gd_desaturate(stdClass $image) {
+  return imagefilter($image->resource, IMG_FILTER_GRAYSCALE);
 }
 
 /**
  * GD helper function to create an image resource from a file.
  *
- * @param $file
- *   A string file path where the image should be saved.
- * @param $extension
- *   A string containing one of the following extensions: gif, jpg, jpeg, png.
+ * @param $image
+ *   An image object. The $image->resource value will populated by this call.
  * @return
  *   An image resource, or FALSE on error.
+ *
+ * @see image_open()
  */
-function image_gd_open($file, $extension) {
-  $extension = str_replace('jpg', 'jpeg', $extension);
-  $open_func = 'imageCreateFrom' . $extension;
-  if (!function_exists($open_func)) {
-    return FALSE;
+function image_gd_open(stdClass $image) {
+  $extension = str_replace('jpg', 'jpeg', $image->info['extension']);
+  $function = 'imagecreatefrom'. $extension;
+  if (function_exists($function) && $image->resource = $function($image->source)) {
+    return $image;
   }
-  return $open_func($file);
+  return FALSE;
 }
 
 /**
  * GD helper to write an image resource to a destination file.
  *
- * @param $res
- *   An image resource created with image_gd_open().
+ * @param $image
+ *   An image object.
  * @param $destination
  *   A string file path where the image should be saved.
  * @param $extension
  *   A string containing one of the following extensions: gif, jpg, jpeg, png.
  * @return
- *   Boolean indicating success.
+ *   TRUE or FALSE, based on success.
+ *
+ * @see image_close()
  */
-function image_gd_close($res, $destination, $extension) {
-  $extension = str_replace('jpg', 'jpeg', $extension);
-  $close_func = 'image' . $extension;
-  if (!function_exists($close_func)) {
+function image_gd_close(stdClass $image, $destination) {
+  $extension = str_replace('jpg', 'jpeg', $image->info['extension']);
+  $function = 'image'. $extension;
+  if (!function_exists($function)) {
     return FALSE;
   }
   if ($extension == 'jpeg') {
-    return $close_func($res, $destination, variable_get('image_jpeg_quality', 75));
+    return $function($image->resource, $destination, variable_get('image_jpeg_quality', 75));
   }
   else {
-    return $close_func($res, $destination);
+    // Always save PNG images with full transparency.
+    if ($extension == 'png') {
+      imagealphablending($image->resource, FALSE);
+      imagesavealpha($image->resource, TRUE);
+    }
+    return $function($image->resource, $destination);
   }
 }
 
 /**
+ * Create a truecolor image preserving transparency from a provided image.
+ *
+ * @param $image
+ *   An image object.
+ * @param $width
+ *   The new width of the new image, in pixels.
+ * @param $height
+ *   The new height of the new image, in pixels.
+ * @return
+ *   A GD image handle.
+ */
+function image_gd_create_tmp(stdClass $image, $width, $height) {
+  $res = imagecreatetruecolor($width, $height);
+
+  if ($image->info['extension'] == 'gif') {
+    // Grab transparent color index from image resource.
+    $transparent = imagecolortransparent($image->resource);
+
+    if ($transparent >= 0) {
+      // The original must have a transparent color, allocate to the new image.
+      $transparent_color = imagecolorsforindex($image->resource, $transparent);
+      $transparent = imagecolorallocate($res, $transparent_color['red'], $transparent_color['green'], $transparent_color['blue']);
+
+      // Flood with our new transparent color.
+      imagefill($res, 0, 0, $transparent);
+      imagecolortransparent($res, $transparent);
+    }
+  }
+  elseif ($image->info['extension'] == 'png') {
+    imagealphablending($res, FALSE);
+    $transparency = imagecolorallocatealpha($res, 0, 0, 0, 127);
+    imagefill($res, 0, 0, $transparency);
+    imagealphablending($res, TRUE);
+    imagesavealpha($res, TRUE);
+  }
+  else {
+    imagefill($res, 0, 0, imagecolorallocate($res, 255, 255, 255));
+  }
+
+  return $res;
+}
+
+/**
  * @} End of "ingroup image".
  */
Index: modules/system/system.admin.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.admin.inc,v
retrieving revision 1.125
diff -u -r1.125 system.admin.inc
--- modules/system/system.admin.inc	11 Feb 2009 05:33:18 -0000	1.125
+++ modules/system/system.admin.inc	16 Feb 2009 01:08:53 -0000
@@ -1462,6 +1462,15 @@
  */
 function system_image_toolkit_settings() {
   $toolkits_available = image_get_available_toolkits();
+
+  if (count($toolkits_available) == 0) {
+    variable_del('image_toolkit');
+    $form['image_toolkit_help'] = array(
+      '#markup' => t("No image toolkits were detected. Drupal includes support for <a href='!gd-link'>PHP's built-in image processing functions</a> but they were not detected on this system. You should consult your system administrator to have them enabled, or try using a third party toolkit.", array('gd-link' => url('http://php.net/gd'))),
+    );
+    return $form;
+  }
+
   if (count($toolkits_available) > 1) {
     $form['image_toolkit'] = array(
       '#type' => 'radios',
@@ -1470,12 +1479,11 @@
       '#options' => $toolkits_available
     );
   }
-  elseif (count($toolkits_available) == 1) {
+  else {
     variable_set('image_toolkit', key($toolkits_available));
   }
 
   $form['image_toolkit_settings'] = image_toolkit_invoke('settings');
-
   return system_settings_form($form, TRUE);
 }
 
Index: includes/file.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/file.inc,v
retrieving revision 1.157
diff -u -r1.157 file.inc
--- includes/file.inc	13 Feb 2009 00:39:01 -0000	1.157
+++ includes/file.inc	16 Feb 2009 01:08:52 -0000
@@ -1183,13 +1183,11 @@
       list($width, $height) = explode('x', $maximum_dimensions);
       if ($info['width'] > $width || $info['height'] > $height) {
         // Try to resize the image to fit the dimensions.
-        if (image_get_toolkit() && image_scale($file->filepath, $file->filepath, $width, $height)) {
+        if ($image = image_open($file->filepath)) {
+          image_scale($image, $width, $height);
+          image_close($image);
+          $file->filesize = $image->info['file_size'];
           drupal_set_message(t('The image was resized to fit within the maximum allowed dimensions of %dimensions pixels.', array('%dimensions' => $maximum_dimensions)));
-
-          // Clear the cached filesize and refresh the image information.
-          clearstatcache();
-          $info = image_get_info($file->filepath);
-          $file->filesize = $info['file_size'];
         }
         else {
           $errors[] = t('The image is too large; the maximum dimensions are %dimensions pixels.', array('%dimensions' => $maximum_dimensions));
Index: includes/image.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/image.inc,v
retrieving revision 1.28
diff -u -r1.28 image.inc
--- includes/image.inc	30 Dec 2008 16:43:14 -0000	1.28
+++ includes/image.inc	16 Feb 2009 01:08:52 -0000
@@ -36,7 +36,7 @@
  * Return a list of available toolkits.
  *
  * @return
- *   An array of toolkit name => descriptive title.
+ *   An array with the toolkit names as keys and the descriptions as values.
  */
 function image_get_available_toolkits() {
   // hook_image_toolkits returns an array of toolkit names.
@@ -46,10 +46,12 @@
   foreach ($toolkits as $name) {
     $function = 'image_' . $name . '_info';
     if (drupal_function_exists($function)) {
-      $info = $function();
-      $output[$info['name']] = $info['title'];
+      if ($info = $function()) {
+        $output[$info['name']] = $info['title'];
+      }
     }
   }
+
   return $output;
 }
 
@@ -62,14 +64,13 @@
 function image_get_toolkit() {
   static $toolkit;
 
-  if (!$toolkit) {
+  if (!isset($toolkit)) {
+    $toolkits = image_get_available_toolkits();
     $toolkit = variable_get('image_toolkit', 'gd');
-    if (isset($toolkit) &&
-      drupal_function_exists("image_" . $toolkit . "_resize")) {
-    }
-    elseif (!drupal_function_exists("image_gd_check_settings") ||
-      !image_gd_check_settings()) {
-      $toolkit = FALSE;
+    if (!isset($toolkits[$toolkit]) || !drupal_function_exists('image_' . $toolkit . '_open')) {
+      // The selected toolkit isn't available so return the first one found. If
+      // none are available this will return FALSE.
+      $toolkit = reset($toolkits);
     }
   }
 
@@ -87,19 +88,16 @@
  *   Mixed values (typically Boolean indicating successful operation).
  */
 function image_toolkit_invoke($method, $params = array()) {
-  if ($toolkit = image_get_toolkit()) {
-    $function = 'image_' . $toolkit . '_' . $method;
-    if (drupal_function_exists($function)) {
-      return call_user_func_array($function, $params);
-    }
-    else {
-      watchdog('php', 'The selected image handling toolkit %toolkit can not correctly process %function.', array('%toolkit' => $toolkit, '%function' => $function), WATCHDOG_ERROR);
-      return FALSE;
-    }
+  $image = $params[0];
+  $toolkit = isset($image->toolkit) ? $image->toolkit : image_get_toolkit();
+  $function = 'image_' . $toolkit . '_' . $method;
+  if (drupal_function_exists($function)) {
+    return call_user_func_array($function, $params);
   }
+  watchdog('image', 'The selected image handling toolkit %toolkit can not correctly process %function.', array('%toolkit' => $toolkit, '%function' => $function), WATCHDOG_ERROR);
+  return FALSE;
 }
 
-
 /**
  * Get details about an image.
  *
@@ -108,8 +106,8 @@
  * @return
  *   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.
+ *    '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.
@@ -137,133 +135,245 @@
 }
 
 /**
- * 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.
+ * Scales an image to the exact width and height given.
+ *
+ * This function achieves the target aspect ratio by cropping the original image
+ * equally on both sides, or equally on the top and bottom. This function is
+ * useful to create uniform sized avatars from larger images.
  *
  * The resulting image always has the exact target dimensions.
  *
- * @param $source
- *   The file path of the source image.
- * @param $destination
- *   The file path of the destination image.
+ * @param $image
+ *   An image object returned by image_open().
  * @param $width
  *   The target width, in pixels.
  * @param $height
  *   The target height, in pixels.
  * @return
  *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
  */
-function image_scale_and_crop($source, $destination, $width, $height) {
-  $info = image_get_info($source);
-
-  $scale = max($width / $info['width'], $height / $info['height']);
-  $x = round(($info['width'] * $scale - $width) / 2);
-  $y = round(($info['height'] * $scale - $height) / 2);
+function image_scale_and_crop(stdClass $image, $width, $height) {
+  $aspect = $image->info['height'] / $image->info['width'];
+  if (empty($height)) $height = $width / $aspect;
+  if (empty($width)) $width = $height * $aspect;
+
+  $scale = max($width / $image->info['width'], $height / $image->info['height']);
+  $x = (int) round(($image->info['width'] * $scale - $width) / 2);
+  $y = (int) round(($image->info['height'] * $scale - $height) / 2);
 
-  if (image_toolkit_invoke('resize', array($source, $destination, $info['width'] * $scale, $info['height'] * $scale))) {
-    return image_toolkit_invoke('crop', array($destination, $destination, $x, $y, $width, $height));
+  if (image_resize($image, $image->info['width'] * $scale, $image->info['height'] * $scale)) {
+    return image_crop($image, $x, $y, $width, $height);
   }
   return FALSE;
 }
 
 /**
- * Scales an image to the given width and height while maintaining aspect
- * ratio.
+ * 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.
  *
- * @param $source
- *   The file path of the source image.
- * @param $destination
- *   The file path of the destination image.
+ * @param $image
+ *   An image object returned by image_open().
  * @param $width
  *   The target width, in pixels.
  * @param $height
  *   The target height, in pixels.
+ * @param $upscale
+ *   Allow upscaling.
  * @return
  *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
+ * @see image_scale_and_crop()
  */
-function image_scale($source, $destination, $width, $height) {
-  $info = image_get_info($source);
+function image_scale(stdClass $image, $width = NULL, $height = NULL, $upscale = FALSE) {
+  $aspect = $image->info['height'] / $image->info['width'];
 
-  // Don't scale up.
-  if ($width >= $info['width'] && $height >= $info['height']) {
-    return FALSE;
+  if ($upscale) {
+    // Set width/height according to aspect ratio if either is empty.
+    $width = !empty($width) ? $width : $height / $aspect;
+    $height = !empty($height) ? $height : $width / $aspect;
+  }
+  else {
+    // Set impossibly large values if the width and height aren't set.
+    $width = !empty($width) ? $width : 9999999;
+    $height = !empty($height) ? $height : 9999999;
+
+    // Don't scale up.
+    if (round($width) >= $image->info['width'] && round($height) >= $image->info['height']) {
+      return TRUE;
+    }
   }
 
-  $aspect = $info['height'] / $info['width'];
   if ($aspect < $height / $width) {
-    $width = (int)min($width, $info['width']);
-    $height = (int)round($width * $aspect);
+    $height = $width * $aspect;
   }
   else {
-    $height = (int)min($height, $info['height']);
-    $width = (int)round($height / $aspect);
+    $width = $height / $aspect;
   }
 
-  return image_toolkit_invoke('resize', array($source, $destination, $width, $height));
+  return image_resize($image, $width, $height);
 }
 
 /**
  * Resize an image to the given dimensions (ignoring aspect ratio).
  *
- * @param $source
- *   The file path of the source image.
- * @param $destination
- *   The file path of the destination image.
+ * @param $image
+ *   An image object returned by image_open().
  * @param $width
  *   The target width, in pixels.
  * @param $height
  *   The target height, in pixels.
-  * @return
+ * @param $toolkit
+ *   An optional override of the default image toolkit.
+ * @return
  *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
  */
-function image_resize($source, $destination, $width, $height) {
-  return image_toolkit_invoke('resize', array($source, $destination, $width, $height));
+function image_resize(stdClass $image, $width, $height) {
+  $width = (int) round($width);
+  $height = (int) round($height);
+
+  return image_toolkit_invoke('resize', array($image, $width, $height), $image->toolkit);
 }
 
 /**
  * Rotate an image by the given number of degrees.
  *
- * @param $source
- *   The file path of the source image.
- * @param $destination
- *   The file path of the destination image.
+ * @param $image
+ *   An image object returned by image_open().
  * @param $degrees
  *   The number of (clockwise) degrees to rotate the image.
  * @param $background
  *   An hexadecimal 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.
+ *   0xff00ff for magenta, and 0xffffff for white. For images that support
+ *   transparency, this will default to transparent. Otherwise it will
+ *   be white.
  * @return
  *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
  */
-function image_rotate($source, $destination, $degrees, $background = 0x000000) {
-  return image_toolkit_invoke('rotate', array($source, $destination, $degrees, $background));
+function image_rotate(stdClass $image, $degrees, $background = NULL) {
+  return image_toolkit_invoke('rotate', array($image, $degrees, $background));
 }
 
 /**
  * Crop an image to the rectangle specified by the given rectangle.
  *
- * @param $source
- *   The file path of the source image.
- * @param $destination
- *   The file path of the destination image.
+ * @param $image
+ *   An image object returned by image_open().
  * @param $x
- *   The top left co-ordinate, in pixels, of the crop area (x axis value).
+ *   The top left coordinate of the crop area (x axis value).
  * @param $y
- *   The top left co-ordinate, in pixels, of the crop area (y axis value).
+ *   The top left coordinate of the crop area (y axis value).
  * @param $width
  *   The target width, in pixels.
  * @param $height
  *   The target height, in pixels.
  * @return
  *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
+ * @see image_scale_and_crop()
+ */
+function image_crop(stdClass $image, $x, $y, $width, $height) {
+  $aspect = $image->info['height'] / $image->info['width'];
+  if (empty($height)) $height = $width / $aspect;
+  if (empty($width)) $width = $height * $aspect;
+
+  $width = (int) round($width);
+  $height = (int) round($height);
+
+  return image_toolkit_invoke('crop', array($image, $x, $y, $width, $height), $image->toolkit);
+}
+
+/**
+ * Convert an image to grayscale.
+ *
+ * @param $image
+ *   An image object returned by image_open().
+ * @return
+ *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
+ */
+function image_desaturate(stdClass $image) {
+  return image_toolkit_invoke('desaturate', array($image), $image->toolkit);
+}
+
+
+/**
+ * Open an image file and return an image object.
+ *
+ * Any changes to the file are not saved until image_close() is called.
+ *
+ * @param $file
+ *   Path to an image file.
+ * @param $toolkit
+ *   An optional, image toolkit name to override the default.
+ * @return
+ *   An image object or FALSE if there was a problem opening the file. The
+ *   image object has the following properties:
+ *    - 'source' - The original file path.
+ *    - 'info' - The array of information returned by image_get_info()
+ *    - 'toolkit' - The name of the image toolkit requested when the image was
+ *      opened.
+ *   Image tookits may add additional properties. The caller is advised not to
+ *   monkey about with them.
+ *
+ * @see image_close()
+ * @see image_get_info()
+ */
+function image_open($file, $toolkit = FALSE) {
+  if (!$toolkit) {
+    $toolkit = image_get_toolkit();
+  }
+  if ($toolkit) {
+    $image = new stdClass();
+    $image->source = $file;
+    $image->info = image_get_info($file);
+    $image->toolkit = $toolkit;
+    if ($image = image_toolkit_invoke('open', array($image), $toolkit)) {
+      return $image;
+    }
+  }
+  return FALSE;
+}
+
+/**
+ * Close the image and save the changes to a file.
+ *
+ * @param $image
+ *   An image object returned by image_open(). The object's 'info' property
+ *   will be updated if the file is saved successfully.
+ * @param $destination
+ *   Destination path where the image should be saved. If it is empty the
+ *   original image file will be overwritten.
+ * @return
+ *   TRUE or FALSE, based on success.
+ *
+ * @see image_open()
  */
-function image_crop($source, $destination, $x, $y, $width, $height) {
-  return image_toolkit_invoke('crop', array($source, $destination, $x, $y, $width, $height));
+function image_close(stdClass $image, $destination = NULL) {
+  if (empty($destination)) {
+    $destination = $image->source;
+  }
+  if ($return = image_toolkit_invoke('close', array($image, $destination), $image->toolkit)) {
+    // Clear the cached file size and refresh the image information.
+    clearstatcache();
+    $image->info = image_get_info($destination);
+
+    if (@chmod($destination, 0664)) {
+      return $return;
+    }
+    watchdog('image', 'Could not set permissions on destination file: %file', array('%file' => $destination));
+  }
+  return FALSE;
 }
 
 /**
Index: modules/simpletest/tests/image.test
===================================================================
RCS file: modules/simpletest/tests/image.test
diff -N modules/simpletest/tests/image.test
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ modules/simpletest/tests/image.test	1 Jan 1970 00:00:00 -0000
@@ -0,0 +1,265 @@
+<?php
+// $Id: form.test,v 1.3 2009/01/28 07:43:26 webchick Exp $
+
+/**
+ * @file
+ * Unit tests for the Drupal Form API.
+ */
+
+
+/**
+ * Base class for image manipulation testing.
+ */
+class ImageTestCase extends DrupalWebTestCase {
+  // Colors that are used in testing.
+  protected $black       = array(0, 0, 0, 0);
+  protected $red         = array(255, 0, 0, 0);
+  protected $green       = array(0, 255, 0, 0);
+  protected $blue        = array(0, 0, 255, 0);
+  protected $yellow      = array(255, 255, 0, 0);
+  protected $fuchsia     = array(255, 0, 255, 0); // Used as background colors.
+  protected $transparent = array(0, 0, 0, 127);
+  protected $white       = array(255, 255, 255, 0);
+
+  protected $width = 40;
+  protected $height = 20;
+
+  /**
+   * Function to compare two colors by RGBa.
+   */
+  function colorsAreEqual($color_a, $color_b) {
+    // Fully transparent pixels are equal, regardless of RGB.
+    if ($color_a[3] == 127 && $color_b[3] == 127) {
+      return TRUE;
+    }
+
+    foreach ($color_a as $key => $value) {
+      if ($color_b[$key] != $value) {
+        return FALSE;
+      }
+    }
+
+    return TRUE;
+  }
+
+}
+
+/**
+ * Test the core image manipulation functions.
+ */
+class ImageManipulateTestCase extends ImageTestCase {
+  function getInfo() {
+    return array(
+      'name' => t('Image manipulation tests'),
+      'description' => t('Check that core image manipulations work properly: scale, resize, rotate, crop, scale and crop, and desaturate.'),
+      'group' => t('Image API'),
+    );
+  }
+
+  /**
+   * Function for finding a pixel's RGBa values.
+   */
+  function getPixelColor($image, $x, $y) {
+    $color_index = imagecolorat($image->resource, $x, $y);
+
+    $transparent_index = imagecolortransparent($image->resource);
+    if ($color_index == $transparent_index) {
+      return array(0, 0, 0, 127);
+    }
+
+    return array_values(imagecolorsforindex($image->resource, $color_index));
+  }
+
+  /**
+   * Since PHP can't visually check that our images have been manipulated
+   * properly, build a list of expected color values for each of the corners and
+   * the expected height and widths for the final images.
+   */
+  function testGdManipulations() {
+    // If GD isn't available don't bother testing this.
+    if (!drupal_function_exists('image_gd_check_settings') || !image_gd_check_settings()) {
+      return;
+    }
+
+    // Typically the corner colors will be unchanged. These colors are in the
+    // order of top-left, top-right, bottom-right, bottom-left.
+    $default_corners = array($this->red, $this->green, $this->blue, $this->transparent);
+
+    // A list of files that will be tested.
+    $files = array(
+      'image-test.png',
+      'image-test.gif',
+      'image-test.jpg',
+    );
+
+    // Setup a list of tests to perform on each type.
+    $operations = array(
+      'resize' => array(
+        'function' => 'resize',
+        'arguments' => array(20, 10),
+        'width' => 20,
+        'height' => 10,
+        'corners' => $default_corners,
+      ),
+      'scale_x' => array(
+        'function' => 'scale',
+        'arguments' => array(20, NULL),
+        'width' => 20,
+        'height' => 10,
+        'corners' => $default_corners,
+      ),
+      'scale_y' => array(
+        'function' => 'scale',
+        'arguments' => array(NULL, 10),
+        'width' => 20,
+        'height' => 10,
+        'corners' => $default_corners,
+      ),
+      'upscale_x' => array(
+        'function' => 'scale',
+        'arguments' => array(80, NULL, TRUE),
+        'width' => 80,
+        'height' => 40,
+        'corners' => $default_corners,
+      ),
+      'upscale_y' => array(
+        'function' => 'scale',
+        'arguments' => array(NULL, 40, TRUE),
+        'width' => 80,
+        'height' => 40,
+        'corners' => $default_corners,
+      ),
+      'crop' => array(
+        'function' => 'crop',
+        'arguments' => array(12, 4, 16, 12),
+        'width' => 16,
+        'height' => 12,
+        'corners' => array_fill(0, 4, $this->white),
+      ),
+      'scale_and_crop' => array(
+        'function' => 'scale_and_crop',
+        'arguments' => array(10, 8),
+        'width' => 10,
+        'height' => 8,
+        'corners' => array_fill(0, 4, $this->black),
+      ),
+      'rotate_5' => array(
+        'function' => 'rotate',
+        'arguments' => array(5, 0xFF00FF), // Fuchsia background.
+        'width' => 42,
+        'height' => 24,
+        'corners' => array_fill(0, 4, $this->fuchsia),
+      ),
+      'rotate_90' => array(
+        'function' => 'rotate',
+        'arguments' => array(90, 0xFF00FF), // Fuchsia background.
+        'width' => 20,
+        'height' => 40,
+        'corners' => array($this->fuchsia, $this->red, $this->green, $this->blue),
+      ),
+      'rotate_transparent_5' => array(
+        'function' => 'rotate',
+        'arguments' => array(5),
+        'width' => 42,
+        'height' => 24,
+        'corners' => array_fill(0, 4, $this->transparent),
+      ),
+      'rotate_transparent_90' => array(
+        'function' => 'rotate',
+        'arguments' => array(90),
+        'width' => 20,
+        'height' => 40,
+        'corners' => array($this->transparent, $this->red, $this->green, $this->blue),
+      ),
+      'desaturate' => array(
+        'function' => 'desaturate',
+        'arguments' => array(),
+        'height' => 20,
+        'width' => 40,
+        // Grayscale corners are a bit funky. Each of the corners are a shade of
+        // gray. The values of these were determined simply by looking at the
+        // final image to see what desaturated colors end up being.
+        'corners' => array(array_fill(0, 3, 76) + array(3 => 0), array_fill(0, 3, 149) + array(3 => 0), array_fill(0, 3, 29) + array(3 => 0), array_fill(0, 3, 0) + array(3 => 127)),
+      ),
+    );
+
+    foreach ($files as $file) {
+      foreach ($operations as $op => $values) {
+        // Open up a fresh image.
+        $image = image_open($this->originalFileDirectory . '/simpletest/' . $file, 'gd');
+        if (!$image) {
+          $this->fail(t('Could not open image %file.', array('%file' => $file)));
+          continue 2;
+        }
+
+        // Transparent GIFs and the imagefilter function don't work together.
+        // There is a todo in image.gd.inc to correct this.
+        if ($image->info['extension'] == 'gif') {
+          if ($op == 'desaturate') {
+            $values['corners'][3] = $this->white;
+          }
+        }
+
+        // Perform our operation.
+        $function = 'image_'. $values['function'];
+        $arguments = array();
+        $arguments[] = &$image;
+        $arguments = array_merge($arguments, $values['arguments']);
+        call_user_func_array($function, $arguments);
+
+        // To keep from flooding the test with assert values, make a general value
+        // for whether each group of values fail.
+        $correct_dimensions_real = TRUE;
+        $correct_dimensions_object = TRUE;
+        $correct_colors = TRUE;
+
+        // Check the real dimensions of the image first.
+        if (imagesy($image->resource) != $values['height'] || imagesx($image->resource) != $values['width']) {
+          $correct_dimensions_real = FALSE;
+        }
+
+        // Check that the image object has an accurate record of the dimensions.
+        if ($image->info['width'] != $values['width'] || $image->info['height'] != $values['height']) {
+          $correct_dimensions_object = FALSE;
+        }
+        // Now check each of the corners to assure actions like rotate and
+        // desaturate had the proper actions apply.
+        foreach ($values['corners'] as $key => $corner) {
+          // Get the location of the corner.
+          switch ($key) {
+            case 0:
+              $x = 0;
+              $y = 0;
+              break;
+            case 1:
+              $x = $values['width'] - 1;
+              $y = 0;
+              break;
+            case 2:
+              $x = $values['width'] - 1;
+              $y = $values['height'] - 1;
+              break;
+            case 3:
+              $x = 0;
+              $y = $values['height'] - 1;
+              break;
+          }
+          $color = $this->getPixelColor($image, $x, $y);
+          $correct_colors = $this->colorsAreEqual($color, $corner);
+        }
+
+        $directory = file_directory_path() . '/imagetests';
+        file_check_directory($directory, FILE_CREATE_DIRECTORY);
+        image_close($image,$directory . '/' . $op . '.' . $image->info['extension']);
+
+        $this->assertTrue($correct_dimensions_real, t('Image %file after %action action has proper dimensions.', array('%file' => $file, '%action' => $op)));
+        $this->assertTrue($correct_dimensions_object, t('Image %file object after %action action is reporting the proper height and width values.', array('%file' => $file, '%action' => $op)));
+        // JPEG colors will always be messed up due to compression.
+        if ($image->info['extension'] != 'jpg') {
+          $this->assertTrue($correct_colors, t('Image %file object after %action action has the correct color placement.', array('%file' => $file, '%action' => $op)));
+        }
+      }
+    }
+
+  }
+}