fImage.php

<?php
/**
 * Represents an image on the filesystem, also provides image manipulation functionality
 *
 * @copyright  Copyright (c) 2007-2011 Will Bond, others
 * @author     Will Bond [wb] <will@flourishlib.com>
 * @author     Will Bond, iMarc LLC [wb-imarc] <will@imarc.net>
 * @author     Jeff Turcotte, iMarc LLC [jt] <jeff@imarc.net>
 * @license    http://flourishlib.com/license
 *
 * @package    Flourish
 * @link       http://flourishlib.com/fImage
 *
 */
class fImage extends fFile
{
	// The following constants allow for nice looking callbacks to static methods
	const create                  = 'fImage::create';
	const getCompatibleMimetypes  = 'fImage::getCompatibleMimetypes';
	const isImageCompatible       = 'fImage::isImageCompatible';
	const reset                   = 'fImage::reset';
	const setImageMagickDirectory = 'fImage::setImageMagickDirectory';
	const setImageMagickTempDir   = 'fImage::setImageMagickTempDir';


	/**
	 * Enable or disable the exif image type check
	 *
	 * @var boolean
	 */
	static private $exif_image_type_check = true;

	/**
	 * If we are using the ImageMagick processor, this stores the path to the binaries
	 *
	 * @var string
	 */
	static private $imagemagick_dir = NULL;

	/**
	 * A custom tmp path to use for ImageMagick
	 *
	 * @var string
	 */
	static private $imagemagick_temp_dir = NULL;

	/**
	 * The version of ImageMagick
	 *
	 * @var string
	 */
	static private $imagemagick_version = NULL;

	/**
	 * The processor to use for the image manipulation
	 *
	 * @var string
	 */
	static private $processor = NULL;


	/**
	 * Checks to make sure we can get to and execute the ImageMagick convert binary
	 *
	 * @param  string $path  The path to ImageMagick on the filesystem
	 * @return void
	 */
	static private function checkImageMagickBinary($path)
	{
		// Make sure we can execute the convert binary
		if (self::isSafeModeExecDirRestricted($path)) {
			throw new fEnvironmentException(
				'Safe mode is turned on and the ImageMagick convert binary is not in the directory defined by the safe_mode_exec_dir ini setting or safe_mode_exec_dir is not set - safe_mode_exec_dir is currently %s.',
				ini_get('safe_mode_exec_dir')
			);
		}

		$binary = $path . (fCore::checkOS('windows') ? 'convert.exe' : 'convert');

		if (self::isOpenBaseDirRestricted($path)) {
			exec($binary . ' -version', $executable);
		} else {
			$executable = is_executable($binary);
		}

		if (!$executable) {
			throw new fEnvironmentException(
				'The ImageMagick convert binary located in the directory %s does not exist or is not executable',
				$path
			);
		}

		// determine version
		exec($binary, $output);
		if (preg_match('/\d+\.\d+\.\d+/', $output[0], $matches)) {
			self::$imagemagick_version = $matches[0];
		}
	}


	/**
	 * Creates an image on the filesystem and returns an object representing it
	 *
	 * This operation will be reverted by a filesystem transaction being rolled
	 * back.
	 *
	 * @throws fValidationException  When no image was specified or when the image already exists
	 *
	 * @param  string $file_path  The path to the new image
	 * @param  string $contents   The contents to write to the image
	 * @return fImage
	 */
	static public function create($file_path, $contents)
	{
		if (empty($file_path)) {
			throw new fValidationException('No filename was specified');
		}

		if (file_exists($file_path)) {
			throw new fValidationException(
				'The image specified, %s, already exists',
				$file_path
			);
		}

		$directory = fFilesystem::getPathInfo($file_path, 'dirname');
		if (!is_writable($directory)) {
			throw new fEnvironmentException(
				'The file path specified, %s, is inside of a directory that is not writable',
				$file_path
			);
		}

		file_put_contents($file_path, $contents);

		$image = new fImage($file_path);

		fFilesystem::recordCreate($image);

		return $image;
	}


	/**
	 * Determines what processor to use for image manipulation
	 *
	 * @return void
	 */
	static public function determineProcessor()
	{
		// Determine what processor to use
		if (self::$processor === NULL) {

			// Look for imagemagick first since it can handle more than GD
			try {

				// If exec is disabled we can't use imagemagick
				if (in_array('exec', array_map('trim', explode(',', ini_get('disable_functions'))))) {
					throw new Exception();
				}

				if (fCore::checkOS('windows')) {

						$win_search = 'dir /B "C:\Program Files\ImageMagick*" 2> NUL';
						exec($win_search, $win_output);
						$win_output = trim(join("\n", $win_output));

						if (!$win_output || stripos($win_output, 'File not found') !== FALSE) {
							throw new Exception();
						}

						$path = 'C:\\Program Files\\' . $win_output . '\\';

				} elseif (fCore::checkOS('linux', 'bsd', 'solaris', 'osx', 'aix')) {

					$found = FALSE;

					if (fCore::checkOS('solaris')) {
						$locations = array(
							'/opt/local/bin/',
							'/opt/bin/',
							'/opt/csw/bin/'
						);

					} else {
						$locations = array(
							'/usr/local/bin/',
							'/usr/bin/'
						);
					}

					foreach($locations as $location) {
						if (self::isSafeModeExecDirRestricted($location)) {
							continue;
						}
						if (self::isOpenBaseDirRestricted($location)) {
							exec($location . 'convert -version', $output);
							if ($output) {
								$found = TRUE;
								$path  = $location;
								break;
							}
						} elseif (is_executable($location . 'convert')) {
							$found = TRUE;
							$path  = $location;
							break;
						}
					}

					// We have no fallback in solaris
					if (!$found && fCore::checkOS('solaris')) {
						throw new Exception();
					}


					if (!$found && fCore::checkOS('linux', 'freebsd', 'aix')) {
						$nix_search = 'whereis -b convert';
						exec($nix_search, $nix_output);
						$nix_output = trim(str_replace('convert:', '', join("\n", $nix_output)));

						if (!$nix_output) {
							throw new Exception();
						}

						$path = preg_replace('#^(.*)convert$#i', '\1', $nix_output);
					}

					if (!$found && fCore::checkOS('osx', 'netbsd', 'openbsd')) {
						$osx_search = 'whereis convert';
						exec($osx_search, $osx_output);
						$osx_output = trim(join("\n", $osx_output));

						if (!$osx_output) {
							throw new Exception();
						}

						if (preg_match('#^(.*)convert#i', $osx_output, $matches)) {
							$path = $matches[1];
						}
					}

				} else {
					$path = NULL;
				}

				self::checkImageMagickBinary($path);

				self::$imagemagick_dir = $path;
				self::$processor = 'imagemagick';

			} catch (Exception $e) {

				// Look for GD last since it does not support tiff files
				if (function_exists('gd_info')) {

					self::$processor = 'gd';

				} else {
					self::$processor = 'none';
				}
			}
		}
	}

