顔を中心にした正方形切り抜き領域の計算ツール | KIT
1200×900の写真で、位置400、250にある200×240の顔からは、x 320、y 190から始まる一辺360ピクセルの正方形が得られます。顔は中央にあり、各辺に顔の4分の1の余白が付きます。画像に触れる前に計画でき、ブラウザで無料で使えます。
- 無料
- ブラウザで動作
- 登録不要
- データは端末の外に出ません
無料で実行
計算例
- 幅
- 1,200
- 高さ
- 900
- 顔の X
- 400
- 顔の Y
- 250
- 顔の幅
- 200
- 顔の高さ
- 240
- X
- 320
- Y
- 190
- 辺
- 360
- 右辺
- 680
顔の中央切り抜き推定ツールは、顔検出の結果をそのまま使える正方形の切り抜き領域に変換します。ピクセルのアップロードやデコード、変換は一切行いません。純粋で決定論的な幾何計算であり、実際の切り抜きの前に実行する計画ステップです。
切り抜きの前に領域を推定する理由
顔を考慮した切り抜きは、プロフィール写真、アバター生成、人物ディレクトリのサムネイル、フォトライブラリのスマートプレビューなど、あらゆる場面で使われています。
これらに共通するのは、コストがかかるのは画像のデコードと再エンコードであり、厄介なのは後になって顔が端で切れていたり、正方形が中央からずれていたり、円形マスクに対してマージンが狭すぎたりと、フレーミングの失敗に気づくことです。この機能は、安価な判断と高価な実行を分離します。
顔検出器をすでに実行してバウンディングボックスを持っているなら、画像をそのまま画像パイプラインに流して結果を期待するのではなく、まず正確な切り抜き領域を問い合わせます。対話的にプロトタイプを作成し、後で結果を再確認することなく自動化できます。
領域の計算方法
アルゴリズムは意図的にシンプルで、完全に決定論的です。まず顔のバウンディングボックスの中心を求めます。正方形の辺は顔の幅と高さの大きい方から始まり、1にマージンの2倍を加えた係数で拡大されます。
つまりデフォルトのマージン0.25では、顔サイズの4分の1が各辺に追加され、顔の最長辺の1.5倍の正方形になります。これは顔写真に適した余裕のあるフレーミングです。その正方形が画像自体より大きい場合は、画像の最短辺に合わせて縮小されます。
その後、正方形は顔の中心に配置され、端からはみ出す場合は画像内に押し戻されます。変形はせず、常にクランプされるため、返される領域は常に画像内に収まる有効な切り抜きになります。画像の外にある顔ボックスは検出器のバグであり、それを知らせることが重要だからです。
パイプラインでの位置づけ
典型的な流れは、お好みの顔検出器を実行し、最適なバウンディングボックスを取得し、この推定ツールを呼び出してから、返された領域をimage.crop機能や独自のサムネイルワーカーなどの実際の切り抜きツールに渡すというものです。推定ツールは画像のバイトデータに一切触れないため、メタデータだけで使用することもできます。
例えば、何かをダウンロードする前に、境界付近で検出された顔が使える正方形を生成するか、別のレイアウトにフォールバックすべきかを判断できます。マージンパラメータが唯一の調整つまみです。0は顔の最長辺ぴったりのタイトな正方形、0.25はデフォルトの顔写真フレーミング、0.5以上は髪や肩のための余白を残します。
活用例
アップロードから正方形のアバターを生成
検出器から顔ボックスを取得し、円形マスクにも耐えるマージン付きで、切り抜きワーカーに渡す正確な正方形を得られます。
サムネイルパイプラインの事前検証
画像のデコードと再エンコードのコストを支払う前に、メタデータだけで顔ボックスを検証し、切り抜き領域を計算できます。
自動切り抜きの監査
推定された領域を各アセットと一緒に保存すれば、フレーミングの悪いアバターを、それを生成した正確な座標まで遡って追跡できます。
よくある質問
料金はいくらですか?
また、このページのブラウザ上では無料で実行でき、結果はまったく同じです。
画像をアップロードする必要がありますか?
いいえ。 送信されるのは画像の寸法と顔のバウンディングボックス、つまり6つの数値だけです。ピクセルデータの送信、処理、保存は一切行われません。
顔ボックスが画像からはみ出している場合はどうなりますか?
画像の外にある顔ボックスはほぼ必ず検出または座標マッピングのバグであり、黙って切り抜かれるのではなく報告されます。
正方形が端を超えてしまう場合は?
サイズを保ったまま画像内に押し戻されます。画像自体より大きい場合は画像の最短辺に縮小されます。返される領域は常に完全に画像内に収まります。
マージンは何をするものですか?
顔の最長辺に対する割合で、顔の周りに余白を追加します。デフォルトの0.25では顔の最長辺の1.5倍の正方形になり、0はタイトな切り抜き、0.5は余裕のあるスペースを残します。
結果は決定論的ですか?
はい。 純粋な算術演算なので、同じ入力には同じ座標が返ります。
関連ツール
開発者向け — APIアクセス
このページの機能はすべてAPIからも利用できます。自社システムに組み込みたいチーム向けのセクションです。それ以外の方は上のツールをそのままお使いください。
エンドポイント
Bearerトークンで認証し、POST1回でタスクをキューに登録します。結果はWebhookまたは署名付きリンクで受け取れます。
お使いのスタックから呼び出す
curl -X POST https://api.kit.forhosting.com/image/crop-face-center-estimate \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"width":1200,"height":900,"face_x":400,"face_y":250,"face_width":200,"face_height":240}'const res = await fetch("https://api.kit.forhosting.com/image/crop-face-center-estimate", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"width": 1200,
"height": 900,
"face_x": 400,
"face_y": 250,
"face_width": 200,
"face_height": 240
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/image/crop-face-center-estimate",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"width": 1200,
"height": 900,
"face_x": 400,
"face_y": 250,
"face_width": 200,
"face_height": 240
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/image/crop-face-center-estimate", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"width":1200,"height":900,"face_x":400,"face_y":250,"face_width":200,"face_height":240}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"width":1200,"height":900,"face_x":400,"face_y":250,"face_width":200,"face_height":240}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/image/crop-face-center-estimate", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)リクエスト例
{
"width": 1200,
"height": 900,
"face_x": 400,
"face_y": 250,
"face_width": 200,
"face_height": 240
}レスポンス例
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "image.crop_face_center_estimate",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}非同期APIです。task_idは即時に返ります。ポーリングは1秒あたり1リクエストまでです。
料金
単価はすべて公開しています。トークン換算や独自クレジットはありません。失敗したタスクは課金されません。
制限
max_mb | 15 |
max_megapixels | 12 |
エラー
| HTTP | コード | 意味 |
|---|---|---|
401 | unauthorized | APIキーが無効か、指定されていません。Authorizationヘッダーを確認してください。 |
402 | insufficient_balance | 残高が不足しています。チャージ後に再度お試しください。 |
404 | unknown_type | 指定されたタスクタイプは存在しません。タイプ名を確認してください。 |
429 | rate_limited | リクエストが多すぎます。しばらく待ってから再度お試しください。 |
技術的な注記
画像の寸法と検出された顔のバウンディングボックス(left、top、width、height)、および任意のマージンを送信すると、顔を中央に保ち、画像内に完全に収まる正方形のx、y、辺の長さが返されます。このページのブラウザ上では無料で実行でき、APIでは1回$0.002でご利用いただけます。
切り抜きの前に領域を推定する理由
答えはx、y、辺の長さを含むシンプルなJSONオブジェクトで、ImageMagickからcanvas要素まであらゆる切り抜きツールに渡せますし、判断を監査可能にするためアセットと一緒に保存することもできます。計算は6つの数値に対する純粋な算術演算なので、コストはほぼゼロ、応答はマイクロ秒単位で、ブラウザでもAPIでも完全に同じ動作をします。
領域の計算方法
顔ボックス自体も厳密に検証され、負の原点、0以下のサイズ、画像の端を超えるボックスは、壊れた切り抜きを黙って返すのではなくinvalid_inputエラーを発生させます。
パイプラインでの位置づけ
すべては何も保存しないグローバルエッジ上で実行され、このページの無料計算ツールと同じモジュールが動いているため、ブラウザで表示される数値は、呼び出しを自動化したときにAPIが返す数値とバイト単位で完全一致します。