画像の扱い

Nette\Utils\Image クラスは、サイズ変更、切り抜き、シャープ化、描画、複数画像の合成といった画像の操作を簡単にします。

PHP には画像を操作する関数が数多くあります。しかしその API はあまり使いやすくありません。ここで気持ちのよい API を用意しないなら、それは Nette Framework ではないでしょう。

インストール:

composer require nette/utils

以下の例では、次のクラスの別名が定義されているものとします。

use Nette\Utils\Image;
use Nette\Utils\ImageColor;
use Nette\Utils\ImageType;

画像の作成

たとえば 100×200 の大きさで、新しいトゥルーカラー画像を作ります。

$image = Image::fromBlank(100, 200);

背景色を指定することもできます（既定は黒です）。

$image = Image::fromBlank(100, 200, ImageColor::rgb(125, 0, 0));

あるいはファイルから画像を読み込みます。

$image = Image::fromFile('nette.jpg');

画像の保存

画像はファイルに保存できます。

$image->save('resampled.jpg');

圧縮品質は JPEG（既定 85）、WEBP（既定 80）、AVIF（既定 30）では 0〜100 の範囲で、PNG（既定 9）では 0〜9 の範囲で指定できます。

$image->save('resampled.jpg', 80); // JPEG、品質 80%

ファイルの拡張子から形式がはっきりしない場合は、定数で指定できます。

$image->save('resampled.tmp', null, ImageType::JPEG);

ディスクに保存する代わりに、画像を変数に書き出すこともできます。

$data = $image->toString(ImageType::JPEG, 80); // JPEG、品質 80%

あるいは適切な Content-Type の HTTP ヘッダーとともにブラウザへ直接送れます。

// Content-Type: image/png ヘッダーを送ります
$image->send(ImageType::PNG);

形式

対応している形式は JPEG、PNG、GIF、WebP、AVIF、BMP です。ただしお使いの PHP のバージョンもそれらに対応している必要があり、isTypeSupported()関数で確かめられます。アニメーションには対応していません。

形式は定数 ImageType::JPEG、ImageType::PNG、ImageType::GIF、ImageType::WEBP、ImageType::AVIF、ImageType::BMP で表されます。

$supported = Image::isTypeSupported(ImageType::JPEG);

読み込み時に画像の形式を知りたいですか。メソッドは第 2 パラメータでそれを返します。

$image = Image::fromFile('nette.jpg', $type);

画像そのものを読み込まずに判別するには Image::detectTypeFromFile() を使います。

サイズ変更

よくある操作が画像のサイズ変更です。現在の大きさは getWidth() と getHeight() メソッドが返します。

サイズ変更には resize() メソッドを使います。画像が 500×300 ピクセルを超えないように比率を保って縮小する例です（幅がちょうど 500px になるか、高さがちょうど 300px になり、もう一方は縦横比を保つよう計算されます）。

$image->resize(500, 300);

片方の大きさだけを指定して、もう一方を自動的に計算させることもできます。

$image->resize(500, null); // 幅 500px、高さは自動計算

$image->resize(null, 300); // 幅は自動計算、高さ 300px

どちらの大きさもパーセントで指定できます。

$image->resize('75%', 300); // 75 % × 300px

resize() の振る舞いは次のフラグで変えられます。Image::Stretch を除くすべてのフラグは縦横比を保ちます。

フラグ	説明
`Image::OrSmaller`（既定）	できあがりの大きさが指定した大きさ以下になります
`Image::OrBigger`	対象の領域を埋めます（片方の大きさが超えることもあります）
`Image::Cover`	対象の領域を埋め、はみ出した部分を切り取ります
`Image::ShrinkOnly`	縮小だけを行います（小さな画像の引き伸ばしを防ぎます）
`Image::Stretch`	縦横比を保ちません

フラグはメソッドの第 3 引数として渡します。

$image->resize(500, 300, Image::OrBigger);

フラグは組み合わせられます。

$image->resize(500, 300, Image::ShrinkOnly | Image::Stretch);

