Image Manipulation Class

CodeIgniter’s Image Manipulation class lets you perform the following actions:

• Image Resizing
• Thumbnail Creation
• Image Cropping
• Image Rotating
• Image Watermarking

All three major image libraries are supported: GD/GD2, NetPBM, and ImageMagick

• Initializing the Class
  • Processing an Image
  • Processing Methods
  • Preferences
  • Setting preferences in a config file
• Image Watermarking
  • Two Types of Watermarking
  • Watermarking an Image
  • Watermarking Preferences
    • Text Preferences
    • Overlay Preferences
• Class Reference

Initializing the Class

Like most other classes in CodeIgniter, the image class is initialized in your controller using the $this->load->library function:

$this->load->library('image_lib');

Once the library is loaded it will be ready for use. The image library object you will use to call all functions is: $this->image_lib

Processing an Image

Regardless of the type of processing you would like to perform (resizing, cropping, rotation, or watermarking), the general process is identical. You will set some preferences corresponding to the action you intend to perform, then call one of four available processing functions. For example, to create an image thumbnail you’ll do this:

$config['image_library'] = 'gd2';
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['create_thumb'] = TRUE;
$config['maintain_ratio'] = TRUE;
$config['width']         = 75;
$config['height']       = 50;

$this->load->library('image_lib', $config);

$this->image_lib->resize();

The above code tells the image_resize function to look for an image called mypic.jpg located in the source_image folder, then create a thumbnail that is 75 X 50 pixels using the GD2 image_library. Since the maintain_ratio option is enabled, the thumb will be as close to the target width and height as possible while preserving the original aspect ratio. The thumbnail will be called mypic_thumb.jpg and located at the same level as source_image.

Processing Methods

There are four available processing methods:

• $this->image_lib->resize()
• $this->image_lib->crop()
• $this->image_lib->rotate()
• $this->image_lib->watermark()

These methods return boolean TRUE upon success and FALSE for failure. If they fail you can retrieve the error message using this function:

echo $this->image_lib->display_errors();

A good practice is to use the processing function conditionally, showing an error upon failure, like this:

if ( ! $this->image_lib->resize())
{
        echo $this->image_lib->display_errors();
}

$this->image_lib->display_errors('<p>', '</p>');

Preferences

The preferences described below allow you to tailor the image processing to suit your needs.

Note that not all preferences are available for every function. For example, the x/y axis preferences are only available for image cropping. Likewise, the width and height preferences have no effect on cropping. The “availability” column indicates which functions support a given preference.

Availability Legend:

• R - Image Resizing
• C - Image Cropping
• X - Image Rotation
• W - Image Watermarking

Setting preferences in a config file

If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called image_lib.php, add the $config array in that file. Then save the file in config/image_lib.php and it will be used automatically. You will NOT need to use the $this->image_lib->initialize() method if you save your preferences in a config file.

Image Watermarking

The Watermarking feature requires the GD/GD2 library.

Two Types of Watermarking

There are two types of watermarking that you can use:

• Text: The watermark message will be generated using text, either with a True Type font that you specify, or using the native text output that the GD library supports. If you use the True Type version your GD installation must be compiled with True Type support (most are, but not all).
• Overlay: The watermark message will be generated by overlaying an image (usually a transparent PNG or GIF) containing your watermark over the source image.

Watermarking an Image

Just as with the other methods (resizing, cropping, and rotating) the general process for watermarking involves setting the preferences corresponding to the action you intend to perform, then calling the watermark function. Here is an example:

$config['source_image'] = '/path/to/image/mypic.jpg';
$config['wm_text'] = 'Copyright 2006 - John Doe';
$config['wm_type'] = 'text';
$config['wm_font_path'] = './system/fonts/texb.ttf';
$config['wm_font_size'] = '16';
$config['wm_font_color'] = 'ffffff';
$config['wm_vrt_alignment'] = 'bottom';
$config['wm_hor_alignment'] = 'center';
$config['wm_padding'] = '20';

$this->image_lib->initialize($config);

$this->image_lib->watermark();

The above example will use a 16 pixel True Type font to create the text “Copyright 2006 - John Doe”. The watermark will be positioned at the bottom/center of the image, 20 pixels from the bottom of the image.

