leblancfg/autocrop

autocrop – クイック概要

機能

• 画像内で最も大きな顔を検出し、その周囲で画像を切り取る小さなPythonツール。
• コマンドラインまたは小さなPython APIから操作可能。
• OpenCVのYuNetニューラルネットワーク顔検出器を使用するため、検出はローカルで実行され、クラウドサービスは不要。

重要性

• プロフィール画像、IDカード写真、中央に顔がくるサムネイルが必要なワークフローなどで、よくある面倒なステップを自動化。
• 多くの画像形式（PNG、JPEG、WebP、GIF、TIFFなど）に対応し、さまざまな一般的な形式で出力可能。

入手方法

pip install autocrop   # 最新の2.xリリースを取得

Python 3.10以上、OpenCV 4.8以上、Pillow 12.3以上が必要です。

基本的な使い方

• CLI – ワンライナーで切り取り:

  autocrop portrait.jpg -o cropped.jpg          # 500×500pxにリサイズして切り取り
  autocrop portrait.jpg --no-resize > out.png   # 元のピクセルサイズを維持
  autocrop - > out.jpg < portrait.jpg            # 標準入力から読み込み、標準出力に書き出し
  

• Python – 小規模API:

  from autocrop import Cropper
  from PIL import Image
  
  cropper = Cropper()                     # デフォルトはalign=False
  result = cropper.crop('portrait.png')   # ファイルパスまたはOpenCV BGR配列を受け付ける
  
  if result.image is not None:
      Image.fromarray(result.image).save('cropped.png')
  print(result.diagnostics)  # 選択された顔や切り取り矩形などを表示
  

  このAPIは、切り取られた画像（RGB/RGBA NumPy配列）を含むCropResultと、詳細情報を含むCropDiagnosticsデータクラスを返します。

主なオプション

オプション	変更内容
-w/--width -H/--height	出力サイズ（デフォルト500×500px）。
--no-resize	最終リサイズをスキップし、元の切り取り寸法を維持。
--align	目のランドマークを使用して顔を水平に回転（デフォルトではオフ）。
--json PATH	切り取り診断情報をJSONファイルに書き出す。
-v/--verbose	処理時間や処理情報をstderrに出力。

バッチ処理
このツールは呼び出しごとに1枚の画像を処理するため、大量のコレクションやビデオフレームワークフローで、標準的なシェルユーティリティ（find、xargs、parallel、fdなど）と簡単に組み合わせることができます。

内部の仕組み

• autocropはOpenCV Zooのface_detection_yunet_2023mar.onnxモデルをバンドルしているため、検出はオフラインで動作。
• 検出器は軽量なニューラルネットワークで、CPU上で高速に動作し、GPUは不要。

プロジェクトの健全性

• CIはLinux、macOS、WindowsでPython 3.10～3.15に対して実行。
• 最近のメジャーバージョン2.0（2026年10月）で破壊的なAPI変更が導入され、移行ノートが提供されています。
• 貢献ガイドラインと公開イシュートラッカーがあり、積極的にメンテナンスされています。

典型的な使用例

• Webアプリ用の統一プロフィール画像サムネイルの生成。
• IDカード写真の一括作成。
• 下流のMLパイプライン用にビデオフレームから顔の切り取りを抽出。

---

autocropは、AI対応画像処理分野の中核に位置する、顔中心の画像切り取りに特化した実用的で本番対応のユーティリティです。