大きさのどちらか（または両方）を負の数で指定すると、画像を上下や左右に反転できます。

$flipped = $image->resize(null, '-100%'); // 上下に反転

$flipped = $image->resize('-100%', '-100%'); // 180° 回転

$flipped = $image->resize(-125, 500); // サイズ変更と左右の反転

画像のサイズを変えたあと、控えめなシャープ化で見た目を良くできます。

$image->sharpen();

切り抜き

切り抜きには crop() メソッドを使います。

$image->crop($left, $top, $width, $height);

resize() と同じく、すべての値はパーセントで指定できます。$left と $top のパーセントは、CSS の background-position プロパティと同じく、残りの領域から計算されます。

$image->crop('100%', '50%', '80%', '80%');

画像は自動的に切り抜くこともできます。たとえば黒い縁を取り除くのに使えます。

$image->cropAuto(IMG_CROP_BLACK);

cropAuto() メソッドは imagecropauto() 関数のオブジェクト指向のラッパーです。詳しくはそのドキュメントをご覧ください。

色

ImageColor::rgb() メソッドを使うと、赤・緑・青（RGB）の値で色を定義できます。CSS と同じく、0（完全に透明）から 1（完全に不透明）までの透明度も指定できます。

$color = ImageColor::rgb(255, 0, 0); // 赤
$transparentBlue = ImageColor::rgb(0, 0, 255, 0.5); // 半透明の青

ImageColor::hex() メソッドを使うと、CSS と同じように 16 進の形式で色を定義できます。#rgb、#rrggbb、#rgba、#rrggbbaa の形式に対応しています。

$color = ImageColor::hex("#F00"); // 赤
$transparentGreen = ImageColor::hex("#00FF0080"); // 半透明の緑

色は ellipse()、fill() などのほかのメソッドでも使えます。

描画と編集

画像を操作する PHP の関数はすべて使えます（メソッド一覧をご覧ください）が、オブジェクト指向の形に包まれています。

$image->filledEllipse($centerX, $centerY, $width, $height, ImageColor::rgb(255, 0, 0));

PHP のネイティブの長方形を描く関数は座標の指定がやや使いにくいので、Image クラスは代わりのものを提供します。rectangleWH()と filledRectangleWH()です。

複数画像の合成

現在の画像の上に別の画像を簡単に重ねられます。

$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, ImageColor::rgb(52, 132, 210));

// 座標はパーセントでも指定できます
$blank->place($logo, '80%', '80%'); // 右下の角の近くに置きます

重ねるときアルファチャンネルは尊重されます。さらに、重ねる画像の透明度を変えることもできます（透かしを作れます）。

$blank->place($image, '80%', '80%', 25); // 不透明度は 25%

こんな API を使うのは、まさに楽しみですね。

メソッド一覧

static fromBlank (int $width, int $height, ?ImageColor $color=null): Image

指定した大きさで新しいトゥルーカラー画像を作ります。既定の色は黒です。

static fromFile (string $file, int &$detectedFormat=null, string &$warnings=null): Image

ファイルから画像を読み込み、その種類を $detectedFormat に返します。$warnings を渡すと、画像デコーダーの致命的でない警告が PHP の警告として発せられる代わりにそこへ保存されます。警告がなければ null のままです。

static fromString (string $s, int &$detectedFormat=null, string &$warnings=null): Image

文字列から画像を読み込み、その種類を $detectedFormat に返します。$warnings を渡すと、画像デコーダーの致命的でない警告が PHP の警告として発せられる代わりにそこへ保存されます。警告がなければ null のままです。

static rgb (int $red, int $green, int $blue, int $transparency=0): array

この関数は ImageColor クラスに置き換えられました。色をご覧ください。

static typeToExtension (int $type): string

指定した種類のファイル拡張子を返します。

static typeToMimeType (int $type): string

指定した種類の MIME タイプを返します。

static extensionToType (string $extension): int

ファイルの拡張子から画像の種類を返します。

static detectTypeFromFile (string $file, int &$width=null, int &$height=null): ?int

画像ファイルの種類を返し、$width と $height パラメータにその大きさも返します。

