is a script to crop a portrait photo into an image with square dimensions. It was originally written to have artist photos nicely displayed in a grid. While a simple heuristic (top of a portrait, center of a landscape orientation) works well for many cases, band photos and unusual perspectives can lead to less than ideal results (missing band members, parts of faces cut off etc.)
This script uses face detection to find the crop area, and can handle cases where cropping isn't possible (by re-arranging the faces into a new image).


Superseded by LMS Image Enhancer


  • Beta quality, little error handling
  • Tested on Linux, may or may not work on other platforms if the required dependencies are installed


photosquare is written in Python and has the following dependencies:

  • Python 3
  • dlib with Python bindings
  • Pillow python module

Since these are fairly common packages, they should be available from the OS package manager.



Face detection modes

The script can use HOG (histogram of oriented gradients, fast, but less accurate), or CNN (convolutional neural network, slow but more accurate). It can also use both and merge the results (since there are cases in which each method detects faces the other doesn't). Generally, the detection rate is pretty high, but not perfect (e.g. low quality sources or partly visible faces may lead to problems).
If no face is detected, the script can

  • skip the image
  • use a simple heuristic (take the top area of a portrait or the center area of a landscape photo)
  • use "fairly dumb image processing" to determine the crop area
Faces grid

If cropping isn't possible without removing a face, the script can create a image grid of all faces instead.


The general format is [options] sourcepath destinationpath. This will write square versions of all images in sourcepath to destinationpath.


All images in sourcepath are processed, so make sure there are no images with identical names.

Run ./ --help for a list of all option.

Option Description
--log-level set log level: CRITICAL, ERROR, WARNING, INFO, DEBUG
--clobber overwrite existing destination files
--facedetect-mode mode of face detection: hog, cnn, both
--cnn-model path to the pre-trained cnn model (e.g. data/mmod_human_face_detector.dat)
--on-nofaces action if no face detected (skip, simple, smartcrop)
--on-failsquare action if square crop is impossible (skip, ignore, grid)
--grid-bgcolor background color of image grid (a color name like black or a RGB hex value like #ff99ff)
--skip-squareness how square the original image has to be to be skipped (decimal value 0.5-1.0, 1.0 means height=width)
--copy-square copy square source images to the destination directory
--demomode no cropping, visually highlight detected faces / crop area instead

Additional credits

  • uses
  • uses the Intersection over Union algorithm implemented by Martin Thoma