diff options
Diffstat (limited to 'user_guide_src/source/libraries/image_lib.rst')
| -rw-r--r-- | user_guide_src/source/libraries/image_lib.rst | 475 |
1 files changed, 0 insertions, 475 deletions
diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst deleted file mode 100644 index 22407962f..000000000 --- a/user_guide_src/source/libraries/image_lib.rst +++ /dev/null @@ -1,475 +0,0 @@ -######################## -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* 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>'); - -.. _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** 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 -*************** - -.. 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(); |