static detectTypeFromString (string $s, int &$width=null, int &$height=null): ?int

文字列から画像の種類を返し、$width と $height パラメータにその大きさも返します。

static isTypeSupported (int $type): bool

指定した画像の種類に対応しているかを調べます。

static getSupportedTypes(): array

対応している画像の種類の配列を返します。

static calculateTextBox (string $text, string $fontFile, float $size, float $angle=0, array $options=[]): array

特定のフォントと大きさで、テキストを囲む長方形の寸法を計算します。キー left、top、width、height を含む連想配列を返します。テキストが左側のカーニングのはみ出しで始まる場合、左のマージンは負になることがあります。

affine (array $affine, ?array $clip=null): Image

元画像をアフィン変換した画像を返します。切り抜き領域を任意で指定できます。（詳しくはこちら）

alphaBlending (bool $on): void

トゥルーカラー画像への描画に 2 つの異なるモードを与えます。ブレンドモードでは、setPixel() などすべての描画関数に渡された色のアルファチャンネル成分が、下の色をどれだけ透かすかを決めます。その結果、その地点の既存の色と描画する色が自動的に混ぜられ、結果が画像に保存されます。できあがるピクセルは不透明です。非ブレンドモードでは、描画する色がアルファチャンネルの情報も含めてそのままコピーされ、対象のピクセルを置き換えます。パレット画像への描画ではブレンドモードは使えません。（詳しくはこちら）

antialias (bool $on): void

線と輪郭だけの多角形について、高速なアンチエイリアス描画を有効にします。アルファ成分には対応しておらず、直接のブレンド操作で働きます。トゥルーカラー画像でのみ働きます。

アンチエイリアスのかかった基本図形を透明な背景色とともに使うと、思わぬ結果になることがあります。ブレンドの方法は背景色をほかの色と同じように扱います。アルファ成分に対応していないため、アルファにもとづくアンチエイリアスはできません。（詳しくはこちら）

arc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color): void

指定した座標を中心とする円弧を描きます。（詳しくはこちら）

colorAllocate (int $red, int $green, int $blue): int

指定した RGB 成分から成る色を表す色識別子を返します。画像で使う各色を作るために呼ぶ必要があります。（詳しくはこちら）

colorAllocateAlpha (int $red, int $green, int $blue, int $alpha): int

透明度のパラメータ $alpha が加わる点を除き、colorAllocate() とまったく同じように振る舞います。（詳しくはこちら）

colorAt (int $x, int $y): int

画像の指定した位置のピクセルの色インデックスを返します。トゥルーカラー画像なら、この関数はそのピクセルの RGB 値を整数として返します。個々の赤・緑・青の成分の値にアクセスするには、ビットシフトとマスクを使ってください。（詳しくはこちら）

colorClosest (int $red, int $green, int $blue): int

画像のパレットの中で、指定した RGB 値に「最も近い」色のインデックスを返します。望みの色とパレットの各色との「距離」は、RGB の値が 3 次元空間の点を表すかのように計算されます。（詳しくはこちら）

colorClosestAlpha (int $red, int $green, int $blue, int $alpha): int

画像のパレットの中で、指定した RGB 値と $alpha の水準に「最も近い」色のインデックスを返します。（詳しくはこちら）

colorClosestHWB (int $red, int $green, int $blue): int

指定した色に対して、色相・白さ・黒さが最も近い色のインデックスを取得します。（詳しくはこちら）

colorDeallocate (int $color): void

colorAllocate() や colorAllocateAlpha() で以前に確保した色を解放します。（詳しくはこちら）

colorExact (int $red, int $green, int $blue): int

画像のパレットの中の、指定した色のインデックスを返します。（詳しくはこちら）

colorExactAlpha (int $red, int $green, int $blue, int $alpha): int

画像のパレットの中の、指定した色 + アルファのインデックスを返します。（詳しくはこちら）

colorMatch (Image $image2): void

画像のパレット版の色を、トゥルーカラー版により近づけます。（詳しくはこちら）

colorResolve (int $red, int $green, int $blue): int

