Source for file Transform.php

<?php
 
/* vim: set expandtab tabstop=4 shiftwidth=4: */
 
/**
 * Simple and cross-library package to doing image transformations and
 * manipulations.
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   Image
 * @package    Image_Transform
 * @author     Vincent Oostindie <vincent@sunlight.tmfweb.nl>
 * @author     Alan Knowles <alan@akbkhome.com>
 * @author     Peter Bowyer <peter@mapledesign.co.uk>
 * @author     Philippe Jausions <Philippe.Jausions@11abacus.com>
 * @copyright  2002-2007 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id: Transform.php,v 1.42 2007/04/19 16:17:57 dufuz Exp $
 * @link       http://pear.php.net/package/Image_Transform
 */
 
/**
 * Include for error handling
 */
require_once 'PEAR.php';
 
/**
 * Error code for unsupported library, image format or methods
 */
define('IMAGE_TRANSFORM_ERROR_UNSUPPORTED', 1);
 
/**
 * Error code for failed transformation operations
 */
define('IMAGE_TRANSFORM_ERROR_FAILED', 2);
 
/**
 * Error code for failed i/o (Input/Output) operations
 */
define('IMAGE_TRANSFORM_ERROR_IO', 3);
 
/**
 * Error code for invalid arguments
 */
define('IMAGE_TRANSFORM_ERROR_ARGUMENT', 4);
 
/**
 * Error code for out-of-bound related errors
 */
define('IMAGE_TRANSFORM_ERROR_OUTOFBOUND', 5);
 
 
 
/**
 * Base class with factory method for backend driver
 *
 * The main "Image_Transform" class is a container and base class which
 * provides a static method for creating an Image object as well as
 * some utility functions (maths) common to all parts of Image_Transform.
 *
 * @category   Image
 * @package    Image_Transform
 * @author     Alan Knowles <alan@akbkhome.com>
 * @author     Peter Bowyer <peter@mapledesign.co.uk>
 * @author     Philippe Jausions <Philippe.Jausions@11abacus.com>
 * @copyright  2002-2007 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/Image_Transform
 * @since      PHP 4.0
 */
class Image_Transform
{
    /**
     * Name of the image file
     * @var string 
     */
    var $image = '';
 
    /**
     * Type of the image file (eg. jpg, gif png ...)
     * @var string 
     */
    var $type = '';
 
    /**
     * Original image width in x direction
     * @var int 
     */
    var $img_x = '';
 
    /**
     * Original image width in y direction
     * @var int 
     */
    var $img_y = '';
 
    /**
     * New image width in x direction
     * @var int 
     */
    var $new_x = '';
 
    /**
     * New image width in y direction
     * @var int 
     */
    var $new_y = '';
 
    /**
     * Path to the library used
     * e.g. /usr/local/ImageMagick/bin/ or
     * /usr/local/netpbm/
     */
    var $lib_path = '';
 
    /**
     * Flag to warn if image has been resized more than once before displaying
     * or saving.
     */
    var $resized = false;
 
    /**
     * @var array General options
     * @access protected
     */
    var $_options = array(
        'quality'     => 75,
        'scaleMethod' => 'smooth',
        'canvasColor' => array(255, 255, 255),
        'pencilColor' => array(0, 0, 0),
        'textColor'   => array(0, 0, 0)
        );
 
    /**
     * Flag for whether settings should be discarded on saving/display of image
     * @var bool 
     * @see Image_Transform::keepSettingsOnSave
     */
    var $keep_settings_on_save = false;
 
    /**
     * Supported image types
     * @var array 
     * @access protected
     */
    var $_supported_image_types = array();
 
    /**
     * Initialization error tracking
     * @var object 
     * @access private
     ***/
    var $_error = null;
 
    /**
     * associative array that tracks existence of programs
     * (for drivers using shell interface and a tiny performance
     * improvement if the clearstatcache() is used)
     * @var array 
     * @access protected
     */
    var $_programs = array();
 
     /**
      * Default parameters used in the addText methods.
      */
     var $default_text_params = array('text' => 'Default text',
                                      'x'     => 10,
                                      'y'     => 20,
                                      'color' => 'red',
                                      'font'  => 'Arial.ttf',
                                      'size'  => '12',
                                      'angle' => 0,
                                      'resize_first' => false);
 