	/**
	 * Returns an array of acceptable mime types for the processor that was detected
	 *
	 * @internal
	 *
	 * @return array  The mime types that the detected image processor can manipulate
	 */
	static public function getCompatibleMimetypes()
	{
		self::determineProcessor();

		$mimetypes = array('image/gif', 'image/jpeg', 'image/pjpeg', 'image/png');

		if (self::$processor == 'imagemagick') {
			$mimetypes[] = 'image/tiff';
		}

		return $mimetypes;
	}


	/**
	 * Gets the dimensions and type of an image stored on the filesystem
	 *
	 * The `'type'` key will have one of the following values:
	 *
	 *  - `{null}` (File type is not supported)
	 *  - `'jpg'`
	 *  - `'gif'`
	 *  - `'png'`
	 *  - `'tif'`
	 *
	 * @throws fValidationException  When the file specified is not an image
	 *
	 * @param  string $image_path  The path to the image to get stats for
	 * @param  string $element     The element to retrieve: `'type'`, `'width'`, `'height'`
	 * @return mixed  An associative array: `'type' => {mixed}, 'width' => {integer}, 'height' => {integer}`, or the element specified
	 */
	static protected function getInfo($image_path, $element=NULL)
	{
		$extension = strtolower(fFilesystem::getPathInfo($image_path, 'extension'));
		if (!in_array($extension, array('jpg', 'jpeg', 'png', 'gif', 'tif', 'tiff'))) {
			$type = self::getImageType($image_path);
			if ($type === NULL) {
				throw new fValidationException(
					'The file specified, %s, does not appear to be an image',
					$image_path
				);
			}
		}

		fCore::startErrorCapture(E_WARNING);
		$image_info = getimagesize($image_path);
		fCore::stopErrorCapture();

		if ($image_info == FALSE) {
			throw new fValidationException(
				'The file specified, %s, is not an image',
				$image_path
			);
		}

		$valid_elements = array('type', 'width', 'height');
		if ($element !== NULL && !in_array($element, $valid_elements)) {
			throw new fProgrammerException(
				'The element specified, %1$s, is invalid. Must be one of: %2$s.',
				$element,
				join(', ', $valid_elements)
			);
		}

		$types = array(IMAGETYPE_GIF     => 'gif',
					   IMAGETYPE_JPEG    => 'jpg',
					   IMAGETYPE_PNG     => 'png',
					   IMAGETYPE_TIFF_II => 'tif',
					   IMAGETYPE_TIFF_MM => 'tif');

		$output           = array();
		$output['width']  = $image_info[0];
		$output['height'] = $image_info[1];
		if (isset($types[$image_info[2]])) {
			$output['type'] = $types[$image_info[2]];
		} else {
			$output['type'] = NULL;
		}

		if ($element !== NULL) {
			return $output[$element];
		}

		return $output;
	}


	/**
	 * Gets the image type from a file by looking at the file contents
	 *
	 * @param  string $image  The image path to get the type for
	 * @return string|NULL  The type of the image - `'jpg'`, `'gif'`, `'png'` or `'tif'` - NULL if not one of those
	 */
	static private function getImageType($image)
	{
		if (self::$exif_image_type_check === false) {
			$extension = pathinfo($image, PATHINFO_EXTENSION);

			if (in_array($extension, ['jpg', 'jpeg', 'tif', 'tiff', 'png', 'gif'])) {
				return $extension;
			}

			return null;
		}

		if (function_exists('exif_imagetype')) {
			fCore::startErrorCapture();
			$type = exif_imagetype($image);
			fCore::stopErrorCapture();

			if ($type === IMAGETYPE_JPEG) {
				return 'jpg';
			}

			if ($type === IMAGETYPE_TIFF_II || $type === IMAGETYPE_TIFF_MM) {
				return 'tif';
			}

			if ($type === IMAGETYPE_PNG) {
				return 'png';
			}

			if ($type === IMAGETYPE_GIF) {
				return 'gif';
			}
		}

		// Fall back to legacy image detection.

		$handle   = fopen($image, 'r');
		$contents = fread($handle, 32);
		fclose($handle);

		$_0_8  = substr($contents, 0, 8);
		$_0_4  = substr($contents, 0, 4);
		$_6_4  = substr($contents, 6, 4);
		$_20_4 = substr($contents, 20, 4);

		if ($_0_4 == "MM\x00\x2A" || $_0_4 == "II\x2A\x00") {
			return 'tif';
		}

		if ($_0_8 == "\x89PNG\x0D\x0A\x1A\x0A") {
			return 'png';
		}

		if ($_0_4 == 'GIF8') {
			return 'gif';
		}

		if ($_6_4 == 'JFIF' || $_6_4 == 'Exif' || ($_0_4 == "\xFF\xD8\xFF\xED" && $_20_4 == "8BIM")) {
			return 'jpg';
		}

		return NULL;
	}


