画像操作クラス

CodeIgniter’s Image Manipulation class lets you perform the following actions:

• 画像のリサイズ
• サムネイルの作成
• 画像の切り抜き
• 画像の回転
• 画像の合成

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.

クラスの初期化

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

画像の処理

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.

処理メソッド

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

設定

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.

「可能な操作」欄の凡例:

• R - 画像のリサイズ
• C - Image Cropping
• X - Image Rotation
• W - Image Watermarking

設定項目	初期値	選択肢	説明	有効性
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

設定ファイルによる設定

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.

画像の合成

画像の合成機能は、GD/GD2 ライブラリが必要になります。

2種類の合成

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.

画像の合成

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.

画像合成の設定

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

設定項目	初期値	選択肢	説明
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.

テキストの設定

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

設定項目	初期値	選択肢	説明
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.

オーバーレイの設定

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

設定項目	初期値	選択肢	説明
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 CI_Image_lib

initialize([$props = array()])

パラメータ array $props:  Image processing preferences 返り値:TRUE on success, FALSE in case of invalid settings 返り値型:bool

Initializes the class for processing an image.

resize()

返り値:TRUE on success, FALSE on failure 返り値型: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 設定 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()

返り値:TRUE on success, FALSE on failure 返り値型: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 設定 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()

返り値:TRUE on success, FALSE on failure 返り値型: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:

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

watermark()

返り値:TRUE on success, FALSE on failure 返り値型:bool

Creates a watermark over an image, please refer to the 画像の合成 section for more info.

clear()

返り値: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>']])

パラメータ string $open:  Error message opening tag パラメータ string $close:  Error message closing tag 返り値:Error messages 返り値型:string

Returns all detected errors formatted as a string.

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