画像操作クラス
CodeIgniterの画像操作クラスを使うと、次のことが行えます:
- 画像のリサイズ
- サムネイルの作成
- 画像の切り抜き
- 画像の回転
- 画像の合成
次の3つのよく使われている画像ライブラリすべてに対応しています: GD/GD2、NetPBM、および ImageMagick
Note: 画像の合成は、GD/GD2 ライブラリを使用した場合のみ利用可能です。 加えて、他のライブラリを指定した場合でも、 画像のプロパティを取得するためにはGDが必要になります。 しかし、画像の処理に関しては指定したライブラリだけで可能です。
クラスの初期化
CodeIgniter のほとんどのクラスと同様に、 画像クラスは $this->load->library メソッドを使ってコントローラの中で初期化します:
$this->load->library('image_lib');
ライブラリが読み込まれると、使う準備ができます。すべてのメソッドを呼び出すには、次の画像ライブラリオブジェクトを使います: $this->image_lib
画像の処理
処理の種類(リサイズ、切り抜き、回転、または、合成)にかかわらず、基本的な手順は同じです。 4つの利用可能な処理のうちひとつを呼び出すとき、その行いたい処理に対応した設定項目をセットすることができます。 たとえば、画像のサムネイルを作成するには次のようにします:
$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();
上のコードでは、source_image に指定したフォルダの中から mypic.jpg を探し出して、 GD2 image_library を使って75 X 50 ピクセルのサムネイルを作成するよう、image_resize メソッドに設定しています。 maintain_ratio オプションが有効になっているので、サムネイルはもともとのアスペクト比を維持したまま、 指定された width（幅） と height（高さ） にできるだけ近づけるようにします。 サムネイルは mypic_thumb.jpgという名前になります。
Note: 画像クラスに全ての処理を許可するため、 画像が含まれるフォルダと画像のパーミッションを書き込み可能に設定する必要があります。
Note: 画像処理はいくつかの操作において，かなりのサーバのメモリを必要とします。画像処理の最中に out of memory エラーに遭遇した場合は，最大サイズの制限や PHP の memory_limit の調整が必要かも知れません。
処理メソッド
利用可能な処理メソッドは4つあります:
- $this->image_lib->resize()
- $this->image_lib->crop()
- $this->image_lib->rotate()
- $this->image_lib->watermark()
- $this->image_lib->clear()
これらのメソッドは、処理が成功したら TRUE を、失敗したら FALSE を返します。 もし失敗した場合は、下記のメソッドを使って、エラーメッセージを取得できます:
echo $this->image_lib->display_errors();
よいプラクティスは、次のように、処理メソッドを呼び出す時はいつも、失敗した時にエラーを表示することです:
if ( ! $this->image_lib->resize())
{
echo $this->image_lib->display_errors();
}
Note: オプションで、次のようにメソッドに開始/終了タグを渡して、 エラーメッセージを HTML で整形することもできます:
$this->image_lib->display_errors('<p>', '</p>');
設定
ニーズに合わせた処理に調整するため、下で説明している設定項目を利用できます。
どのメソッドでも全ての設定項目が利用可能なわけではないのを注意してください。 たとえば、x / y 軸の設定項目は、切り抜きのみ指定可能です。同じく、width と height の設定項目は、切り抜き処理では有効ではありません。 "使用可能な操作" の列に、どのメソッドでその設定項目がサポートされているかが示されています。
「可能な操作」欄の凡例:
- R - 画像のリサイズ
- C - 画像の切り抜き
- X - 画像の回転
- W - 画像の合成
| 設定項目 | 初期値 | 選択肢 | 説明 | 可能な操作 |
|---|---|---|---|---|
| image_library | GD2 | GD、GD2, ImageMagick、NetPBM | 使用するイメージライブラリを設定します。 | R, C, X, W |
| library_path | なし | なし | ImageMagick または NetPBM libraryへのサーバパスを指定してください。どちらかのライブラリを使う場合は、パスを指定する必要があります。 | R, C, X |
| source_image | なし | なし | 処理を施すもとになる画像の ファイル名/パス を指定します。パスは、URLではなく、サーバの相対、または、絶対パスを指定する必要があります。 | R, C, S, W |
| dynamic_output | FALSE | TRUE/FALSE (ブール値) | 新しい画像ファイルをディスクに書き込むか、動的に生成するかを決めます。Note: 動的に生成する設定を選んだ場合、画像は一度にひとつだけしか表示できず、ページ上に配置することもできません。単に、イメージヘッダに続いて、画像の生データを動的にブラウザに出力します。 | R, C, X, W |
| quality | 90% | 1 - 100% | 画質を指定します。画質が高ければ、ファイルサイズも大きくなります。 | R, C, X, W |
| new_image | なし | なし | 出力対象の画像ファイル名/パスをセットします。この設定項目は、画像のコピーを作成するときに使います。パスは、URLではなく、サーバの相対、または、絶対パスを指定する必要があります。 | R, C, X, W |
| width | なし | なし | 画像に設定したい幅をセットします。 | R, C |
| height | なし | なし | 画像に設定したい高さをセットします。 | R, C |
| create_thumb | FALSE | TRUE/FALSE (ブール値) | 画像処理メソッドに、サムネイルを作成するかどうかを設定します。 | R |
| thumb_marker | _thumb | なし | サムネイルの識別子を指定します。ここで指定したものが拡張子の直前に挿入されます。mypic.jpg の場合はmypic_thumb.jpg になります。 | R |
| maintain_ratio | TRUE | TRUE/FALSE (ブール値) | リサイズされるときや、固定の値を指定したとき、もとの画像のアスペクト比を維持するかどうかを指定します。 | R, C |
| master_dim | auto | auto、width、height | リサイズするか、またはサムネイルを作成するとき、基準軸としてどれを使用したらよいかを指定します。たとえば、イメージを100X75ピクセルにリサイズしたいとします。元の画像サイズが縦も横も両方ぴったりリサイズできないものであるとき[ 訳注:アスペクト比を固定している場合など ]、この設定により、どの軸を絶対の基準の値として使用すべきかが決まります。"auto" にすると、画像の高さが幅より長いか、あるいはその逆かにより、軸が自動的に決定されます。 | R |
| rotation_angle | なし | 90、180、270、vrt、hor | 画像を回転するときの角度を指定します。PHP では反時計回りに回転するのを注意してください。ですので、右に90度回転させるには、270を指定しなければなりません。 | X |
| x_axis | なし | なし | 切り取る X 座標 をピクセルで指定します。たとえば、30に指定した場合、左から30ピクセルのところで切り取られます。 | C |
| y_axis | なし | なし | 切り取る Y 座標 をピクセルで指定します。たとえば、30に指定した場合、上から30ピクセルのところで切り取られます。 | C |
設定ファイルによる設定
上の方法で設定したくない場合は、代わりに設定ファイルに記述することができます。 単純に、image_lib.php という名前で新しいファイルを作成し、$config という名前の配列をそのファイルに書きます。 config/image_lib.php にファイルを保存すると、自動的にそれが使用されます。 設定ファイルに設定を保存した場合は、$this->image_lib->initialize メソッドを使用してはいけません。
$this->image_lib->resize()
画像リサイズメソッドを使うと、元の画像をリサイズすることができ、 （リサイズするかどうかにかかわらず）コピーを作成したり、サムネイルを作成したりできます。
実用的な目的では、サムネイルの場合、名前の一部にサムネイルのマークがつく（たとえば、mypic_thumb.jpg）以外は、 コピーの作成とサムネイルの作成とに違いはありません。
このメソッドでは、上の表でリストアップした設定項目のうち次の3つを除いてすべてが利用可能です: rotationa_angle, x_axis, y_axis。
サムネイルの作成
次の設定項目を TRUE にすると、リサイズメソッドではサムネイルファイルが作成されます（元画像はそのまま保存されます）:
$config['create_thumb'] = TRUE;
この一つの設定項目で、サムネイルが作成されるかどうかが決まります。
コピーの作成
次の設定項目にパスまたは新しいファイル名（あるいはその両方）を指定すると、 リサイズメソッドでは画像ファイルのコピーが作成されます（元画像はそのまま保存されます）:
$config['new_image'] = '/path/to/new_image.jpg';
この設定項目についての注意事項です:
- 新しい画像の名前だけが指定されている場合は、元画像と同じフォルダにコピーが置かれます。
- パスだけが指定されている場合、新しい画像ファイルは、その保存先に、元画像と同じ名前で保存されます。
- パスと画像の名前の両方が指定されている場合は、指定された保存先と名前で画像が保存されます。
元画像のリサイズ
上で使われている2つの設定項目( create_thumb と new_image )を指定しない場合、 リサイズメソッドでは代わりに元画像が処理の対象になります。
$this->image_lib->crop()
切り抜きメソッドは、次のように切り取る場所を指定する X および Y 軸 (ピクセル) を設定する必要があるのを除いて、 リサイズメソッドと大体同じように動作します:
$config['x_axis'] = '100';
$config['y_axis'] = '40';
このメソッドでは、上の表でリストアップした設定項目のうち次のものを除いてすべてが利用可能です: rotation、width、height、create_thumb、new_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: ビジュアルインターフェースなしに画像の切り取りをするのは難しいので、 このメソッドはそういったインターフェースを構築しない場合には、あまり役に立たないかもしれません。 そのインターフェースとは、ちょうど、私たちが開発した ExpressionEngine のフォトギャラリーモジュールで使われているようなもののことです。 私たちが追加したのは、切り取る範囲を選択可能な JavaScript の UI でした。
$this->image_lib->rotate()
画像回転メソッドは、設定で回転する角度を指定する必要があります:
$config['rotation_angle'] = '90';
回転には5つのオプションがあります:
- 90 - 反時計回りに90度回転します。
- 180 - 反時計回りに180度回転します。
- 270 - 反時計回りに270度回転します。
- hor - 水平方向に反転します[訳注:左右を反転します]。
- vrt - 垂直方向に反転します[訳注:上下を反転します]。
下記は、画像を回転させる方法の例です:
$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()
clearメソッドは、画像処理に使われたすべての値をリセットします。ループの中で画像処理をするときに使います。
$this->image_lib->clear();
画像の合成
画像の合成機能は、GD/GD2 ライブラリが必要になります。
2種類の合成
次の2つのタイプの合成が利用できます:
- テキスト: メッセージの合成は指定した TrueType フォントか、GD ライブラリで組み込みでサポートされている文字のどちらかでテキストをもとに生成されます。 TrueType を使用する場合、GD のインストール時に、TrueType をサポートするようコンパイルれている必要があります （ほとんどはそうなっていますが、すべてそうだとは限りません）。
- オーバーレイ: 画像（たいていは透過 PNG か透過 GIF ）のオーバーレイにより、 元の画像に合成するイメージを重ねて合成メッセージが生成されます。
画像の合成
他のメソッドのように(リサイズ、切り抜き、および、回転)画像合成の一般的な処理は、 処理したい内容に応じた設定を指定した後、画像合成メソッドを呼び出して行われます。 次は、例です:
$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();
上の例では、16ピクセルの TrueType フォントを "Copyright 2006 - John Doe" というテキストを作成するのに使用しています。 合成する画像は、下詰めの中央揃えで、画像の下から20ピクセルのところに配置されます。
Note: 画像クラスのどんな処理も利用できるようにするには、画像ファイルに"書き込み"のパーミッションがある必要があります。たとえば、パーミッションを 777 に設定してください。
画像合成の設定
この表は、両方のタイプの画像合成(テキストまたはオーバレイ)で利用可能な設定項目を示したものです。
| 設定項目 | 初期値 | 選択肢 | 説明 |
|---|---|---|---|
| wm_type | text | text、overlay | 画像合成のタイプを指定します。 |
| source_image | なし | なし | 画像ファイルの 名前/パス を指定します。パスは、URL ではなくサーバの相対または絶対パスで指定しなければなりません。 |
| dynamic_output | FALSE | TRUE/FALSE (ブール値) | 新しい画像ファイルをディスクに書き込むか、動的に生成するかを決めます。Note: 動的に生成する設定を選んだ場合、画像は一度にひとつだけしか表示できず、ページ上に配置することもできません。単に、イメージヘッダに続いて、画像の生データを動的にブラウザに出力します。 |
| quality | 90% | 1 - 100% | 画質を指定します。画質が高ければ、ファイルサイズも大きくなります。 |
| padding | なし | 数字 | 余白の量をピクセルで指定します。余白は、画像の端からどのくらい離れるかを指定できます。 |
| wm_vrt_alignment | bottom | top、middle、bottom | 合成画像の縦方向の整列を指定します。 |
| wm_hor_alignment | center | left、center、 right | 合成画像の横方向の整列を指定します。 |
| wm_hor_offset | なし | なし | 合成画像に適用する 水平方向のオフセット(ピクセル) を指定できます。このオフセットは、通常、合成画像を右へずらすものですが、横方向の整列を "右" に設定している場合、左方向に向かってずれます。 |
| wm_vrt_offset | なし | なし | 合成画像に適用する 垂直方向のオフセット(ピクセル) を指定できます。このオフセットは、通常、合成画像を下へずらすものですが、縦方向の整列を "下" に設定している場合、上方向に向かってずれます。 |
テキストの設定
この表は、テキストタイプの画像合成で利用可能な設定項目を示したものです。
| 設定項目 | 初期値 | 選択肢 | 説明 |
|---|---|---|---|
| wm_text | なし | なし | 合成画像として表示したいテキストです。著作権の表示がよくあるケースです。 |
| wm_font_path | なし | なし | 使用したい TrueType フォントのサーバパスです。この項目を指定しなかった場合、GD の組み込みフォントが使用されます。 |
| wm_font_size | 16 | なし | テキストのサイズ。Note: 上の TrueType オプションを使わなかった場合、1-5で番号を指定します。逆に TrueType オプションを使った場合は、使用するフォントにおいて正しいピクセルサイズであればどの値でも使えます。 |
| wm_font_color | ffffff | なし | フォントの色を16進数で指定します。Note: 16進を、3文字の省略形 (たとえば fff )でなく、6桁 (たとえば 993300)で指定します。 |
| wm_shadow_color | なし | なし | フォントのシャドウカラーを16進数で指定します。空にしておくと、ドロップシャドウは使用されません。Note: 16進を、3文字の省略形 (たとえば fff )でなく、6桁 (たとえば 993300)で指定します。 |
| wm_shadow_distance | 3 | なし | ドロップシャドウを表示するフォントからの距離 (ピクセル)。 |
オーバーレイの設定
この表は、オーバーレイタイプの画像合成で利用可能な設定項目を示したものです。
| 設定項目 | 初期値 | 選択肢 | 説明 |
|---|---|---|---|
| wm_overlay_path | なし | なし | 合成に使用したい画像のサーバパス。オーバーレイで合成する場合のみの必須項目です。 |
| wm_opacity | 50 | 1 - 100 | 画像の不透明度。 合成画像の不透明度 (透明度) を指定できます。これにより、合成する画像は、薄くなって、背後にある元の画像の詳細を完全には隠しません。50% の不透明度が典型的です。 |
| wm_x_transp | 4 | 数字 | PNG または GIF 画像が合成する画像の場合、イメージの "透過"する色を指定できます。下記の設定項目と同時に使用すると、この設定で、色を指定できます。透明にしたい色が表されている画素をイメージ上での(左上から測られる) "X" および "Y" ピクセル座標の位置を指定することで動作します。 |
| wm_y_transp | 4 | 数字 | 上の設定項目と同時に使用します。この設定項目で、透明にしたい色の画素がある座標を指定します。 |