	/**
	 * Checks to make sure the class can handle the image file specified
	 *
	 * @internal
	 *
	 * @throws fValidationException  When the image specified does not exist
	 *
	 * @param  string $image  The image to check for incompatibility
	 * @return boolean  If the image is compatible with the detected image processor
	 */
	static public function isImageCompatible($image)
	{
		self::determineProcessor();

		if (!file_exists($image)) {
			throw new fValidationException(
				'The image specified, %s, does not exist',
				$image
			);
		}

		$type = self::getImageType($image);

		if ($type === NULL || ($type == 'tif' && self::$processor == 'gd')) {
			return FALSE;
		}

		return TRUE;
	}


	/**
	 * Checks if the path specified is restricted by open basedir
	 *
	 * @param  string $path  The path to check
	 * @return boolean  If the path is restricted by the `open_basedir` ini setting
	 */
	static private function isOpenBaseDirRestricted($path)
	{
		if (ini_get('open_basedir')) {
			$open_basedirs = explode((fCore::checkOS('windows')) ? ';' : ':', ini_get('open_basedir'));
			$found = FALSE;

			foreach ($open_basedirs as $open_basedir) {
				if (strpos($path, $open_basedir) === 0) {
					$found = TRUE;
				}
			}

			if (!$found) {
				return TRUE;
			}
		}

		return FALSE;
	}


	/**
	 * Checks if the path specified is restricted by the safe mode exec dir restriction
	 *
	 * @param  string $path  The path to check
	 * @return boolean  If the path is restricted by the `safe_mode_exec_dir` ini setting
	 */
	static private function isSafeModeExecDirRestricted($path)
	{
		if (!in_array(strtolower(ini_get('safe_mode')), array('0', '', 'off'))) {
			$exec_dir = ini_get('safe_mode_exec_dir');
			if (!$exec_dir || stripos($path, $exec_dir) === FALSE) {
				return TRUE;
			}
		}
		return FALSE;
	}


	/**
	 * Resets the configuration of the class
	 *
	 * @internal
	 *
	 * @return void
	 */
	static public function reset()
	{
		self::$imagemagick_dir      = NULL;
		self::$imagemagick_temp_dir = NULL;
		self::$processor            = NULL;
	}


	/**
	 * Set whether or not to do exif imagetype checks
	 *
	 * @param boolean
	 */
	 static public function setExifTypeCheck($check = true)
	 {
		 return self::$exif_image_type_check = $check;
	 }


	/**
	 * Sets the directory the ImageMagick binary is installed in and tells the class to use ImageMagick even if GD is installed
	 *
	 * @param  string $directory  The directory ImageMagick is installed in
	 * @return void
	 */
	static public function setImageMagickDirectory($directory)
	{
		$directory = fDirectory::makeCanonical($directory);

		self::checkImageMagickBinary($directory);

		self::$imagemagick_dir = $directory;
		self::$processor = 'imagemagick';
	}


	/**
	 * Sets a custom directory to use for the ImageMagick temporary files
	 *
	 * @param  string $temp_dir  The directory to use for the ImageMagick temp dir
	 * @return void
	 */
	static public function setImageMagickTempDir($temp_dir)
	{
		$temp_dir = new fDirectory($temp_dir);
		if (!$temp_dir->isWritable()) {
			throw new fEnvironmentException(
				'The ImageMagick temp directory specified, %s, does not appear to be writable',
				$temp_dir->getPath()
			);
		}
		self::$imagemagick_temp_dir = $temp_dir->getPath();
	}


	/**
	 * The modifications to perform on the image when it is saved
	 *
	 * @var array
	 */
	private $pending_modifications = array();


	/**
	 * Creates an object to represent an image on the filesystem
	 *
	 * @throws fValidationException  When no image was specified, when the image does not exist or when the path specified is not an image
	 *
	 * @param  string  $file_path    The path to the image
	 * @param  boolean $skip_checks  If file checks should be skipped, which improves performance, but may cause undefined behavior - only skip these if they are duplicated elsewhere
	 * @return fImage
	 */
	public function __construct($file_path, $skip_checks=FALSE)
	{
		self::determineProcessor();

		parent::__construct($file_path, $skip_checks);

		if (!self::isImageCompatible($file_path)) {
			$valid_image_types = array('GIF', 'JPG', 'PNG');
			if (self::$processor == 'imagemagick') {
				$valid_image_types[] = 'TIF';
			}
			throw new fValidationException(
				'The image specified, %1$s, is not a valid %2$s file',
				$file_path,
				fGrammar::joinArray($valid_image_types, 'or')
			);
		}
	}


	/**
	 * Prevents a programmer from trying to append an image
	 *
	 * @param  mixed $data  The data to append to the image
	 * @return void
	 */
	public function append($data)
	{
		throw new fProgrammerException('It is not possible to append an image');
	}