    /**
     * Creates a new Image_Transform object
     *
     * @param string $driver name of driver class to initialize. If no driver
     *                is specified the factory will attempt to use 'Imagick' first
     *                then 'GD' second, then 'Imlib' last
     *
     * @return object an Image_Transform object, or PEAR_Error on error
     *
     * @see PEAR::isError()
     * @see Image_Transform::setOption()
     */
    function &factory($driver = '')
    {
        if ($driver == '') {
            $extensions = array(
                'imagick' => 'Imagick2',
                'gd'      => 'GD',
                'imlib'   => 'Imlib');
 
            foreach ($extensions as $ext => $ext_driver) {
                if (PEAR::loadExtension($ext)) {
                    $driver = $ext_driver;
                    break;
                }
            }
            if (!$driver) {
                return PEAR::raiseError('No image library specified and none can be found.  You must specify driver in factory() call.',
                    IMAGE_TRANSFORM_ERROR_ARGUMENT);
            }
        }
        @include_once 'Image/Transform/Driver/' . basename($driver) . '.php';
 
        $classname = "Image_Transform_Driver_{$driver}";
        if (!class_exists($classname)) {
            return PEAR::raiseError('Image library not supported... aborting.',
                IMAGE_TRANSFORM_ERROR_UNSUPPORTED);
        }
        $obj =& new $classname;
 
        // Check startup error
        if ($error =& $obj->isError()) {
            $obj =& $error;
        }
        return $obj;
    }
 
    /**
     * Returns/sets an error when the instance couldn't initialize properly
     *
     * @param  object PEAR_Error object when setting an error
     * @return mixed FALSE or PEAR_Error object
     * @access protected
     */
    function &isError($error = null)
    {
        if (!is_null($error)) {
            $this->_error =& $error;
        }
        return $this->_error;
    }
 
    /**
     * Resizes the image in the X and/or Y direction(s)
     *
     * If either is 0 it will keep the original size for that dimension
     *
     * @param mixed $new_x (0, number, percentage 10% or 0.1)
     * @param mixed $new_y (0, number, percentage 10% or 0.1)
     * @param array $options Options
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     */
    function resize($new_x = 0, $new_y = 0, $options = null)
    {
        // 0 means keep original size
        $new_x = (0 == $new_x)
                 ? $this->img_x
                 : $this->_parse_size($new_x, $this->img_x);
        $new_y = (0 == $new_y)
                 ? $this->img_y
                 : $this->_parse_size($new_y, $this->img_y);
 
        // Now do the library specific resizing.
        return $this->_resize($new_x, $new_y, $options);
    } // End resize
 
 
    
