leblancfg/autocrop

autocrop – 快速概览

功能

• 一个微型 Python 工具，可查找图像中最大的面部并围绕其裁剪图像。
• 可通过命令行或小型 Python API 使用。
• 使用 OpenCV 的 YuNet 神经网络面部检测器，因此检测在本地运行，无需云服务。

重要性

• 自动执行个人资料图片、身份证照片或任何需要居中面部缩略图的工作流程中常见且繁琐的步骤。
• 支持多种图像格式（PNG、JPEG、WebP、GIF、TIFF 等），并可输出多种常见格式。

获取方式

pip install autocrop   # 获取最新的 2.x 版本

需要 Python 3.10+、OpenCV 4.8+ 和 Pillow 12.3+。

基本用法

• 命令行 – 单行裁剪：

  autocrop portrait.jpg -o cropped.jpg          # 裁剪并调整为 500×500 像素
  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×500 像素）。
--no-resize	跳过最终大小调整，保持原始裁剪尺寸。
--align	使用眼睛关键点将面部旋转至水平（默认为关闭）。
--json PATH	将裁剪诊断信息写入 JSON 文件。
-v/--verbose	将处理时间和信息打印到 stderr。

批处理
该工具每次调用处理单个图像，因此可以轻松与标准 shell 工具（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 应用生成统一的个人资料图片缩略图。
• 批量准备身份证照片。
• 从视频帧中提取面部裁剪，用于下游机器学习流水线。

---

autocrop 是一个专注于面部中心图像裁剪的、面向生产环境的实用工具，位于 AI 赋能图像处理领域的核心位置。