	/**
	 * Crops the image by the exact pixel dimensions specified
	 *
	 * The crop does not occur until ::saveChanges() is called.
	 *
	 * @param  numeric        $new_width    The width in pixels to crop the image to
	 * @param  numeric        $new_height   The height in pixels to crop the image to
	 * @param  numeric|string $crop_from_x  The number of pixels from the left of the image to start the crop from, or a horizontal position of `'left'`, `'center'` or `'right'`
	 * @param  numeric|string $crop_from_y  The number of pixels from the top of the image to start the crop from, or a vertical position of `'top'`, `'center'` or `'bottom'`
	 * @return fImage  The image object, to allow for method chaining
	 */
	public function crop($new_width, $new_height, $crop_from_x, $crop_from_y)
	{
		$this->tossIfDeleted();

		// Get the original dimensions for our parameter checking
		$dim = $this->getCurrentDimensions();
		$orig_width  = $dim['width'];
		$orig_height = $dim['height'];

		if (is_string($crop_from_x) && !is_numeric($crop_from_x)) {
			switch (strtolower($crop_from_x)) {
				case 'left':
					$crop_from_x = 0;
					break;
				case 'center':
					$crop_from_x = floor(max($orig_width-$new_width, 0)/2);
					break;
				case 'right':
					$crop_from_x = max($orig_width-$new_width, 0);
					break;
				default:
					throw new fProgrammerException(
						'The crop-from x specified, %1$s, is not a valid horizontal position. Must be one of: %2$s.',
						$crop_from_x,
						array('left', 'center', 'right')
					);
			}
		}

		if (is_string($crop_from_y) && !is_numeric($crop_from_y)) {
			switch (strtolower($crop_from_y)) {
				case 'top':
					$crop_from_y = 0;
					break;
				case 'center':
					$crop_from_y = floor(max($orig_height-$new_height, 0)/2);
					break;
				case 'bottom':
					$crop_from_y = max($orig_height-$new_height, 0);
					break;
				default:
					throw new fProgrammerException(
						'The crop-from y specified, %1$s, is not a valid vertical position. Must be one of: %2$s.',
						$crop_from_y,
						array('top', 'center', 'bottom')
					);
			}
		}

		// Make sure the user input is valid
		if (!is_numeric($crop_from_x) || $crop_from_x < 0 || $crop_from_x > $orig_width - 1) {
			throw new fProgrammerException(
				'The crop-from x specified, %s, is not a number, is less than zero, or would result in a zero-width image',
				$crop_from_x
			);
		}
		if (!is_numeric($crop_from_y) || $crop_from_y < 0 || $crop_from_y > $orig_height - 1) {
			throw new fProgrammerException(
				'The crop-from y specified, %s, is not a number, is less than zero, or would result in a zero-height image',
				$crop_from_y
			);
		}

		if (!is_numeric($new_width) || $new_width <= 0 || $crop_from_x + $new_width > $orig_width) {
			throw new fProgrammerException(
				'The new width specified, %1$s, is not a number, is less than or equal to zero, or is larger than can be cropped with the specified crop-from x of %2$s',
				$new_width,
				$crop_from_x
			);
		}
		if (!is_numeric($new_height) || $new_height <= 0 || $crop_from_y + $new_height > $orig_height) {
			throw new fProgrammerException(
				'The new height specified, %1$s, is not a number, is less than or equal to zero, or is larger than can be cropped with the specified crop-from y of %2$s',
				$new_height,
				$crop_from_y
			);
		}

		// If nothing changed, don't even record the modification
		if ($orig_width == $new_width && $orig_height == $new_height) {
			return $this;
		}

		// Record what we are supposed to do
		$this->pending_modifications[] = array(
			'operation'  => 'crop',
			'start_x'    => $crop_from_x,
			'start_y'    => $crop_from_y,
			'width'      => $new_width,
			'height'     => $new_height,
			'old_width'  => $orig_width,
			'old_height' => $orig_height
		);

		return $this;
	}


	/**
	 * Crops the biggest area possible from the center of the image that matches the ratio provided
	 *
	 * The crop does not occur until ::saveChanges() is called.
	 *
	 * @param  numeric $ratio_width          The width ratio to crop the image to
	 * @param  numeric $ratio_height         The height ratio to crop the image to
	 * @param  string  $horizontal_position  A horizontal position of `'left'`, `'center'` or `'right'`
	 * @param  string  $vertical_position    A vertical position of `'top'`, `'center'` or `'bottom'`
	 * @return fImage  The image object, to allow for method chaining
	 */
	public function cropToRatio($ratio_width, $ratio_height, $horizontal_position='center', $vertical_position='center')
	{
		$this->tossIfDeleted();

		// Make sure the user input is valid
		if ((!is_numeric($ratio_width) && $ratio_width !== NULL) || $ratio_width < 0) {
			throw new fProgrammerException(
				'The ratio width specified, %s, is not a number or is less than or equal to zero',
				$ratio_width
			);
		}
		if ((!is_numeric($ratio_height) && $ratio_height !== NULL) || $ratio_height < 0) {
			throw new fProgrammerException(
				'The ratio height specified, %s, is not a number or is less than or equal to zero',
				$ratio_height
			);
		}


		// Make sure
		$valid_horizontal_positions = array('left', 'center', 'right');
		if (!in_array(strtolower($horizontal_position), $valid_horizontal_positions)) {
			throw new fProgrammerException(
				'The horizontal position specified, %1$s, is not valid. Must be one of: %2$s.',
				$horizontal_position,
				$valid_horizontal_positions
			);
		}

		$valid_vertical_positions = array('top', 'center', 'bottom');
		if (!in_array(strtolower($vertical_position), $valid_vertical_positions)) {
			throw new fProgrammerException(
				'The vertical position specified, %1$s, is not valid. Must be one of: %2$s.',
				$vertical_position,
				$valid_vertical_positions
			);
		}

		// Get the new dimensions
		$dim = $this->getCurrentDimensions();
		$orig_width  = $dim['width'];
		$orig_height = $dim['height'];

		$orig_ratio = $orig_width / $orig_height;
		$new_ratio  = $ratio_width / $ratio_height;

		if ($orig_ratio > $new_ratio) {
			$new_height = $orig_height;
			$new_width  = round($new_ratio * $new_height);
		} else {
			$new_width  = $orig_width;
			$new_height = round($new_width / $new_ratio);
		}

		return $this->crop($new_width, $new_height, $horizontal_position, $vertical_position);
	}


