利用可能なモードを指定して、画像を自動的にクロップする

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — 利用可能なモードを指定して、画像を自動的にクロップする

### 説明

function imagecropauto(
GdImage `$image`,
int `$mode` = `IMG_CROP_DEFAULT`,
float `$threshold` = 0.5,
int `$color` = -1
): GdImage|false

指定した `mode` にしたがって、画像を自動的にクロップします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

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

  以下の定数のいずれか。

  `IMG_CROP_DEFAULT`
    `IMG_CROP_TRANSPARENT` と同じです。 PHP 7.4.0 より前のバージョンでは、 PHP にバンドルされた libgd は、 画像に透過色がない場合に `IMG_CROP_SIDES` にフォールバックしていました。
  `IMG_CROP_TRANSPARENT`
    透過色の背景をクロップします。
  `IMG_CROP_BLACK`
    黒の背景をクロップします。
  `IMG_CROP_WHITE`
    白の背景をクロップします。
  `IMG_CROP_SIDES`
    画像の四隅から、クロップする背景色を検出します。
  `IMG_CROP_THRESHOLD`
    `threshold` と `color` を用いてクロップします。
`threshold`

  画像の色とクロップする色を比較する際に用いる許容誤差を、パーセントで指定します。 色の違いを判断する際には、RGBキューブ内での距離を用います。

  `IMG_CROP_THRESHOLD` モードのときにだけ利用します。

  > 注意: PHP 7.4.0 より前のバージョンでは、 PHP にバンドルされていた libgd はやや異なるアルゴリズムを用いていました。 なので、同じ `threshold` を渡しても システムの libgd と PHP にバンドルされた libgd とは異なる結果が生成されていました。

`color`

  RGB値あるいはパレットインデックスを指定します。

  `IMG_CROP_THRESHOLD` モードのときにだけ利用します。

### 戻り値

成功した場合にクロップ後の画像オブジェクトを返します。 失敗した場合に `false` を返します 画像全体がクロップされてしまった場合にも `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
7.4.0 | PHP にバンドルされた imagecropauto() の振る舞いは、 システムにインストールされる libgd のそれと同じになりました。 つまり、`IMG_CROP_DEFAULT` が `IMG_CROP_SIDES` にフォールバックすることはなくなり、 しきい値によるクロップは、 システムにインストールされる libgd のアルゴリズムと同じものを使うようになりました。
7.4.0 | `mode` パラメータのデフォルト値が `IMG_CROP_AUTO` に変更されました。 これより前のバージョンでは、デフォルト値は `-1` で、`IMG_CROP_DEFAULT` に対応しています。 しかし、`-1` を渡すのは非推奨になりました。

### 例

例1 自動クロップの適切な処理

戻り値のところで説明したとおり、全部クロップしてしまったときに imagecropauto() が返す値は `false` となります。 この例では、クロップする部分がある場合にだけ画像オブジェクト `$im` を自動クロップします。 それ以外の場合は、元の画像をそのまま使います。

    <?php
    $cropped = imagecropauto($im, IMG_CROP_DEFAULT);
    if ($cropped !== false) { // 新しい画像オブジェクトが戻された場合にだけ
        $im = $cropped;       // クロップ後の画像を $im に代入します
    }
    ?>

### 参考

- imagecrop() - 指定した矩形に画像をクロップする

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