画像にフィルタを適用する

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — 画像にフィルタを適用する

### 説明

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

imagefilter() は、指定したフィルタ `filter` を `image` に適用します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`filter`

  `filter` は、以下のいずれかです。

  - `IMG_FILTER_NEGATE`: 画像の色を反転させます。
  - `IMG_FILTER_GRAYSCALE`: REC.601 luma (Y') の計算と同じ係数を使い、 重み付けを赤、緑、青のコンポーネントごとに変えることで、 画像を白黒にします。アルファ値は保持されます。 パレットの制限のため、パレット画像の結果は異なるかもしれません。
  - `IMG_FILTER_BRIGHTNESS`: 画像の輝度を変更します。 輝度レベルを `args` で設定します。輝度の範囲は -255 から 255 までです。
  - `IMG_FILTER_CONTRAST`: 画像のコントラストを 変更します。コントラストのレベルを `args` で設定します。
  - `IMG_FILTER_COLORIZE`: `IMG_FILTER_GRAYSCALE` と似ていますが、 色を指定することが可能です。 `args`、`arg2` および `arg3` を使用して `red`、`green`、 `blue` の値を指定します。また `arg4` を使用して `alpha` チャネルの値を指定します。 各値の範囲は 0 から 255 までです。
  - `IMG_FILTER_EDGEDETECT`: エッジを検出し、 画像のエッジを強調します。
  - `IMG_FILTER_EMBOSS`: 画像にエンボス処理を行います。
  - `IMG_FILTER_GAUSSIAN_BLUR`: ガウス分布を 使用して画像をぼかします。
  - `IMG_FILTER_SELECTIVE_BLUR`: 画像をぼかします。
  - `IMG_FILTER_MEAN_REMOVAL`: 平均を除去し、 「スケッチ風の」効果を得ます。
  - `IMG_FILTER_SMOOTH`: 画像を滑らかにします。 滑らかさのレベルを `args` で指定します。
  - `IMG_FILTER_PIXELATE`: モザイク効果を画像に適用します。 `args` でブロックの大きさを、 そして `arg2` でモザイク効果のモードを指定します。
  - `IMG_FILTER_SCATTER`: Scatter 効果を 画像に適用します。`args` と `arg2` を効果の強さを定義するのに使い、 選んだピクセルの色にだけ適用するために 追加で `arg3` を使います。
`args`

  - `IMG_FILTER_BRIGHTNESS`: 輝度レベル。
  - `IMG_FILTER_CONTRAST`: コントラストレベル。
  - `IMG_FILTER_COLORIZE`: 赤コンポーネントの値。
  - `IMG_FILTER_SMOOTH`: 平滑度レベル。
  - `IMG_FILTER_PIXELATE`: ピクセル単位のブロックサイズ。
  - `IMG_FILTER_SCATTER`: 効果を減らすレベル。 この値は、 `arg2` で設定する追加レベル以上でなければなりません。
`arg2`

  - `IMG_FILTER_COLORIZE`: 緑コンポーネントの値。
  - `IMG_FILTER_PIXELATE`: 高度なモザイク効果を使用するか否か (デフォルトは `false`)。
  - `IMG_FILTER_SCATTER`: 効果の追加レベル
`arg3`

  - `IMG_FILTER_COLORIZE`: 青コンポーネントの値。
  - `IMG_FILTER_SCATTER`: オプション。 効果を適用するインデックスカラーの値の配列。
`arg4`

  - `IMG_FILTER_COLORIZE`: アルファチャネル。 0 から 127 までの値で、0 は完全な不透明、127 は完全な透明を表す。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

`IMG_FILTER_SCATTER` `filter` で `sub` または `plus` がオーバーフローやアンダーフローを引き起こす場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `IMG_FILTER_SCATTER` `filter` で `sub` または `plus` がオーバーフローやアンダーフローを引き起こす場合、 ValueError をスローするようになりました。
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。
7.4.0 | Scatter 効果のサポート (`IMG_FILTER_SCATTER`) が追加されました。

### 例

例1 imagefilter() グレースケールの例

    <?php
    $im = imagecreatefrompng('dave.png');

    if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
    {
        echo 'Image converted to grayscale.';

        imagepng($im, 'dave.png');
    }
    else
    {
        echo 'Conversion to grayscale failed.';
    }
    ?>

例2 imagefilter() 輝度の例

    <?php
    $im = imagecreatefrompng('sean.png');

    if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
    {
        echo 'Image brightness changed.';

        imagepng($im, 'sean.png');
    }
    else
    {
        echo 'Image brightness change failed.';
    }
    ?>

例3 imagefilter() 単色化の例

    <?php
    $im = imagecreatefrompng('philip.png');

    /* R, G, B, so 0, 255, 0 is green */
    if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
    {
        echo 'Image successfully shaded green.';

        imagepng($im, 'philip.png');
    }
    else
    {
        echo 'Green shading failed.';
    }
    ?>

例4 imagefilter() での打ち消しの例

    <?php
    // Define our negate function so its portable for
    // php versions without imagefilter()
    function negate($im)
    {
        if(function_exists('imagefilter'))
        {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for($x = 0; $x < imagesx($im); ++$x)
        {
            for($y = 0; $y < imagesy($im); ++$y)
            {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return(true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if($im && negate($im))
    {
        echo 'Image successfully converted to negative colors.';

        imagejpeg($im, 'kalle.jpg', 100);
    }
    else
    {
        echo 'Converting to negative colors failed.';
    }
    ?>

例5 imagefilter() でのモザイク処理の例

    <?php
    // Load the PHP logo, we need to create two instances
    // to show the differences
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Create the image instance we want to show the
    // differences on
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Apply pixelation to each instance, with a block
    // size of 3
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Merge the differences onto the output image
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Output the differences
    header('Content-Type: image/png');
    imagepng($output);
    ?>

上の例の出力は、 たとえば以下のようになります。

例6 imagefilter() でのScatter効果の例

    <?php
    // Load the image
    $logo = imagecreatefrompng('./php.png');

    // Apply a very soft scatter effect to the image
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Output the image with the scatter effect
    header('Content-Type: image/png');
    imagepng($logo);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 注意

> 注意: `IMG_FILTER_SCATTER` の適用結果は常にランダムです。

### 参考

- imageconvolution() - div および offset の係数を使用し、3x3 の畳み込み配列を適用する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open