Image_Transform

General usage

The first step to do when using Image_Transform is to create an Image_Transform_Driver instance via the static factory() method. Just pass the driver name and you've got your object.

Now you can load() your image by passing the filename to this function. Use one of the scaling methods and then save().

<?php
require_once 'Image/Transform.php';

//create transform driver object
$it = Image_Transform::factory('GD');

//load the original file
$it->load('beach-large.jpg');

//scale it to 150px
$it->scaleMaxLength(150);

//save it into a different file
$it->save('beach-150px.jpg');
?>

The example above did not do any error checking. Principially, any method may return a PEAR_Error object. Either you check each return value or - in PHP 5 - set the global PEAR error handler to throw exceptions as soon as an error occurs. This may interfere with other errors that are expected and can be hidden, so be careful with this option (especially when using other packages).

<?php
require_once 'Image/Transform.php';

//create transform driver object
$it = Image_Transform::factory('GD');
if (PEAR::isError($it)) {
    die($it->getMessage());
}

//load the original file
$ret = $it->load('beach-large.jpg');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}

//scale it to 150px
$ret = $it->scaleByLength(150);
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}

//save it into a different file
$ret = $it->save('beach-150px.jpg');
if (PEAR::isError($ret)) {
    die($ret->getMessage());
}
?>

Drivers

The Image_Transform package is useless without a driver that encapsulates some graphic libraries' methods. As of April 2008, the package has the following drivers you can install and use:

• Image_Transform_Driver_GD - uses methods of the GD 2 extension

• Image_Transform_Driver_Imagick2 - for imagick PECL extension version < 2.0

• Image_Transform_Driver_Imagick3 - for imagick PECL extension version >= 2.0

• Image_Transform_Driver_Imlib - uses PHP imlib extension

• Image_Transform_Driver_IM - Imagick binary executables (if you don't have the extension)

• Image_Transform_Driver_NetPBM - uses the binary executable pnmscale of the NetPBM software package.

Scaling images

Image_Transform brings you a lot of methods to scale images. Most of them call the basic resizing method with different parameters, but still have their right to exist because they make your life convenient. Here is a short list:

• resize - generic resizing method. Pass any size, percentage string (with %) or a scaling factor for both x and y values. Keep it 0 to keep that size. Does not necessarily keep the aspect ratio.

• scaleByX - scale the image by resizing the width of the image to the given pixel size. Preserves aspect ratio.

• scaleByY - scale the image by resizing the height of the image to the given pixel size. Preserves aspect ratio.

• scale - generig scaling function. Pass a pixel value, percentage (with %) or scaling factor (<1). Keeps aspect ratio.

• scaleByPercentage - scales by the given percentage.

• scaleByFactor - same as scaleByPercentage(), just that the numbers are factor 100 smaller.

• scaleByLength - scale so that the longest size has the desired size.

• fit - scale the image so that it fits into the given box (width and height). Nothing is done if the image is already smaller or equal than the box size.

• fitX - scale the image so that the width is the given size. If the width is already smaller, nothing is done.

• fitY - scale the image so that the height is the given size. If the height is already smaller, nothing is done.

Saving

The save() method requires at least one parameter, the filename as which the scaled image is to be saved as. With only one parameter, the type of the new image is the same as the original type.

The second parameter can be the extension of the file type you want to save the image as, for example png or jpg.

In case of an error - for example if the driver does not support to write the file type - a PEAR_Error object is returned.

Instead of saving, you can directly put out the image to the browser using display().

Other methods