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).
Note
Superseded by LMS Image Enhancer
Status
- Beta quality, little error handling
- Tested on Linux, may or may not work on other platforms if the required dependencies are installed
Installation
photosquare is written in Python and has the following dependencies:
Since these are fairly common packages, they should be available from the OS package manager.
Then,
- download the script itself (and run
chmod 755 photosquare-*.py
) - download the pre-trained dlib CNN face detection model and uncompress it
- download smartcrop.py and place it into the same directory as
photosquare-x.y.z.py
Usage
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.
Command
The general format is photosquare.py [options] sourcepath destinationpath
. This will write square versions of all images in sourcepath
to destinationpath
.
Note
All images in sourcepath
are processed, so make sure there are no images with identical names.
Run ./photosquare.py --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 smartcrop.py
- uses the Intersection over Union algorithm implemented by Martin Thoma
License
GNU GPLv3