+ +

+

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

+

Note

+

Watermarking is only available using the GD/GD2 library. In +addition, even though other libraries are supported, GD is required in +order for the script to calculate the image properties. The image +processing, however, will be performed with the library you specify.

+

Initializing the Class
+
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.

+

Note

+

In order for the image class to be allowed to do any +processing, the folder containing the image files must have write +permissions.

+

Note

+

Image processing can require a considerable amount of server +memory for some operations. If you are experiencing out of memory errors +while processing images you may need to limit their maximum size, and/or +adjust PHP memory limits.

+

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();
+}
+

+

+

Note

+

You can optionally specify the HTML formatting to be applied to +the errors, by submitting the opening/closing tags in the function, +like this:

+

$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

+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Preference	Default Value	Options	Description	Availability
image_library	GD2	GD, GD2, ImageMagick, NetPBM	Sets the image library to be used.	R, C, X, W
library_path	None	None	Sets the server path to your ImageMagick or NetPBM library. If you use +either of those libraries you must supply the path.	R, C, X +R, C, S, W
source_image	None	None	Sets the source image name/path. The path must be a relative or absolute +server path, not a URL.
dynamic_output	FALSE	TRUE/FALSE (boolean)	Determines whether the new image file should be written to disk or +generated dynamically. Note: If you choose the dynamic setting, only one +image can be shown at a time, and it can’t be positioned on the page. It +simply outputs the raw image dynamically to your browser, along with +image headers.	R, C, X, W
file_permissions	0644	(integer)	File system permissions to apply on the resulting image file, +writing it to the disk. WARNING: Use octal integer notation!	R, C, X, W
quality	90%	1 - 100%	Sets the quality of the image. The higher the quality the larger the +file size.	R, C, X, W
new_image	None	None	Sets the destination image name/path. You’ll use this preference when +creating an image copy. The path must be a relative or absolute server +path, not a URL.	R, C, X, W
width	None	None	Sets the width you would like the image set to.	R, C
height	None	None	Sets the height you would like the image set to.	R, C
create_thumb	FALSE	TRUE/FALSE (boolean)	Tells the image processing function to create a thumb.	R
thumb_marker	_thumb	None	Specifies the thumbnail indicator. It will be inserted just before the +file extension, so mypic.jpg would become mypic_thumb.jpg	R
maintain_ratio	TRUE	TRUE/FALSE (boolean)	Specifies whether to maintain the original aspect ratio when resizing or +use hard values.	R, C
master_dim	auto	auto, width, height	Specifies what to use as the master axis when resizing or creating +thumbs. For example, let’s say you want to resize an image to 100 X 75 +pixels. If the source image size does not allow perfect resizing to +those dimensions, this setting determines which axis should be used as +the hard value. “auto” sets the axis automatically based on whether the +image is taller than wider, or vice versa.	R
rotation_angle	None	90, 180, 270, vrt, hor	Specifies the angle of rotation when rotating images. Note that PHP +rotates counter-clockwise, so a 90 degree rotation to the right must be +specified as 270.	X
x_axis	None	None	Sets the X coordinate in pixels for image cropping. For example, a +setting of 30 will crop an image 30 pixels from the left.	C
y_axis	None	None	Sets the Y coordinate in pixels for image cropping. For example, a +setting of 30 will crop an image 30 pixels from the top.	C

+

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.

+

Note

+

In order for the image class to be allowed to do any +processing, the image file must have “write” file permissions +For example, 777.

+

Watermarking Preferences ¶

+

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

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Preference	Default Value	Options	Description
wm_type	text	text, overlay	Sets the type of watermarking that should be used.
source_image	None	None	Sets the source image name/path. The path must be a relative or absolute +server path, not a URL.
dynamic_output	FALSE	TRUE/FALSE (boolean)	Determines whether the new image file should be written to disk or +generated dynamically. Note: If you choose the dynamic setting, only one +image can be shown at a time, and it can’t be positioned on the page. It +simply outputs the raw image dynamically to your browser, along with +image headers.
quality	90%	1 - 100%	Sets the quality of the image. The higher the quality the larger the +file size.
wm_padding	None	A number	The amount of padding, set in pixels, that will be applied to the +watermark to set it away from the edge of your images.
wm_vrt_alignment	bottom	top, middle, bottom	Sets the vertical alignment for the watermark image.
wm_hor_alignment	center	left, center, right	Sets the horizontal alignment for the watermark image.
wm_hor_offset	None	None	You may specify a horizontal offset (in pixels) to apply to the +watermark position. The offset normally moves the watermark to the +right, except if you have your alignment set to “right” then your offset +value will move the watermark toward the left of the image.
wm_vrt_offset	None	None	You may specify a vertical offset (in pixels) to apply to the watermark +position. The offset normally moves the watermark down, except if you +have your alignment set to “bottom” then your offset value will move the +watermark toward the top of the image.

+

Text Preferences ¶

+

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

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Preference	Default Value	Options	Description
wm_text	None	None	The text you would like shown as the watermark. Typically this will be a +copyright notice.
wm_font_path	None	None	The server path to the True Type Font you would like to use. If you do +not use this option, the native GD font will be used.
wm_font_size	16	None	The size of the text. Note: If you are not using the True Type option +above, the number is set using a range of 1 - 5. Otherwise, you can use +any valid pixel size for the font you’re using.
wm_font_color	ffffff	None	The font color, specified in hex. Both the full 6-length (ie, 993300) and +the short three character abbreviated version (ie, fff) are supported.
wm_shadow_color	None	None	The color of the drop shadow, specified in hex. If you leave this blank +a drop shadow will not be used. Both the full 6-length (ie, 993300) and +the short three character abbreviated version (ie, fff) are supported.
wm_shadow_distance	3	None	The distance (in pixels) from the font that the drop shadow should +appear.

+

Overlay Preferences ¶

+

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

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Preference	Default Value	Options	Description
wm_overlay_path	None	None	The server path to the image you wish to use as your watermark. Required +only if you are using the overlay method.
wm_opacity	50	1 - 100	Image opacity. You may specify the opacity (i.e. transparency) of your +watermark image. This allows the watermark to be faint and not +completely obscure the details from the original image behind it. A 50% +opacity is typical.
wm_x_transp	4	A number	If your watermark image is a PNG or GIF image, you may specify a color +on the image to be “transparent”. This setting (along with the next) +will allow you to specify that color. This works by specifying the “X” +and “Y” coordinate pixel (measured from the upper left) within the image +that corresponds to a pixel representative of the color you want to be +transparent.
wm_y_transp	4	A number	Along with the previous setting, this allows you to specify the +coordinate to a pixel representative of the color you want to be +transparent.

+

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:

+

90 - rotates counter-clockwise by 90 degrees.
180 - rotates counter-clockwise by 180 degrees.
270 - rotates counter-clockwise by 270 degrees.
hor - flips the image horizontally.
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();
+

+

+

+ +

+

+ + +