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에 출력.

일괄 처리
이 도구는 호출당 단일 이미지를 처리하므로 대규모 컬렉션이나 비디오 프레임 워크플로에서 표준 셸 유틸리티(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 변경이 도입되었으며 마이그레이션 노트가 제공됩니다.
기여 가이드라인과 공개 이슈 트래커로 활발히 유지 관리됩니다.

대표적인 사용 사례

웹 앱용 균일한 프로필 사진 썸네일 생성.
ID 카드 사진 대량 준비.
다운스트림 ML 파이프라인을 위해 비디오 프레임에서 얼굴 자르기 추출.

autocrop은 AI 기반 이미지 처리 공간의 중심에 있는 얼굴 중심 이미지 자르기를 위한 집중적이고 프로덕션 준비가 된 유틸리티입니다.

leblancfg/autocrop

autocrop – 빠른 개요

관련