	/**
	 * Converts the image to grayscale
	 *
	 * Desaturation does not occur until ::saveChanges() is called.
	 *
	 * @return fImage  The image object, to allow for method chaining
	 */
	public function desaturate()
	{
		$this->tossIfDeleted();

		$dim = $this->getCurrentDimensions();

		// Record what we are supposed to do
		$this->pending_modifications[] = array(
			'operation'  => 'desaturate',
			'width'      => $dim['width'],
			'height'     => $dim['height'],
			'old_width'  => $dim['width'],
			'old_height' => $dim['height']
		);

		return $this;
	}


	/**
	 * Gets the dimensions of the image as of the last modification
	 *
	 * @return array  An associative array: `'width' => {integer}, 'height' => {integer}`
	 */
	private function getCurrentDimensions()
	{
		if (empty($this->pending_modifications)) {
			$output = self::getInfo($this->file);
			unset($output['type']);

		} else {
			$last_modification = $this->pending_modifications[sizeof($this->pending_modifications)-1];
			$output['width']  = $last_modification['width'];
			$output['height'] = $last_modification['height'];
		}

		return $output;
	}


	/**
	 * Returns the width and height of the image as a two element array
	 *
	 * @return array  In the format `0 => (integer) {width}, 1 => (integer) {height}`
	 */
	public function getDimensions()
	{
		$info = self::getInfo($this->file);
		return array($info['width'], $info['height']);
	}


	/**
	 * Returns the height of the image
	 *
	 * @return integer  The height of the image in pixels
	 */
	public function getHeight()
	{
		return self::getInfo($this->file, 'height');
	}


	/**
	 * Returns the type of the image
	 *
	 * @return string  The type of the image: `'jpg'`, `'gif'`, `'png'`, `'tif'`
	 */
	public function getType()
	{
		return self::getImageType($this->file);
	}


	/**
	 * Returns the width of the image
	 *
	 * @return integer  The width of the image in pixels
	 */
	public function getWidth()
	{
		return self::getInfo($this->file, 'width');
	}


	/**
	 * Checks if the current image is an animated gif
	 *
	 * @return boolean  If the image is an animated gif
	 */
	private function isAnimatedGif()
	{
		$type = self::getImageType($this->file);
		if ($type == 'gif') {
			if (preg_match('#\x00\x21\xF9\x04.{4}\x00\x2C#s', file_get_contents($this->file))) {
				return TRUE;
			}
		}
		return FALSE;
	}