Watermarking Preferences

This table shows the preferences that are available for both types of watermarking (text or overlay)

Text Preferences

This table shows the preferences that are available for the text type of watermarking.

Overlay Preferences

This table shows the preferences that are available for the overlay type of watermarking.

Class Reference

class CI_Image_lib

initialize([$props = array()])

Parameters:	$props (array) – Image processing preferences
Returns:	TRUE on success, FALSE in case of invalid settings
Return type:	bool

Initializes the class for processing an image.

resize()

Returns:	TRUE on success, FALSE on failure
Return type:	bool

The image resizing method lets you resize the original image, create a copy (with or without resizing), or create a thumbnail image.

For practical purposes there is no difference between creating a copy and creating a thumbnail except a thumb will have the thumbnail marker as part of the name (i.e. mypic_thumb.jpg).

All preferences listed in the Preferences table are available for this method except these three: rotation_angle, x_axis and y_axis.

Creating a Thumbnail

The resizing method will create a thumbnail file (and preserve the original) if you set this preference to TRUE:

$config['create_thumb'] = TRUE;

This single preference determines whether a thumbnail is created or not.

Creating a Copy

The resizing method will create a copy of the image file (and preserve the original) if you set a path and/or a new filename using this preference:

$config['new_image'] = '/path/to/new_image.jpg';

Notes regarding this preference:

• If only the new image name is specified it will be placed in the same folder as the original
• If only the path is specified, the new image will be placed in the destination with the same name as the original.
• If both the path and image name are specified it will placed in its own destination and given the new name.

Resizing the Original Image

If neither of the two preferences listed above (create_thumb, and new_image) are used, the resizing method will instead target the original image for processing.

crop()

Returns:	TRUE on success, FALSE on failure
Return type:	bool

The cropping method works nearly identically to the resizing function except it requires that you set preferences for the X and Y axis (in pixels) specifying where to crop, like this:

$config['x_axis'] = 100;
$config['y_axis'] = 40;

All preferences listed in the Preferences table are available for this method except these: rotation_angle, create_thumb and new_image.

Here’s an example showing how you might crop an image:

$config['image_library'] = 'imagemagick';
$config['library_path'] = '/usr/X11R6/bin/';
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['x_axis'] = 100;
$config['y_axis'] = 60;

$this->image_lib->initialize($config);

if ( ! $this->image_lib->crop())
{
        echo $this->image_lib->display_errors();
}

Note

Without a visual interface it is difficult to crop images, so this method is not very useful unless you intend to build such an interface. That’s exactly what we did using for the photo gallery module in ExpressionEngine, the CMS we develop. We added a JavaScript UI that lets the cropping area be selected.

rotate()

Returns:	TRUE on success, FALSE on failure
Return type:	bool

The image rotation method requires that the angle of rotation be set via its preference:

$config['rotation_angle'] = '90';

There are 5 rotation options:

1. 90 - rotates counter-clockwise by 90 degrees.
2. 180 - rotates counter-clockwise by 180 degrees.
3. 270 - rotates counter-clockwise by 270 degrees.
4. hor - flips the image horizontally.
5. vrt - flips the image vertically.

Here’s an example showing how you might rotate an image:

$config['image_library'] = 'netpbm';
$config['library_path'] = '/usr/bin/';
$config['source_image'] = '/path/to/image/mypic.jpg';
$config['rotation_angle'] = 'hor';

$this->image_lib->initialize($config);

if ( ! $this->image_lib->rotate())
{
        echo $this->image_lib->display_errors();
}

watermark()

Returns:	TRUE on success, FALSE on failure
Return type:	bool

Creates a watermark over an image, please refer to the Watermarking an Image section for more info.

clear()

Return type:	void

The clear method resets all of the values used when processing an image. You will want to call this if you are processing images in a loop.

$this->image_lib->clear();

display_errors([$open = '<p>[, $close = '</p>']])

Parameters:	$open (string) – Error message opening tag $close (string) – Error message closing tag
Returns:	Error messages
Return type:	string

Returns all detected errors formatted as a string.

echo $this->image_lib->display_errors();