Pixaven Blog

New Aspect Ratio Mode for Fast and Easy Image Cropping

Introducing FaceMaze - Free Online Face Detection App

Our newly-introduced mode for image cropping allows you to specify the desired aspect ratio that will be used to crop your input images without the need of calculating and providing the exact crop dimensions. With this addition we are bringing the total count of crop modes to three - rect, face and ratio.

What is aspect ratio

Aspect ratio describes the proportional relationship of the width and the height of an image. That relationship is usually denoted by two numbers separated by a colon, for example 16:9 or by a float number, for example 0.75.

The most common aspect ratios used in photography are “4:3”, “3:2”, and “16:9”. It’s worth keeping in mind that aspect ratio (or aspect definition) does not describe the actual pixel size of the image (width and height) but only the relationship between those two image properties.

Aspect ratio cropping with Pixaven API

The top-level crop hash now accepts an additional crop mode value - "ratio". Once the mode in your request JSON is specified, the actual aspect ratio has to be passed a value of an additional ratio key. The Pixaven API supports both ratio notations - a string such as "16:9" or a float number like 0.75.

For example, to crop images using aspect ratio of 5:9:

{
    "crop": {
        "mode": "ratio",
        "ratio": "5:9"
    }
}

The same crop using a number notation would look like this:

{
    "crop": {
        "mode": "ratio",
        "ratio": 0.55
    }
}
Given the input image 750px × 300px
Crop the image using aspect ratio of "5:9"

By default, images are cropped from the center and you can excercise more control over aspect ratio cropping by providing an extra gravity parameter which takes one of the following values: top-left, top, top-right, right, bottom-right, bottom, bottom-left or left.

The aspect ratio of 1:1 will produce square image, which is a great choice for social media and grid layouts. Let’s combine that with crop gravity set for example to left:

{
    "crop": {
        "mode": "ratio",
        "ratio": "1:1",
        "gravity": "left"
    }
}

For the full reference, please check out updated API docs for aspect ratio cropping.

Here’s a quick example of how to use our newly-introduced aspect ratio cropping with our official Node integration:

const Pixaven = require("pixaven");

/**
* Instantiate `pix`
*/

const pix = new Pixaven("your-api-key");

/**
* Upload a file from disk with upload(string) method
* and crop the image using aspect ratio set to "5:9"
*/

pix
    .upload("/srv/storage/animation.gif")
    .crop({
        mode: "ratio",
        ratio: "5:9"
    })
    .toJSON((err, meta) => {
        if (err) {
            return console.log(err);
        }
    });

Should you have questions about the aspect ratio cropping or requests for other features do not hesitate to contact us anytime.

About the author

Przemek Matylla is the Founder and CEO of Pixaven currently living in Berlin. You can follow him on Twitter or connect with him on LinkedIn.