    /**
     * Scales the image to the specified width
     *
     * This method preserves the aspect ratio
     *
     * @param int $new_x Size to scale X-dimension to
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     */
    function scaleByX($new_x)
    {
        if ($new_x <= 0) {
            return PEAR::raiseError('New size must be strictly positive',
                                        IMAGE_TRANSFORM_ERROR_OUTOFBOUND);
        }
        $new_y = round(($new_x / $this->img_x) * $this->img_y, 0);
        return $this->_resize(max(1, $new_x), max(1, $new_y));
    } // End scaleByX
 
    
    /**
     * Alias for resize()
     *
     * @see resize()
     */
    function scaleByXY($new_x = 0, $new_y = 0, $options = null)
    {
        return $this->resize($new_x, $new_y, $options);
    } // End scaleByXY
 
    
    /**
     * Scales the image to the specified height.
     *
     * This method preserves the aspect ratio
     *
     * @param int $new_y Size to scale Y-dimension to
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     */
    function scaleByY($new_y)
    {
        if ($new_y <= 0) {
            return PEAR::raiseError('New size must be strictly positive',
                                        IMAGE_TRANSFORM_ERROR_OUTOFBOUND);
        }
        $new_x = round(($new_y / $this->img_y) * $this->img_x, 0);
        return $this->_resize(max(1, $new_x), max(1, $new_y));
    } // End scaleByY
 
    
    /**
     * Scales an image by a percentage, factor or a given length
     *
     * This method preserves the aspect ratio
     *
     * @param mixed (number, percentage 10% or 0.1)
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     * @see scaleByPercentage, scaleByFactor, scaleByLength
     */
    function scale($size)
    {
        if ((strlen($size) > 1) && (substr($size, -1) == '%')) {
            return $this->scaleByPercentage(substr($size, 0, -1));
        } elseif ($size < 1) {
            return $this->scaleByFactor($size);
        } else {
            return $this->scaleByLength($size);
        }
    } // End scale
 
    
    /**
     * Scales an image to a percentage of its original size.  For example, if
     * my image was 640x480 and I called scaleByPercentage(10) then the image
     * would be resized to 64x48
     *
     * @param  int $size Percentage of original size to scale to
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     */
    function scaleByPercentage($size)
    {
        return $this->scaleByFactor($size / 100);
    } // End scaleByPercentage
 
    
    /**
     * Scales an image to a factor of its original size.  For example, if
     * my image was 640x480 and I called scaleByFactor(0.5) then the image
     * would be resized to 320x240.
     *
     * @param float $size Factor of original size to scale to
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     */
    function scaleByFactor($size)
    {
        if ($size <= 0) {
            return PEAR::raiseError('New size must be strictly positive',
                                        IMAGE_TRANSFORM_ERROR_OUTOFBOUND);
        }
        $new_x = round($size * $this->img_x, 0);
        $new_y = round($size * $this->img_y, 0);
        return $this->_resize(max(1, $new_x), max(1, $new_y));
    } // End scaleByFactor
 
    
    /**
     * Scales an image so that the longest side has the specified dimension.
     *
     * This method preserves the aspect ratio
     *
     * @param int $size Max dimension in pixels
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     */
    function scaleMaxLength($size)
    {
        if ($size <= 0) {
            return PEAR::raiseError('New size must be strictly positive',
                                        IMAGE_TRANSFORM_ERROR_OUTOFBOUND);
        }
        if ($this->img_x >= $this->img_y) {
            $new_x = $size;
            $new_y = round(($new_x / $this->img_x) * $this->img_y, 0);
        } else {
            $new_y = $size;
            $new_x = round(($new_y / $this->img_y) * $this->img_x, 0);
        }
        return $this->_resize(max(1, $new_x), max(1, $new_y));
    } // End scaleMaxLength
 
    
    /**
     * Alias for scaleMaxLength
     *
     * @return mixed TRUE or PEAR_Error object on error
     * @access public
     * @see scaleMaxLength()
     */
    function scaleByLength($size)
    {
        return $this->scaleMaxLength($size);
    }
 
    /**
     * Fits the image in the specified box size
     *
     * If the image is bigger than the box specified by $width and $height,
     * it will be scaled down to fit inside of it.
     * If the image is smaller, nothing is done.
     *
     * @param  integer $width 
     * @param  integer $height 
     * @return bool|PEAR_ErrorTRUE or PEAR_Error object on error
     * @access public
     */
    function fit($width, $height)
    {
        if ($width <= 0 || $height <= 0) {
            return PEAR::raiseError("Invalid arguments.",
                IMAGE_TRANSFORM_ERROR_ARGUMENT);
        }
        $x = $this->img_x / $width;
        $y = $this->img_y / $height;
        if ($x <= 1 && $y <= 1) {
            return true;
        } elseif ($x > $y) {
            return $this->scaleByX($width);
        } else {
            return $this->scaleByY($height);
        }
    }
 
    /**
     * Fits the image in the specified width
     *
     * If the image is wider than the width specified by $width,
     * it will be scaled down to fit inside of it.
     * If the image is smaller, nothing is done.
     *
     * @param integer $width 
     * @return bool|PEAR_ErrorTRUE or PEAR_Error object on error
     * @access public
     */
    function fitX($width)
    {
        return ($this->img_x <= $width) ? true : $this->scaleByX($width);
    }
 
    /**
     * Fits the image in the specified height
     *
     * If the image is taller than the height specified by $height,
     * it will be scaled down to fit inside of it.
     * If the image is smaller, nothing is done.
     *
     * @param integer $height 
     * @return bool|PEAR_ErrorTRUE or PEAR_Error object on error
     * @access public
     */
    function fitY($height)
    {
        return ($this->img_y <= $height) ? true : $this->scaleByY($height);
    }
 
    /**
     * Sets one options
     *
     * @param  string Name of option
     * @param  mixed  Value of option
     * @access public
     * @see setOptions()
     */
    function setOption($name, $value)
    {
        $this->_options[$name] = $value;
    }
 
