Command Line

Croppola.com exposes a simple web interface, that can be accessed from the command line using tools like curl, lwp, or wget. The following examples use curl, which is available on all mayor operating systems.

The service is available free of charge for a volume of up to 100 photos per day, 500 photos per month, or 2400 photos per year. Above that, please request an API key.

Smart cropping in one step

In the simplest case, you submit a photo to Croppola.com, and specify the desired aspect ratio and crop size. The server will reply with the cropped image:

curl -X POST --data-binary @yourimage.jpg \
	'https://croppola.com/croppola/image.jpg?aspectRatio=1.5&width=90%&algorithm=croppola&apiKey=YOURAPIKEY' \
	> cropped-image.jpg

This submits yourimage.jpg to croppola.com, and stores the cropped photo as cropped-image.jpg. Note the '' around the URL, which will prevent the shell from interpreting the & character in the URL.

The same, but for a PNG image:

curl -X POST --data-binary @yourimage.png \
	'https://croppola.com/croppola/image.png?aspectRatio=1.5&width=90%&algorithm=croppola&apiKey=YOURAPIKEY' \
	> cropped-image.png

Crop size

The width and height of the desired crop can be provided in the following ways:

width and height
aspectRatio and width
aspectRatio and height
aspectRatio, maximumWidth, and maximumHeight (largest fitting rectangle)
aspectRatio, minimumWidth, and minimumHeight (smallest fitting rectangle)

aspectRatio can be given as a number (e.g. aspectRatio=1.32), or a ratio (e.g. aspectRatio=16:9).

All other parameters are measured in image pixels (e.g. width=340) or as percentage of the original image dimensions (e.g. maximumWidth=80%).

If the desired crop dimensions are bigger than the image itself, the crop width and height are scaled to keep the same aspect ratio (if an aspect ratio is provided), or reduced to the image width and height (if width and height are provided).

Composition algorithms

Croppola provides the following composition algorithms to determine the position of the crop rectangle within the image:

croppola: Positions the crop rectangle in the most interesting area of the image.
center: Positions the crop rectangle in the center of the image.

Alternatively, the x and y coordinates can be specified manually, such as in the following example:

curl -X POST --data-binary @yourimage.jpg \
	'https://croppola.com/croppola/image.jpg?aspectRatio=2:1&width=340&x=287&y=55&apiKey=YOURAPIKEY' \
	> cropped-image.jpg

Creating thumbnails

Croppola can be used to create smart thumbnails with the same aspect ratio and size. To use that, add the scaledMaximumWidth (or scaledWidth) parameter with the desired thumbnail width in pixels. The following will create square thumbnails of size 200x200 pixels, showing the most interesting part of the image:

curl -X POST --data-binary @yourimage.jpg \
	'https://croppola.com/croppola/image.jpg?aspectRatio=1.0&minimumHeight=80%&scaledMaximumWidth=200&algorithm=croppola&apiKey=YOURAPIKEY' \
	> yourimage-thumbnail.jpg

Obtaining crop coordinates

Instead of cropping the image, croppola.com can send the coordinates where it would have cropped the image in either JSON or TSV format:

curl -X POST --data-binary @yourimage.jpg \
	'https://croppola.com/croppola/image.json?aspectRatio=1.5&width=90%&algorithm=croppola&apiKey=YOURAPIKEY'

The resulting JSON data looks like this:

{
  "token": "9a4acbd7b8ad2ce6daf2",  // Image token (for future requests)
  "algorithm": "croppola",
  "imageWidth": 1024,               // Source image size
  "imageHeight": 768,
  "x": 3.413333,                    // High-res crop rectangle
  "y": 150.186667,
  "width": 921.600000,
  "height": 614.400000,
  "cropX": 3,                       // Final crop rectangle
  "cropY": 150,
  "cropWidth": 922,
  "cropHeight": 614,
  "scaledWidth": 600,               // Size of (scaled) final image
  "scaledHeight": 400,
  "faces": [
    {"x": 587.4, "y": 270.3, "width": 742.1, "height": 740.6}
    ],
  "dominantColors": [
    {"r": 8, "g": 3, "b": 4, "importance": 0.268},
    {"r": 155, "g": 124, "b": 106, "importance": 0.732}
    ],
  "version": 2
}

The most important information here are the crop coordinates cropX, cropY, cropWidth and cropHeight.

Besides that, the server assigns and submits a token for the image. This token can be used to refer to the image without uploading it again, and allows you to download several crop (or crop coordinates) without uploading the same image again:

curl 'https://croppola.com/croppola/9a4acbd7b8ad2ce6daf2/image.json?aspectRatio=1.5&width=90%&algorithm=croppola&apiKey=YOURAPIKEY' > crop1.jpg
curl 'https://croppola.com/croppola/9a4acbd7b8ad2ce6daf2/image.json?aspectRatio=1.0&width=80%&algorithm=croppola&apiKey=YOURAPIKEY' > crop2.jpg

The server keeps images for approximately 1 h (after the last request using it), and deletes them afterwards. If the image does not exist any more, the server will reply with HTTP status 404 Not Found.

Dominant colors

Croppola automatically carries out a color analysis and provides the dominant colors in the reply. Each color consists of four values:

R, G, and B, as numbers ranging from 0 to 255
relative importance of that color, ratio from 0 to 1

The relative importance values sum up to 1. Colors may appear in any order.

Faces

As part of the composition process, croppola looks for faces on the image, and reports their coordinates. Faces may appear in any order.

Face rectangles include eyes, nose, and mouth, but usually do not include hair and neck. To crop heads, you have to scale the rectangles to about 1.5 to 2.0 times the width and height. To get a square crop of a head, you could use the following formula:

head.width = face.height * 1.5;    // try values from 1.5 to 2.0
head.height = head.width;
head.x = face.x + (face.width - head.width) * 0.5;
head.y = face.y + (face.height - head.height) * 0.5;

and then call croppola with fixed coordinates (x, y, width, height) to crop the resulting head rectangle. Example:

curl -X POST --data-binary @yourimage.jpg \
	'https://croppola.com/croppola/image.jpg?x=220&y=96&width=340&height=340&apiKey=YOURAPIKEY' \
	> cropped-head.jpg