path: root/user_guide_src/source/libraries/image_lib.rst

########################
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.

.. contents::
  :local:

.. raw:: html

  <div class="custom-index container"></div>

**********************
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*

.. 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>');

.. _processing-preferences:

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      R, C, X
                                                                                either of those libraries you must supply the path.                         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          R, C, X, W
                                                                                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.
**file_permissions**    0644                    (integer)                       File system permissions to apply on the resulting image file,               R, C, X, W
                                                                                writing it to the disk. WARNING: Use octal integer notation!
**quality**             90%                     1 - 100%                        Sets the quality of the image. The higher the quality the larger the        R, C, X, W
                                                                                file size.
**new_image**           None                    None                            Sets the destination image name/path. You'll use this preference when       R, C, X, W
                                                                                creating an image copy. The path must be a relative or absolute server
                                                                                path, not a URL.
**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      R
                                                                                file extension, so mypic.jpg would become mypic_thumb.jpg
**maintain_ratio**      TRUE                    TRUE/FALSE (boolean)            Specifies whether to maintain the original aspect ratio when resizing or    R, C
                                                                                use hard values.
**master_dim**          auto                    auto, width, height             Specifies what to use as the master axis when resizing or creating          R
                                                                                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.
**rotation_angle**      None                    90, 180, 270, vrt, hor          Specifies the angle of rotation when rotating images. Note that PHP         X
                                                                                rotates counter-clockwise, so a 90 degree rotation to the right must be
                                                                                specified as 270.
**x_axis**              None                    None                            Sets the X coordinate in pixels for image cropping. For example, a          C
                                                                                setting of 30 will crop an image 30 pixels from the left.
**y_axis**              None                    None                            Sets the Y coordinate in pixels for image cropping. For example, a          C
                                                                                setting of 30 will crop an image 30 pixels from the top.
======================= ======================= =============================== =========================================================================== =============

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:

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**  2                   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
***************

.. php:class:: CI_Image_lib

	.. php:method:: initialize([$props = array()])

		:param	array	$props: Image processing preferences
		:returns:	TRUE on success, FALSE in case of invalid settings
		:rtype:	bool

		Initializes the class for processing an image.

	.. php:method:: resize()

		:returns:	TRUE on success, FALSE on failure
		:rtype:	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 :ref:`processing-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.

	.. php:method:: crop()

		:returns:	TRUE on success, FALSE on failure
		:rtype:	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 :ref:`processing-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.

	.. php:method:: rotate()

		:returns:	TRUE on success, FALSE on failure
		:rtype:	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();
			}

	.. php:method:: watermark()

		:returns:	TRUE on success, FALSE on failure
		:rtype:	bool

		Creates a watermark over an image, please refer to the :ref:`watermarking`
		section for more info.		

	.. php:method:: clear()

		:rtype:	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();

	.. php:method:: display_errors([$open = '<p>[, $close = '</p>']])

		:param	string	$open: Error message opening tag
		:param	string	$close: Error message closing tag
		:returns:	Error messages
		:rtype:	string

		Returns all detected errors formatted as a string.
		::

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