leblancfg/autocrop

autocrop – Quick Overview

What it does

• A tiny Python tool that finds the biggest face in an image and crops the picture around it.
• Works from the command line or via a small Python API.
• Uses OpenCV’s YuNet neural‑network face detector, so the detection runs locally – no cloud service needed.

Why it matters

• Automates a common, tedious step for profile pictures, ID‑card photos, or any workflow that needs a centered face thumbnail.
• Handles many image formats (PNG, JPEG, WebP, GIF, TIFF, etc.) and can output a variety of common formats.

How to get it

pip install autocrop   # pulls the latest 2.x release

Requires Python 3.10+, OpenCV 4.8+, and Pillow 12.3+.

Basic usage

• CLI – One‑liner cropping:

  autocrop portrait.jpg -o cropped.jpg          # crop & resize to 500 × 500 px
  autocrop portrait.jpg --no-resize > out.png   # keep original pixel size
  autocrop - > out.jpg < portrait.jpg            # read from stdin, write to stdout
  

• Python – Small API:

  from autocrop import Cropper
  from PIL import Image
  
  cropper = Cropper()                     # align=False by default
  result = cropper.crop('portrait.png')   # accepts file path or OpenCV BGR array
  
  if result.image is not None:
      Image.fromarray(result.image).save('cropped.png')
  print(result.diagnostics)  # shows which face was chosen, crop rectangle, etc.
  

  The API returns a CropResult containing the cropped image (as an RGB/RGBA NumPy array) and a CropDiagnostics dataclass with details.

Key options

Option	What it changes
-w/--width -H/--height	Output size (default 500 × 500 px).
--no-resize	Skip the final resize; keep the original crop dimensions.
--align	Rotate the face to be level using eye landmarks (off by default).
--json PATH	Write a JSON file with the crop diagnostics.
-v/--verbose	Print timing and processing info to stderr.

Batch processing
The tool processes a single image per call, which makes it easy to combine with standard shell utilities (find, xargs, parallel, fd, etc.) for large collections or video‑frame workflows.

Behind the scenes

• Autocrop bundles the face_detection_yunet_2023mar.onnx model from OpenCV Zoo, so detection works offline.
• The detector is a lightweight neural network that runs fast on CPU; no GPU is required.

Project health

• CI runs on Linux, macOS, and Windows across Python 3.10‑3.15.
• Recent major version 2.0 (Oct 2026) introduced a breaking API change; migration notes are provided.
• Actively maintained with contribution guidelines and a public issue tracker.

Typical use cases

• Generating uniform profile‑picture thumbnails for web apps.
• Preparing ID‑card photos in bulk.
• Extracting face crops from video frames for downstream ML pipelines.

---

autocrop is a focused, production‑ready utility for face‑centric image cropping, sitting squarely in the AI‑enabled image‑processing space.