求めた色に対して、正確な色か、可能な限り近い代わりの色のインデックスを返します。（詳しくはこちら）

colorResolveAlpha (int $red, int $green, int $blue, int $alpha): int

求めた色に対して、正確な色か、可能な限り近い代わりの色のインデックスを返します。（詳しくはこちら）

colorSet (int $index, int $red, int $green, int $blue, int $alpha=0): void

パレットの指定したインデックスを、指定した色に設定します。（詳しくはこちら）

colorsForIndex (int $index): array

指定したインデックスの色を取得します。（詳しくはこちら）

colorsTotal(): int

画像のパレットの色数を返します。（詳しくはこちら）

colorTransparent (?int $color=null): int

画像の透明色を取得または設定します。（詳しくはこちら）

convolution (array $matrix, float $div, float $offset): void

指定した係数とオフセットを使って、画像に畳み込み行列を適用します。（詳しくはこちら）

Bundled GD extension が必要なので、どこでも動くとは限りません。

copy (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH): void

座標 $srcX、$srcY から幅 $srcW、高さ $srcH の $src の一部を画像にコピーします。指定された部分は座標 $dstX、$dstY にコピーされます。（詳しくはこちら）

copyMerge (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void

copyMergeGray (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $srcW, int $srcH, int $opacity): void

座標 $srcX、$srcY から幅 $srcW、高さ $srcH の $src の一部を画像にコピーします。指定された部分は座標 $dstX、$dstY にコピーされます。

この関数は copyMerge() と同じですが、合成の際に、コピー操作の前に対象のピクセルをグレースケールに変換することで元画像の色相を保ちます。（詳しくはこちら）

copyResampled (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

ある画像の長方形の部分を別の画像にコピーし、ピクセルの値をなめらかに補間します。とくに画像を縮小しても鮮明さが大きく保たれます。

言い換えれば、copyResampled() は $src の位置 ($srcX,$srcY) から幅 $srcW、高さ $srcH の長方形の領域を取り、画像の位置 ($dstX,$dstY) にある幅 $dstW、高さ $dstH の長方形の領域に置きます。

元と先の座標や幅・高さが異なる場合は、画像の断片が適切に引き伸ばされたり縮められたりします。座標は左上の角を指します。この関数は同じ画像の中の領域をコピーするのにも使えますが、領域が重なると結果は予測できません。（詳しくはこちら）

copyResized (Image $src, int $dstX, int $dstY, int $srcX, int $srcY, int $dstW, int $dstH, int $srcW, int $srcH): void

ある画像の長方形の部分を別の画像にコピーします。言い換えれば、copyResized() は $src の位置 ($srcX,$srcY) から幅 $srcW、高さ $srcH の長方形の領域を取り、画像の位置 ($dstX,$dstY) にある幅 $dstW、高さ $dstH の長方形の領域に置きます。

crop (int|string $left, int|string $top, int|string $width, int|string $height): Image

画像を指定した長方形の領域に切り抜きます。大きさはピクセル単位の整数でも、パーセントの文字列（'50%' など）でも指定できます。

cropAuto (int $mode=0, float $threshold=.5, ?ImageColor $color=null): Image

指定した $mode に従って画像を自動的に切り抜きます。（詳しくはこちら）

ellipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

指定した座標を中心とする楕円を描きます。（詳しくはこちら）

fill (int $x, int $y, ImageColor $color): void

指定した座標（左上が 0, 0）から始めて、指定した $color で塗りつぶします。（詳しくはこちら）

filledArc (int $centerX, int $centerY, int $width, int $height, int $startAngle, int $endAngle, ImageColor $color, int $style): void

指定した座標を中心とする部分的な円弧を描きます。（詳しくはこちら）

filledEllipse (int $centerX, int $centerY, int $width, int $height, ImageColor $color): void

指定した座標を中心とする楕円を描きます。（詳しくはこちら）

filledPolygon (array $points, ImageColor $color): void

画像に塗りつぶされた多角形を作ります。（詳しくはこちら）

filledRectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

画像に、点 ($x1, $y1) から点 ($x2, $y2) までの $color で塗りつぶされた長方形を作ります。点 (0, 0) は画像の左上の角です。（詳しくはこちら）

filledRectangleWH (int $x, int $y, int $width, int $height, ImageColor $color): void

画像に、点 ($x, $y) から幅 $width、高さ $height の $color で塗りつぶされた長方形を作ります。点 (0, 0) は画像の左上の角です。

fillToBorder (int $x, int $y, ImageColor $borderColor, ImageColor $color): void

境界の色を $borderColor で定めて塗りつぶします。塗りつぶしの開始点は ($x, $y)（左上が 0, 0）で、領域は色 $color で塗られます。（詳しくはこちら）

filter (int $filtertype, int …$args): void

指定したフィルタ $filtertype を画像に適用します。（詳しくはこちら）

flip (int $mode): void

指定した $mode で画像を反転します。（詳しくはこちら）

ftText (float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array

画像にテキストを書き込みます。（詳しくはこちら）

gammaCorrect (float $inputgamma, float $outputgamma): void

入力と出力のガンマを与えて、画像にガンマ補正を適用します。（詳しくはこちら）

getClip(): array

現在のクリッピング長方形、つまりその外側にはピクセルが描かれない領域を取得します。（詳しくはこちら）

getHeight(): int

画像の高さを返します。

getImageResource(): GdImage

内部の GD 画像リソースを返します。

getWidth(): int

画像の幅を返します。

interlace (?int $interlace=null): int

インターレースを有効または無効にします。インターレースが有効で画像を JPEG として保存すると、プログレッシブ JPEG として保存されます。（詳しくはこちら）

isTrueColor(): bool

画像がトゥルーカラー画像かを調べます。（詳しくはこちら）

layerEffect (int $effect): void

レイヤー効果を使うためのアルファブレンドのフラグを設定します。（詳しくはこちら）

line (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

指定した 2 点のあいだに線を描きます。（詳しくはこちら）

openPolygon (array $points, ImageColor $color): void

画像に開いた多角形を描きます。polygon() と違い、最後の点と最初の点のあいだには線を描きません。（詳しくはこちら）

paletteCopy (Image $source): void

$source から画像にパレットをコピーします。（詳しくはこちら）

paletteToTrueColor(): void

パレットベースの画像をトゥルーカラー画像に変換します。（詳しくはこちら）

place (Image $image, int|string $left=0, int|string $top=0, int $opacity=100): Image

現在の画像の座標 ($left, $top) に $image をコピーします。座標はピクセル単位の整数でも、パーセントの文字列（'50%' など）でも指定できます。

polygon (array $points, ImageColor $color): void

画像に多角形を作ります。（詳しくはこちら）

rectangle (int $x1, int $y1, int $x2, int $y2, ImageColor $color): void

指定した座標に長方形を作ります。（詳しくはこちら）

rectangleWH (int $x, int $y, int $width, int $height, ImageColor $color): void

指定した座標に、幅と高さを使って長方形を作ります。

resize (int|string $width, int|string $height, int $mode=Image::OrSmaller): Image

画像のサイズを変えます。詳しくはこちら。大きさはピクセル単位の整数でも、パーセントの文字列（'50%' など）でも指定できます。

resolution (?int $resX=null, ?int $resY=null): mixed

画像の解像度を DPI（ドット毎インチ）で設定・取得できます。省略可能なパラメータをどちらも渡さない場合は、現在の解像度が添字配列として返されます。$resX だけを渡すと、水平と垂直の解像度がその値に設定されます。両方を渡すと、水平と垂直の解像度がそれぞれの値に設定されます。

解像度は、この種の情報に対応する形式（現在は PNG と JPEG）で画像を読み書きするときのメタ情報としてのみ使われます。描画の操作には影響しません。新しい画像の既定の解像度は 96 DPI です。（詳しくはこちら）

rotate (float $angle, ImageColor $backgroundColor): Image

画像を指定した角度 $angle（度数）だけ回転します。回転の中心は画像の中心で、回転後の画像は元画像と異なる大きさになることがあります。（詳しくはこちら）

Bundled GD extension が必要なので、どこでも動くとは限りません。

save (string $file, ?int $quality=null, ?int $type=null): void

画像をファイルに保存します。

圧縮品質は JPEG（既定 85）、WEBP（既定 80）、AVIF（既定 30）では 0〜100 の範囲、PNG（既定 9）では 0〜9 の範囲です。ファイルの拡張子から種類がはっきりしない場合は、ImageType の定数のひとつで指定できます。

saveAlpha (bool $saveflag): void

PNG 画像を保存するとき、（単色の透明ではなく）完全なアルファチャンネルの情報を保存するかどうかを決めるフラグを設定します。

Nette は Image のコンストラクタでこのフラグを有効にするので、fromFile()、fromString()、fromBlank() で読み込んだり作ったりした画像はアルファチャンネルを保ちます。既定のブレンドモードでは、描画する色のアルファは結果を混ぜるためだけに使われて保存されないので、描画した透明度を残したいなら先に alphaBlending(false) を呼んでください。（詳しくはこちら）

scale (int $newWidth, int $newHeight=-1, int $mode=IMG_BILINEAR_FIXED): Image

指定した補間アルゴリズムを使って画像を拡大縮小します。（詳しくはこちら）

send (int $type=ImageType::JPEG, ?int $quality=null): void

画像をブラウザに出力します。

圧縮品質は JPEG（既定 85）、WEBP（既定 80）、AVIF（既定 30）では 0〜100 の範囲、PNG（既定 9）では 0〜9 の範囲です。

setBrush (Image $brush): void

特別な色 IMG_COLOR_BRUSHED や IMG_COLOR_STYLEDBRUSHED で描画するとき、すべての線描画関数（line() や polygon() など）が使うブラシ画像を設定します。（詳しくはこちら）

setClip (int $x1, int $y1, int $x2, int $y2): void

現在のクリッピング長方形、つまりその外側にはピクセルが描かれない領域を設定します。（詳しくはこちら）

setInterpolation (int $method=IMG_BILINEAR_FIXED): void

補間の方法を設定します。rotate() と affine() メソッドに影響します。（詳しくはこちら）

getInterpolation(): int

rotate() と affine() メソッドが使う現在の補間の方法を返します。

setPixel (int $x, int $y, ImageColor $color): void

指定した座標に点を描きます。（詳しくはこちら）

setStyle (array $style): void

特別な色 IMG_COLOR_STYLED で描画するとき、あるいは色 IMG_COLOR_STYLEDBRUSHED で画像の線を描くとき、すべての線描画関数（line() や polygon() など）が使うスタイルを設定します。（詳しくはこちら）

setThickness (int $thickness): void

長方形、多角形、円弧などを描くときの線の太さを $thickness ピクセルに設定します。（詳しくはこちら）

setTile (Image $tile): void

特別な色 IMG_COLOR_TILED で塗りつぶすとき、すべての領域塗りつぶし関数（fill() や filledPolygon() など）が使うタイル画像を設定します。

タイルとは、繰り返しの模様で領域を埋めるのに使う画像です。どんな画像でもタイルにでき、colorTransparent() でタイル画像の透明色インデックスを設定すれば、下の領域の一部を透かして見せるタイルを作れます。（詳しくはこちら）

sharpen(): Image

画像をシャープにします。

Bundled GD extension が必要なので、どこでも動くとは限りません。

toString (int $type=ImageType::JPEG, ?int $quality=null): string

画像を文字列として出力します。

圧縮品質は JPEG（既定 85）、WEBP（既定 80）、AVIF（既定 30）では 0〜100 の範囲、PNG（既定 9）では 0〜9 の範囲です。

trueColorToPalette (bool $dither, int $ncolors): void

トゥルーカラー画像をパレット画像に変換します。（詳しくはこちら）

ttfText (float $size, float $angle, int $x, int $y, ImageColor $color, string $fontFile, string $text, array $options=[]): array

指定したテキストを画像に書き込みます。（詳しくはこちら）