| ######################## |
| 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 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 generating 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 shown 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 shown 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 shown 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->diplay_errors(); |