fImage

The fImage class is a representation of an image file on the filesystem. It provides all of the functionality of the fFile class and adds the ability to perform image manipulation via GD or ImageMagick.

Configuration

As mentioned above, the fImage class provide image manipulation by using either the PHP GD extension or the program ImageMagick (command line). Under normal situations fImage can detect if the GD extension installed, and if not it will look for ImageMagick. If ImageMagick is installed in the default location (C:\Program Files\ImageMagick* for Windows, /usr/bin/ or /usr/local/bin/ for Linux/BSD) no configuration is necessary.

If the GD extension is not installed and ImageMagick can not be found, fImage will need to be configured with the location of ImageMagick. This can be done by passing the ImageMagick binary’s directory to the static method setImageMagickDirectory()`.

// An example of manually configuring ImageMagick
fImage::setImageMagickDirectory('/usr/local/imagemagick/bin');

In addition to configuring the path to the ImageMagick binaries, it is also possible to set a temporary directory for ImageMagick to use when processing files. The setImageMagickTempDir() static method performs this task and takes a single parameter $temp_dir.

// Setting a custom temporary directory for ImageMagick
fImage::setImageMagickTempDir('/tmp/imagemagick');

Image Information

The fImage class includes a few methods to provide basic metadata about the image. getWidth() and getHeight() provide straight-forward access to image dimensions. getDimensions() returns a two-element array of the width, then the height.

$width  = $image->getWidth();
$height = $image->getHeight();
 
list($witdh, $height) = $image->getDimensions();

The method getType() will return a string with the image type. Types include: 'jpg', 'gif', 'png' and 'tif'.

$type = $image->getType();

Modification

Probably the most significant functionality of the fImage class is the ability to modify an image. There are currently three different modifications that can be performed: crop(), cropToRatio(), resize() and desaturate().

Calling any of these modifications will not actually cause the changes to be written to disk until saveChanges() is called.

crop() accepts four parameters, the pixels dimensions for $crop_from_x, $crop_from_y, $new_width and $new_height, and will perform pixel-specific cropping.

cropToRatio() will crop the largest rectangle our of an image that conforms to the ratio passed in via $ratio_width and $ratio_height.

desaturate() will cause the image to lose all color information and become grayscale.

resize() will scale the image to fit the canvas size defined by the parameters $canvas_width and $canvas_height. If either parameter is empty() or 0, the image will be resized to fit the specified dimension.

Here are some examples of how to modify an image:

// Create a 16x16 icon from the top left of an image
$image1 = new fImage('./example.gif');
$image1->crop(0, 0, 16, 16);
$image1->saveChanges();
 
// Create a 32x32 icon from an image
$image2 = new fImage('./example.gif');
$image2->cropToRatio(1, 1);
$image2->resize(32, 32);
$image2->saveChanges();
 
// Ensure an image is never wider than 250 pixels
$image3 = new fImage('./example.gif');
$image3->resize(250, 0);
$image3->saveChanges();
 
// Change the image to be grayscale
$image4 = new fImage('./example.gif');
$image4->desaturate();
$image4->saveChanges();

saveChanges() can accept from zero to two parameters. The first optional parameter is the $new_image_type which can be 'jpg', 'gif' or 'png'. If no $new_image_type is specified, the image will be resaved in the current format. If the 'jpg' image type is specified, there is a second optional parameter, the $jpeg_quality to use. If no $jpeg_quality is specified, 90 is used as the default.

// Saving as a PNG
$image2 = new fImage('./example.gif');
$image2->resize(250, 0);
$image2->saveChanges('png');
 
// Saving as a 60 quality JPEG
$image2 = new fImage('./example.gif');
$image2->resize(250, 0);
$image2->saveChanges('jpeg', 60);