	/**
	 * Processes the current image using GD
	 *
	 * @param  string  $output_file   The file to save the image to
	 * @param  integer $jpeg_quality  The JPEG quality to use
	 * @return void
	 */
	private function processWithGD($output_file, $jpeg_quality)
	{
		$type       = self::getImageType($this->file);
		$save_alpha = FALSE;

		$path_info = fFilesystem::getPathInfo($output_file);
		$new_type  = $path_info['extension'];
		$new_type  = ($type == 'jpeg') ? 'jpg' : $type;

		if (!in_array($new_type, array('gif', 'jpg', 'png'))) {
			$new_type = $type;
		}

		if (ini_get('memory_limit') != '-1') {
			// We will estimate memory usage at 3MB if we can't actually check it
			$beginning_memory_usage = 3145728;
			if (function_exists('memory_get_usage')) {
				$beginning_memory_usage = memory_get_usage();
			}
			$memory_limit_bytes = fFilesystem::convertToBytes(ini_get('memory_limit'));

			// Estimate the memory usage and throw an exception if we will run out
			$load_byte_usage = $this->pending_modifications[0]['old_width'] * $this->pending_modifications[0]['old_height'] * 4;
			if ($load_byte_usage + $beginning_memory_usage > $memory_limit_bytes) {
				throw new fEnvironmentException(
					'The predicted memory usage to complete the image modifications using the GD extension, %1$s, will most likely exceed the memory limit of %2$s',
					$load_byte_usage + $beginning_memory_usage,
					$memory_limit_bytes
				);
			}
		}

		switch ($type) {
			case 'gif':
				$gd_res = imagecreatefromgif($this->file);
				$save_alpha = TRUE;
				break;
			case 'jpg':
				$gd_res = imagecreatefromjpeg($this->file);
				break;
			case 'png':
				$gd_res = imagecreatefrompng($this->file);
				$save_alpha = TRUE;
				break;
		}


		foreach ($this->pending_modifications as $num => $mod) {

			if (ini_get('memory_limit') != '-1') {
				$old_byte_usage = $this->pending_modifications[0]['old_width'] * $this->pending_modifications[0]['old_height'] * 4;
				$new_byte_usage = $this->pending_modifications[0]['width'] * $this->pending_modifications[0]['height'] * 4;
				if ($old_byte_usage + $new_byte_usage + $beginning_memory_usage > $memory_limit_bytes) {
					throw new fEnvironmentException(
						'The predicted memory usage to complete the image modifications using the GD extension, %1$s, will most likely exceed the memory limit of %2$s',
						$old_byte_usage + $new_byte_usage + $beginning_memory_usage,
						$memory_limit_bytes
					);
				}
			}

			$new_gd_res = imagecreatetruecolor($mod['width'], $mod['height']);
			if ($save_alpha) {
				imagealphablending($new_gd_res, FALSE);
				imagesavealpha($new_gd_res, TRUE);
				if ($new_type == 'gif') {
					$transparent = imagecolorallocatealpha($new_gd_res, 255, 255, 255, 127);
					imagefilledrectangle($new_gd_res, 0, 0, $mod['width'], $mod['height'], $transparent);
					imagecolortransparent($new_gd_res, $transparent);
				}
			}

			// Perform the resize operation
			if ($mod['operation'] == 'resize') {

				imagecopyresampled($new_gd_res,       $gd_res,
								   0,                 0,
								   0,                 0,
								   $mod['width'],     $mod['height'],
								   $mod['old_width'], $mod['old_height']);

			// Perform the crop operation
			} elseif ($mod['operation'] == 'crop') {

				imagecopyresampled($new_gd_res,       $gd_res,
								   0,                 0,
								   $mod['start_x'],   $mod['start_y'],
								   $mod['width'],     $mod['height'],
								   $mod['width'],     $mod['height']);

			// Perform the desaturate operation
			} elseif ($mod['operation'] == 'desaturate') {

				// Create a palette of grays
				$grays = array();
				for ($i=0; $i < 256; $i++) {
					$grays[$i] = imagecolorallocate($new_gd_res, $i, $i, $i);
				}
				$transparent = imagecolorallocatealpha($new_gd_res, 255, 255, 255, 127);

				// Loop through every pixel and convert the rgb values to grays
				for ($x=0; $x < $mod['width']; $x++) {
					for ($y=0; $y < $mod['height']; $y++) {

						$color = imagecolorat($gd_res, $x, $y);
						if ($type != 'gif') {
							$red   = ($color >> 16) & 0xFF;
							$green = ($color >> 8) & 0xFF;
							$blue  = $color & 0xFF;
							if ($save_alpha) {
								$alpha = ($color >> 24) & 0x7F;
							}
						} else {
							$color_info = imagecolorsforindex($gd_res, $color);
							$red   = $color_info['red'];
							$green = $color_info['green'];
							$blue  = $color_info['blue'];
							$alpha = $color_info['alpha'];
						}

						if (!$save_alpha || $alpha != 127) {

							// Get the appropriate gray (http://en.wikipedia.org/wiki/YIQ)
							$yiq = round(($red * 0.299) + ($green * 0.587) + ($blue * 0.114));

							if (!$save_alpha || $alpha == 0) {
								$new_color = $grays[$yiq];
							} else {
								$new_color = imagecolorallocatealpha($new_gd_res, $yiq, $yiq, $yiq, $alpha);
							}

						} else {
							$new_color = $transparent;
						}

						imagesetpixel($new_gd_res, $x, $y, $new_color);
					}
				}

			// Perform the rotate operation
			} elseif ($mod['operation'] == 'rotate') {
				// The imagerotate() function is only available if the PHP-bundled
				// version of GD is used, which is not always the case (e.g. debian/ubuntu)
				if (function_exists('imagerotate')) {
					// For some reason imagerotate() seem to rotate counter-clockwise
					if ($mod['degrees'] == 90) {
						$mod['degrees'] = 270;
					} elseif ($mod['degrees'] == 270) {
						$mod['degrees'] = 90;
					}

					// If the source image is not true color, we need to convert
					// to a true color image first, otherwise imagerotate() fails
					// and returns false, causing no image to be saved
					if (imagecolorstotal($gd_res)) {
						imagecopy($new_gd_res, $gd_res, 0, 0, 0, 0, $mod['width'], $mod['height']);
						imagedestroy($gd_res);
						$gd_res = $new_gd_res;
						unset($new_gd_res);
					}

					$new_gd_res = imagerotate($gd_res, $mod['degrees'], -1);

					// If you don't set the alpha mode for PNG, images that
					// contain transparency and are rotated will be distored
					// in odd ways
					if ($new_type == 'png') {
						imagealphablending($new_gd_res, false);
						imagesavealpha($new_gd_res, true);
					}

				} else {
					switch ($mod['degrees']) {
						case 90:
				            for ($x=0; $x < $mod['width']; $x++) {
				                for ($y=0; $y < $mod['height']; $y++) {
				                    imagecopy($new_gd_res, $gd_res, $mod['height'] - $y - 1, $x, $x, $y, 1, 1);
								}
							}
				            break;

				        case 180:
				        	// Rather than copying one pixel at a time, like with 90
				        	// and 270 degrees, for 180 degrees we can copy one rpw
				        	// at a time for better performance
				            for ($x=0; $x < $mod['width']; $x++) {
				                imagecopy($new_gd_res, $gd_res, $mod['width'] - $x - 1, 0, $x, 0, 1, $mod['height']);
							}
				            $row = imagecreatetruecolor($mod['width'], 1);
				            for ($y=0; $y < $mod['height']/2; $y++) {
				                imagecopy($row, $new_gd_res, 0, 0, 0, $mod['height'] - $y - 1, $mod['width'], 1);
				                imagecopy($new_gd_res, $new_gd_res, 0, $mod['height'] - $y - 1, 0, $y, $mod['width'], 1);
				                imagecopy($new_gd_res, $row, 0, $y, 0, 0, $mod['width'], 1);
				            }
				            imagedestroy($row);
				            break;

				        case 270:
				            for ($x=0; $x < $mod['width']; $x++) {
				                for ($y=0; $y < $mod['height']; $y++) {
				                    imagecopy($new_gd_res, $gd_res, $y, $mod['width'] - $x - 1, $x, $y, 1, 1);
								}
							}
				            break;
					}
				}
			}

			imagedestroy($gd_res);

			$gd_res = $new_gd_res;
		}

		// Save the file
		switch ($new_type) {
			case 'gif':
				imagetruecolortopalette($gd_res, TRUE, 256);
				imagegif($gd_res, $output_file);
				break;
			case 'jpg':
				imagejpeg($gd_res, $output_file, $jpeg_quality);
				break;
			case 'png':
				imagepng($gd_res, $output_file);
				break;
		}

		imagedestroy($gd_res);
	}


