Chapter 16. Image Manipulation

16.1. Overview
16.2. Image Classes
16.3. Writing Drivers

16.1. Overview

Perforce Chronicle provides an image library that can perform select image manipulations, such as scaling, to be done on the server. Using the image library greatly assists theme developers, who can specify sizes for images to fit within the theme without having to restrict the sizes of images that users upload. This chapter is focused on module developers, providing an overview of how the image library works, and how to interact with and extend the image library.

While the image library can provide better image quality, or can help reduce bandwidth, it requires an additional PHP extension to be installed on the server. If necessary, ask your system administrator to install one of the following extensions:

16.1.1. Supported Image Libraries

Currently supported libraries include:

ImageMagick is "a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 100)." To use this library, the imagick extension must be installed.
GD is "an open source code library for the dynamic creation of images by programmers. GD creates PNG, JPEG, and GIF images, among other formats." To use this library, the gd extension must be installed.

If you have more than one of the supported image libraries installed, Chronicle defaults to using ImageMagick, if available, then GD.

16.1.2. Standard Transformations

Chronicle provides the following transformations in each of the supplied drivers:

crop

Crops the image to the given size at the specified position.

<?php
    $image->transform('crop', array(width, height, x, y));

width specifies the integer width in pixels of the cropped image.
height specifies the integer height in pixels of the cropped image.
x specifies the integer starting pixel of the crop from the left side. 0 would begin the crop with the left-most pixel.
y specifies the integer starting pixel of the crop from the top side. 0 would begin the crop with the top-most pixel.

rotate

Rotates the image.

<?php
    $image->transform('rotate', array(degrees));

degrees specifies the floating point degrees to rotate the image by, in the clock-wise direction.

scale

Scales the image to the specified dimensions.

<?php
    $image->transform('scale', array(width, height));

width specifies the integer width in pixels of the scaled image.
height specifies the integer height in pixels of the scaled image.

Maintaining Aspect Ratio

	Maintaining Aspect Ratio
If only the width, or the height, is specified, the image is scaled to match the specified size, and the unspecified size is computed to maintain the aspect ratio, or shape, of the image. For example, if the original image is 1024x768 pixels, invoking `scale` with a width of 100 pixels would result in a scaled image of 100x75 pixels. Instead, if `scale` is invoked with a height of 100 pixels, the scaled image would be 133x100 pixels. To specify only a height, provide the width as `null`.

If only the width, or the height, is specified, the image is scaled to match the specified size, and the unspecified size is computed to maintain the aspect ratio, or shape, of the image.

For example, if the original image is 1024x768 pixels, invoking scale with a width of 100 pixels would result in a scaled image of 100x75 pixels. Instead, if scale is invoked with a height of 100 pixels, the scaled image would be 133x100 pixels. To specify only a height, provide the width as null.

sharpen

Sharpens the image.

<?php
    $image->transform('sharpen');