    /**
     * Sets multiple options at once
     *
     * Associative array of options:
     *  - quality     (Integer: 0: poor - 100: best)
     *  - scaleMethod ('smooth', 'pixel')
     *
     * @param  array $options Array of options
     * @access public
     */
    function setOptions($options)
    {
        $this->_options = array_merge($this->_options, $options);
    }
 
    /**
     * Sets the image type (in lowercase letters), the image height and width.
     *
     * @return mixed TRUE or PEAR_error
     * @access protected
     * @see PHP_Compat::image_type_to_mime_type()
     * @link http://php.net/getimagesize
     */
    function _get_image_details($image)
    {
        $data = @getimagesize($image);
        //  1 = GIF,   2 = JPG,  3 = PNG,  4 = SWF,  5 = PSD,  6 = BMP,
        //  7 = TIFF (intel byte order),   8 = TIFF (motorola byte order),
        //  9 = JPC,  10 = JP2, 11 = JPX, 12 = JB2, 13 = SWC, 14 = IFF,
        // 15 = WBMP, 16 = XBM
        if (!is_array($data)) {
            return PEAR::raiseError("Cannot fetch image or images details.", true);
        }
 
        switch ($data[2]) {
            case IMAGETYPE_GIF:
                $type = 'gif';
                break;
            case IMAGETYPE_JPEG:
                $type = 'jpeg';
                break;
            case IMAGETYPE_PNG:
                $type = 'png';
                break;
            case IMAGETYPE_SWF:
                $type = 'swf';
                break;
            case IMAGETYPE_PSD:
                $type = 'psd';
                break;
            case IMAGETYPE_BMP:
                $type = 'bmp';
                break;
            case IMAGETYPE_TIFF_II:
            case IMAGETYPE_TIFF_MM:
                $type = 'tiff';
                break;
            case IMAGETYPE_JPC:
                $type = 'jpc';
                break;
            case IMAGETYPE_JP2:
                $type = 'jp2';
                break;
            case IMAGETYPE_JPX:
                $type = 'jpx';
                break;
            case IMAGETYPE_JB2:
                $type = 'jb2';
                break;
            case IMAGETYPE_SWC:
                $type = 'swc';
                break;
            case IMAGETYPE_IFF:
                $type = 'iff';
                break;
            case IMAGETYPE_WBMP:
                $type = 'wbmp';
                break;
            case IMAGETYPE_XBM:
                $type = 'xbm';
                break;
            default:
                return PEAR::raiseError("Cannot recognize image format",
                    IMAGE_TRANSFORM_ERROR_UNSUPPORTED);
        }
        $this->img_x = $this->new_x = $data[0];
        $this->img_y = $this->new_y = $data[1];
        $this->type  = $type;
 
        return true;
    }
 
 
    /**
     * Returns the matching IMAGETYPE_* constant for a given image type
     *
     * @param  mixed $type String (GIF, JPG,...)
     * @return mixed string or integer or input on error
     * @access protected
     * @see PHP_Compat::image_type_to_mime_type()
     ***/
    function _convert_image_type($type)
    {
        switch (strtolower($type)) {
            case 'gif':
                return IMAGETYPE_GIF;
            case 'jpeg':
            case 'jpg':
                return IMAGETYPE_JPEG;
            case 'png':
                return IMAGETYPE_PNG;
            case 'swf':
                return IMAGETYPE_SWF;
            case 'psd':
                return IMAGETYPE_PSD;
            case 'bmp':
                return IMAGETYPE_BMP;
            case 'tiff':
                return IMAGETYPE_TIFF_II;
                //IMAGETYPE_TIFF_MM;
            case 'jpc':
                return IMAGETYPE_JPC;
            case 'jp2':
                return IMAGETYPE_JP2;
            case 'jpx':
                return IMAGETYPE_JPX;
            case 'jb2':
                return IMAGETYPE_JB2;
            case 'swc':
                return IMAGETYPE_SWC;
            case 'iff':
                return IMAGETYPE_IFF;
            case 'wbmp':
                return IMAGETYPE_WBMP;
            case 'xbm':
                return IMAGETYPE_XBM;
            default:
                return $type;
        }
 
        return (isset($types[$t = strtolower($type)])) ? $types[$t] : $type;
    }
 
 
    /**
     * Parses input for number format and convert
     *
     * If either paramet