	/**
	 * Processes the current image using ImageMagick
	 *
	 * @param  string  $output_file   The file to save the image to
	 * @param  integer $jpeg_quality  The JPEG quality to use
	 * @return void
	 */
	private function processWithImageMagick($output_file, $jpeg_quality)
	{
		$type = self::getImageType($this->file);
		if (fCore::checkOS('windows')) {
			$command_line  = str_replace(' ', '" "', self::$imagemagick_dir . 'convert.exe');
		} else {
			$command_line  = escapeshellarg(self::$imagemagick_dir . 'convert');
		}

		if (self::$imagemagick_temp_dir) {
			$command_line .= ' -set registry:temporary-path ' . escapeshellarg(self::$imagemagick_temp_dir) . ' ';
		}

		// Determining in what format the file is going to be saved
		$path_info = fFilesystem::getPathInfo($output_file);
		$new_type = $path_info['extension'];
		$new_type = ($new_type == 'jpeg') ? 'jpg' : $new_type;

		if (!in_array($new_type, array('gif', 'jpg', 'png'))) {
			$new_type = $type;
		}

		$file = $this->file;
		if ($type != 'gif' || $new_type != 'gif') {
			$file .= '[0]';
		}

		$command_line .= ' ' . escapeshellarg(str_replace('tif', 'tiff', $type) . ':' . $file) . ' ';

		// Animated gifs need to be coalesced
		if ($this->isAnimatedGif()) {
			$command_line .= ' -coalesce ';
		}

		// TIFF files should be set to a depth of 8
		if ($type == 'tif') {
			$command_line .= ' -depth 8 ';
		}

		foreach ($this->pending_modifications as $mod) {

			// Perform the resize operation
			if ($mod['operation'] == 'resize') {
				$command_line .= ' -resize "' . $mod['width'] . 'x' . $mod['height'];
				if ($mod['old_width'] < $mod['width'] || $mod['old_height'] < $mod['height']) {
					$command_line .= '<';
				}
				$command_line .= '" ';

			// Perform the crop operation
			} elseif ($mod['operation'] == 'crop') {
				$command_line .= ' -crop ' . $mod['width'] . 'x' . $mod['height'];
				$command_line .= '+' . $mod['start_x'] . '+' . $mod['start_y'];
				$command_line .= ' -repage ' . $mod['width'] . 'x' . $mod['height'] . '+0+0 ';

			// Perform the desaturate operation
			} elseif ($mod['operation'] == 'desaturate') {
				$command_line .= ' -colorspace GRAY ';

			// Perform the rotate operation
			} elseif ($mod['operation'] == 'rotate') {
				$command_line .= ' -rotate ' . $mod['degrees'] . ' ';
			}
		}

		// Default to the RGB colorspace
		if (strpos($command_line, ' -colorspace ') === FALSE) {
			if (version_compare(self::$imagemagick_version, '6.7.5') >= 0) {
				$command_line .= ' -colorspace sRGB ';
			} else {
				$command_line .= ' -colorspace RGB ';
			}
		}

		if ($new_type == 'jpg') {
			$command_line .= ' -compress JPEG -quality ' . $jpeg_quality . ' ';
		}

		$command_line .= ' ' . escapeshellarg($new_type . ':' . $output_file) . ' 2>&1';

		exec($command_line, $output, $return_value);

		if ($return_value !== 0) {
			throw new fEnvironmentException(
				"An error occurred running the command, %1\$s, to modify the image. The error output was:\n%2\$s",
				$command_line,
				join("\n", $output)
			);
		}
	}


	/**
	 * Sets the image to be resized proportionally to a specific size canvas
	 *
	 * Will only size down an image. This method uses resampling to ensure the
	 * resized image is smooth in appearance. Resizing does not occur until
	 * ::saveChanges() is called.
	 *
	 * @param  integer $canvas_width    The width of the canvas to fit the image on, `0` for no constraint
	 * @param  integer $canvas_height   The height of the canvas to fit the image on, `0` for no constraint
	 * @param  boolean $allow_upsizing  If the image is smaller than the desired canvas, the image will be increased in size
	 * @return fImage  The image object, to allow for method chaining
	 */
	public function resize($canvas_width, $canvas_height, $allow_upsizing=FALSE)
	{
		$this->tossIfDeleted();

		// Make sure the user input is valid
		if ((!is_numeric($canvas_width) && $canvas_width !== NULL) || $canvas_width < 0) {
			throw new fProgrammerException(
				'The canvas width specified, %s, is not an integer or is less than zero',
				$canvas_width
			);
		}
		if ((!is_numeric($canvas_height) && $canvas_height !== NULL) || $canvas_height < 0) {
			throw new fProgrammerException(
				'The canvas height specified, %s is not an integer or is less than zero',
				$canvas_height
			);
		}
		if ($canvas_width == 0 && $canvas_height == 0) {
			throw new fProgrammerException(
				'The canvas width and canvas height are both zero, so no resizing will occur'
			);
		}

		// Calculate what the new dimensions will be
		$dim = $this->getCurrentDimensions();
		$orig_width  = $dim['width'];
		$orig_height = $dim['height'];

		if ($canvas_width == 0) {
			$new_height = $canvas_height;
			$new_width  = round(($new_height/$orig_height) * $orig_width);

		} elseif ($canvas_height == 0) {
			$new_width  = $canvas_width;
			$new_height = round(($new_width/$orig_width) * $orig_height);

		} else {
			$orig_ratio   = $orig_width/$orig_height;
			$canvas_ratio = $canvas_width/$canvas_height;

			if ($canvas_ratio > $orig_ratio) {
				$new_height = $canvas_height;
				$new_width  = round($orig_ratio * $new_height);
			} else {
				$new_width  = $canvas_width;
				$new_height = round($new_width / $orig_ratio);
			}
		}

		// If the size did not change, don't even record the modification
		$same_size   = $orig_width == $new_width || $orig_height == $new_height;
		$wont_change = ($orig_width < $new_width || $orig_height < $new_height) && !$allow_upsizing;
		if ($same_size || $wont_change) {
			return $this;
		}

		// Record what we are supposed to do
		$this->pending_modifications[] = array(
			'operation'  => 'resize',
			'width'      => $new_width,
			'height'     => $new_height,
			'old_width'  => $orig_width,
			'old_height' => $orig_height
		);

		return $this;
	}


