autocrop

Perfect for profile picture processing for your website or batch work for ID cards, autocrop will output images centered around the biggest face detected.

Installation

Simple!

pip install autocrop

Use

Autocrop can be used from the command line or directly from Python API.

From the command line

usage: autocrop [-h] [-V] [-v] [-n] [-o OUTPUT] [-w WIDTH] [-H HEIGHT]
                [--facePercent FACEPERCENT]
                [source]

Automatically crops faces from pictures

positional arguments:
  source                Image file, or '-' to read image bytes from stdin.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -v, --verbose         Write timings and basic processing details to stderr
  -n, --no-resize       Do not resize images to the specified width and
                        height, but instead use the original image's pixels.
  -o, --output, -p, --path OUTPUT
                        Output file, or output directory for a single input
                        image. If omitted, cropped image bytes are written to
                        stdout.
  -w, --width WIDTH     Width of cropped files in px. Default=500
  -H, --height HEIGHT   Height of cropped files in px. Default=500
  --facePercent FACEPERCENT
                        Percentage of face to image height

From Python

Import the Cropper class, set some parameters (optional), and start cropping.

The crop method accepts filepaths or OpenCV-style BGR/BGRA np.ndarray inputs, and returns RGB/RGBA Numpy arrays. These are easily handled with PIL or Matplotlib.

from PIL import Image
from autocrop import Cropper

cropper = Cropper()

# Get a Numpy array of the cropped image
cropped_array = cropper.crop('portrait.png')

# Save the cropped image with PIL if a face was detected:
if cropped_array is not None:
    cropped_image = Image.fromarray(cropped_array)
    cropped_image.save('cropped.png')

Autocrop v2 uses OpenCV's YuNet neural-network face detector.

Further examples and use cases are found in the accompanying Jupyter Notebook.

Examples

• Crop one image and write the cropped image bytes to stdout:
  • autocrop portrait.jpg > cropped.jpg
• Crop image bytes from stdin. This uses - instead of -- because -- is already argparse's standard option terminator:
  • cat portrait.jpg | autocrop - > cropped.jpg
  • autocrop -- > cropped.jpg < portrait.jpg
• Crop one image and write to an explicit output file:
  • autocrop portrait.jpg -o cropped.jpg
• Print timings and basic processing details to stderr:
  • autocrop portrait.jpg --verbose > cropped.jpg
• Crop one image and write into an explicit output directory:
  • autocrop portrait.jpg -o crop
• Convert output format by choosing an explicit output extension:
  • autocrop portrait.jpg -o cropped.png
• Crop one image but keep the original crop pixels instead of resizing:
  • autocrop portrait.jpg --no-resize > cropped.jpg

Autocrop intentionally processes one image per invocation. For recursive or filtered batch workflows, compose autocrop with shell tools.

With find:

mkdir -p crop
find pics -type f \( -iname '*.jpg' -o -iname '*.png' \) -print0 |
  while IFS= read -r -d '' file; do
    out="crop/${file#pics/}"
    mkdir -p "$(dirname "$out")"
    autocrop "$file" > "$out"
  done

Convert outputs to JPEG while batching:

mkdir -p crop
find pics -type f \( -iname '*.jpg' -o -iname '*.png' \) -print0 |
  while IFS= read -r -d '' file; do
    out="crop/${file#pics/}"
    mkdir -p "$(dirname "$out")"
    autocrop "$file" -o "${out%.*}.jpg"
  done

With fd:

fd -e jpg -e png . pics -x sh -c 'out="crop/${1#pics/}"; mkdir -p "$(dirname "$out")"; autocrop "$1" -o "${out%.*}.jpg"' sh {}

With xargs:

find pics -type f \( -iname '*.jpg' -o -iname '*.png' \) -print0 |
  xargs -0 -I{} sh -c 'out="crop/${1#pics/}"; mkdir -p "$(dirname "$out")"; autocrop "$1" > "$out"' sh {}

With GNU parallel:

find pics -type f \( -iname '*.jpg' -o -iname '*.png' \) -print0 |
  parallel -0 'out="crop/{= s:^pics/:: =}"; mkdir -p "$(dirname "$out")"; autocrop {} > "$out"'

Detecting faces from video files

You can use autocrop to detect faces in frames extracted from a video. A great way to perform the frame extraction step is with ffmpeg:

mkdir frames faces

# Extract one frame per second
ffmpeg -i input.mp4 -filter:v fps=fps=1/60 frames/ffmpeg_%0d.bmp

# Crop faces as jpg
find frames -type f -name '*.bmp' -print0 |
  while IFS= read -r -d '' file; do
    autocrop "$file" -o "faces/$(basename "${file%.*}").jpg"
  done

Supported file types

The following input file types are supported:

• EPS files (.eps)
• GIF files (.gif) (only the first frame of an animated GIF is used)
• JPEG 2000 files (.j2k, .j2p, .jp2, .jpx)
• JPEG files (.jpeg, .jpg, .jpe)
• LabEye IM files (.im)
• macOS ICNS files (.icns)
• Microsoft Paint bitmap files (.msp)
• PCX files (.pcx)
• Portable Network Graphics (.png)
• Portable Pixmap files (.pbm, .pgm, .ppm)
• SGI files (.sgi)
• SPIDER files (.spi)
• TGA files (.tga)
• TIFF files (.tif, .tiff)
• WebP (.webp)
• Windows bitmap files (.bmp, .dib)
• Windows ICO files (.ico)
• X bitmap files (.xbm)

Explicit output files are limited to writable formats with these extensions: .apng, .bmp, .dib, .eps, .gif, .icns, .ico, .j2c, .j2k, .jpe, .jpeg, .jpg, .jp2, .jpc, .jpf, .jpx, .pbm, .pcx, .pdf, .pgm, .png, .pnm, .ppm, .ps, .rgb, .rgba, .sgi, .tga, .tif, .tiff, and .webp.

Misc

Installing directly

In some cases, you may wish the package directly, instead of through PyPI:

cd ~
git clone https://github.com/leblancfg/autocrop
cd autocrop
uv sync

Development environment

Best practice for your projects is of course to use virtual environments. For local development, autocrop uses uv:

uv sync
uv run autocrop --help

Autocrop is currently being tested on:

• Python 3.10 to 3.14
• OS:
  • Linux
  • macOS
  • Windows

More Info

Check out:

• https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet

Adapted (ages ago now!) from:

• http://photo.stackexchange.com/questions/60411/how-can-i-batch-crop-based-on-face-location

Bundled detector models

Autocrop vendors OpenCV Zoo's face_detection_yunet_2023mar.onnx so YuNet works offline and CI does not depend on runtime downloads. The model source is opencv/opencv_zoo, and OpenCV's model card notes that files in the models/face_detection_yunet directory are MIT licensed.

Contributing

Although autocrop is essentially a CLI wrapper around a single OpenCV function, it is actively developed. It has active users throughout the world.

If you would like to contribute, please consult the contribution docs.