CodeIgniter 使用手冊版本 2.1.4

Image Manipulation 類別

CodeIgniter' 的 Image Manipulation 類別讓你可以執行以下動作:

支援三個主要的影像函式庫: GD/GD2，NetPBM，以及 ImageMagick

注意: 只有 GD/GD2 函式庫才支援浮水印。 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.

初始化類別

就像其他 CodeIgniter 的類別，圖片類別必須在 controller 裡呼叫 $this->load->library 函式來初始化:

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

載入函式庫後就可以使用了。用 $this->image_lib 來使用的影像函式庫物件，以及執行各種動作。

Processing an Image 處理影像

不管你要對影像執行哪種動作(修改尺寸、裁剪、旋轉或者加上浮水印)，一般的處理流程都很雷同。你需要做些喜好設定，然後呼叫其中一個(總共有四個)可用的影像處理函數。例如你想建立縮圖，那麼 可以這麼做：

$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();

上頭的程式碼告訴 image_resize 函式庫去找一個位於 source_image 資料夾裡，名叫 mypic.jpg 的圖片，然後呼叫 GD2 image_library 影像函式庫來創建一張尺寸為 75 X 50 像素的縮圖。 啟動 maintain_ratio 選項後，縮圖會在維持原本的長寬比例下，會盡可能的接近 width 跟 height 的像素尺寸大小。 同時這張縮圖的檔名會命名為 mypic_thumb.jpg 。

注意: 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 處理函數

總共有四個可用的影像處理函數:

這些函數若執行成功會回傳 TRUE 而失敗則回傳 FALSE。 萬一失敗了，可由以下函數來取得錯誤訊息:

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

把影像處裡函數放在條件判斷中是個好方法是，萬一失敗就會印出錯誤訊息，就像:

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

注意: 你可以選擇性的指定錯誤訊息的HTML格式，只消在參數指定開頭/結尾標籤，就像:

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

Preferences 喜好設定

這邊講述了一些喜好設定，允許你依照你的需求來處理影像。

請注意並不是每個選項都對每個函數有作用。 例如只有影像裁剪才能設定 x/y 軸。同樣地，設定寬度及高度對影像裁剪就沒影響了. 表格中"可用" 這欄指出那個函數支援哪些設定。

可用的函數縮寫:

設定 預設值 其他選擇 敘述 可用
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
source_image None None Sets the source image name/path. The path must be a relative or absolute server path，not a URL. R，C，S，W
dynamic_output FALSE TRUE/FALSE (boolean) Determines whether the new image file should be written to disk or generated dynamically. 注意: 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
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 then 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 function if you save your preferences in a config file.

$this->image_lib->resize()

The image resizing function 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 (ie，mypic_thumb.jpg).

All preferences listed in the table above are available for this function except these three: rotation_angle，x_axis，and y_axis.

Creating a Thumbnail

The resizing function 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 function 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:

Resizing the Original Image

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

$this->image_lib->crop()

The cropping function 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 table above are available for this function except these: rotation_angle，width，height，create_thumb，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();
}

注意: Without a visual interface it is difficult to crop images，so this function 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.

$this->image_lib->rotate()

The image rotation function 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();
}

$this->image_lib->clear()

The clear function 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();

 

Image Watermarking

The Watermarking feature requires the GD/GD2 library.

Two Types of Watermarking

There are two types of watermarking that you can use:

Watermarking an Image

Just as with the other functions (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 參考範例:

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

注意: 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. 注意: 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.
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. 注意: 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. Note，you must use the full 6 character hex value (ie，993300)，rather than the three character abbreviated version (ie fff).
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. Note，you must use the full 6 character hex value (ie，993300)，rather than the three character abbreviated version (ie fff).
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.