画像の操作

Nette\Utils\Image クラスは、リサイズ、切り抜き、シャープ化、描画、複数の画像の結合など、画像の操作を簡素化します。

PHPには、画像を操作するための豊富な関数セットがあります。しかし、そのAPIはあまり使いやすくありません。Nette FrameworkがセクシーなAPIを提供しないわけがありません。

インストール:

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%

または、適切なHTTPヘッダー Content-Type と共にブラウザに直接送信します:

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

1つの寸法のみを指定し、もう一方は計算させることも可能です:

$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): Image

ファイルから画像を読み込み、そのタイプを $detectedFormat で返します。

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

文字列から画像を読み込み、そのタイプを $detectedFormat で返します。

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

オプションのクリッピング領域を使用して、src画像のアフィン変換された画像を含む画像を返します。(詳細)

affineMatrixConcat (array $m1, array $m2): array

2つのアフィン変換行列の連結を返します。これは、同じ画像に複数の変換を一度に適用する場合に便利です。(詳細)

affineMatrixGet (int $type, ?mixed $options=null): array

アフィン変換行列を返します。(詳細)

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

パレットの色を2番目の画像に合わせます。(詳細)

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): 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

$src の一部を、座標 $srcX、$srcY から始まり、幅 $srcW、高さ $srcH で画像にコピーします。定義された部分は座標 $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

$src の一部を、座標 $srcX、$srcY から始まり、幅 $srcW、高さ $srcH で画像にコピーします。定義された部分は座標 $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 から幅 $srcW、高さ $srcH の矩形領域を位置 ($srcX, $srcY) で取得し、それを幅 $dstW、高さ $dstH の画像の矩形領域に位置 ($dstX, $dstY) で配置します。

ソースとターゲットの座標、幅、高さが異なる場合、画像フラグメントの対応する拡大または縮小が実行されます。座標は左上隅を基準とします。この関数は同じ画像内の領域をコピーするために使用できますが、領域が重なる場合、結果は予測できません。(詳細)

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

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

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

画像を特定の矩形領域に切り抜きます。寸法はピクセル単位の整数またはパーセンテージの文字列（例: '50%'）で指定できます。

cropAuto (int $mode=-1, 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 $left, int $top, int $width, int $height, ImageColor $color): void

点 $left & $top から始まり、幅 $width、高さ $height の画像内に $color で塗りつぶされた矩形を作成します。点 0, 0 は画像の左上隅です。

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

境界線の色が $border で定義された塗りつぶしを描画します。塗りつぶしの開始点は $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(): resource|GdImage

元のリソースを返します。

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

$image を座標 $left と $top の画像にコピーします。座標はピクセル単位の整数またはパーセンテージの文字列（例: '50%'）で指定できます。

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

画像内に多角形を作成します。(詳細)

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

指定された座標に矩形を作成します。(詳細)

rectangleWH (int $left, int $top, int $width, int $height, ImageColor $color): void

指定された座標に矩形を作成します。

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

画像のサイズを変更します。詳細はこちら。寸法はピクセル単位の整数またはパーセンテージの文字列（例: '50%'）で指定できます。

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

画像の解像度をDPI（ドット/インチ）で設定または返します。オプションのパラメータが指定されていない場合、現在の解像度がインデックス付き配列として返されます。$resX のみが指定されている場合、水平および垂直解像度がこの値に設定されます。両方のオプションパラメータが指定されている場合、水平および垂直解像度がこれらの値に設定されます。

解像度は、この種の情報をサポートする形式（現在はPNGとJPEG）で画像が読み書きされる際のメタ情報としてのみ使用されます。描画操作には影響しません。新しい画像のデフォルト解像度は96 DPIです。(詳細)

rotate (float $angle, int $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画像を保存するときに、完全なアルファチャンネル情報（単色透明度とは対照的に）を保持するかどうかを示すフラグを設定します。

アルファチャンネルを最初に保持するには、アルファブレンドを無効にする必要があります（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() メソッドに影響を与える補間メソッドを設定します。(詳細)

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

指定されたテキストを画像に出力します。(詳細)