	/**
	 * Sets the image to be rotated
	 *
	 * Rotation does not occur until ::saveChanges() is called.
	 *
	 * @param  integer $degrees   The number of degrees to rotate - 90, 180, or 270
	 */
	public function rotate($degrees)
	{
		$this->tossIfDeleted();

		// Make sure the user input is valid
		$valid_degrees = array(90, 180, 270);
		if (!in_array($degrees, $valid_degrees)) {
			throw new fProgrammerException(
				'The number of degrees specified, %1$s, is not valid. Must be one of: %2$s.',
				$degrees,
				$valid_degrees
			);
		}

		// Calculate what the new dimensions will be
		$dim = $this->getCurrentDimensions();
		$orig_width  = $dim['width'];
		$orig_height = $dim['height'];

		if ($degrees == 180) {
			$new_width  = $dim['width'];
			$new_height = $dim['height'];
		} else {
			$new_width  = $dim['height'];
			$new_height = $dim['width'];
		}

		// Record what we are supposed to do
		$this->pending_modifications[] = array(
			'operation'  => 'rotate',
			'degrees'    => $degrees,
			'width'      => $new_width,
			'height'     => $new_height,
			'old_width'  => $orig_width,
			'old_height' => $orig_height
		);

		return $this;
	}


	/**
	 * Saves any changes to the image
	 *
	 * If the file type is different than the current one, removes the current
	 * file once the new one is created.
	 *
	 * This operation will be reverted by a filesystem transaction being rolled
	 * back. If a transaction is in progress and the new image type causes a
	 * new file to be created, the old file will not be deleted until the
	 * transaction is committed.
	 *
	 * @param  string  $new_image_type  The new file format for the image: 'NULL` (no change), `'jpg'`, `'gif'`, `'png'`
	 * @param  integer $jpeg_quality    The quality setting to use for JPEG images - this may be ommitted
	 * @param  boolean $overwrite       If an existing file with the same name and extension should be overwritten
	 * @param  boolean $force_write     Forces the write of the image file even if there are no pending modifications
	 * @param  string  |$new_image_type
	 * @param  boolean |$overwrite
	 * @return fImage  The image object, to allow for method chaining
	 */
	public function saveChanges($new_image_type=NULL, $jpeg_quality=90, $overwrite=FALSE, $force_write=FALSE)
	{
		// This allows ommitting the $jpeg_quality parameter, which is very useful for non-jpegs
		$args = func_get_args();
		if (count($args) == 2 && is_bool($args[1])) {
			$overwrite    = $args[1];
			$jpeg_quality = 90;
		}

		$this->tossIfDeleted();
		self::determineProcessor();

		if (self::$processor == 'none') {
			throw new fEnvironmentException(
				"The changes to the image can't be saved because neither the GD extension or ImageMagick appears to be installed on the server"
			);
		}

		$type = self::getImageType($this->file);
		if ($type == 'tif' && self::$processor == 'gd') {
			throw new fEnvironmentException(
				'The image specified, %s, is a TIFF file and the GD extension can not handle TIFF files. Please install ImageMagick if you wish to manipulate TIFF files.',
				$this->file
			);
		}

		$valid_image_types = array('jpg', 'gif', 'png');
		if ($new_image_type !== NULL && !in_array($new_image_type, $valid_image_types)) {
			throw new fProgrammerException(
				'The new image type specified, %1$s, is invalid. Must be one of: %2$s.',
				$new_image_type,
				join(', ', $valid_image_types)
			);
		}

		if (is_numeric($jpeg_quality)) {
			$jpeg_quality = (int) round($jpeg_quality);
		}

		if (!is_integer($jpeg_quality) || $jpeg_quality < 1 || $jpeg_quality > 100) {
			throw new fProgrammerException(
				'The JPEG quality specified, %1$s, is either not an integer, less than %2$s or greater than %3$s.',
				$jpeg_quality,
				1,
				100
			);
		}

		if ($new_image_type && fFilesystem::getPathInfo($this->file, 'extension') != $new_image_type) {
			if ($overwrite) {
				$path_info   = fFilesystem::getPathInfo($this->file);
				$output_file = $path_info['dirname'] . $path_info['filename'] . '.' . $new_image_type;
			} else {
				$output_file = fFilesystem::makeUniqueName($this->file, $new_image_type);
			}

			if (file_exists($output_file)) {
				if (!is_writable($output_file)) {
					throw new fEnvironmentException(
						'Changes to the image can not be saved because the file, %s, is not writable',
						$output_file
					);
				}

			} else {
				$output_dir = dirname($output_file);
				if (!is_writable($output_dir)) {
					throw new fEnvironmentException(
						'Changes to the image can not be saved because the directory to save the new file, %s, is not writable',
						$output_dir
					);
				}
			}

		} else {
			$output_file = $this->file;
			if (!is_writable($output_file)) {
				throw new fEnvironmentException(
					'Changes to the image can not be saved because the file, %s, is not writable',
					$output_file
				);
			}
		}

		// If we don't have any changes and no name change, just exit
		if (!$force_write && !$this->pending_modifications && $output_file == $this->file) {
			return $this;
		}

		// Wrap changes to the image into the filesystem transaction
		if ($output_file == $this->file && fFilesystem::isInsideTransaction()) {
			fFilesystem::recordWrite($this);
		}

		if (self::$processor == 'gd') {
			$this->processWithGD($output_file, $jpeg_quality);
		} elseif (self::$processor == 'imagemagick') {
			$this->processWithImageMagick($output_file, $jpeg_quality);
		}

		$old_file = $this->file;
		fFilesystem::updateFilenameMap($this->file, $output_file);

		// If we created a new image, delete the old one
		if ($output_file != $old_file) {
			$old_image = new fImage($old_file);
			$old_image->delete();
		}

		$this->pending_modifications = array();
		clearstatcache();

		return $this;
	}
}



/**
 * Copyright (c) 2007-2011 Will Bond <will@flourishlib.com>, others
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */