Focal point cropping: user guide

Why is focal point cropping important?

Focal point cropping allows you to deal with the “Art direction problem” which basically means that images are showed in a different way according with the long variety of devices screen size we have nowadays. The so called responsive web/images design. There are a couple of related articles written by Google developers, and Mozilla developers which explain it in more details. Focal point cropping then allows you to select and modify that point that you consider should be kept when the image is rendered on different screen sizes. That way you don’t lose the details that you want to show of your image, which improves the Art direction.

We offer a flexible solution to given either a focal point or one of the algorithms that we have to automatically detect the focal point, and certain parameters you can get different versions of the images cropped while keeping the focal point.

What parameters we use?

Take a look to figure below:

Diagram focal point cropping parameters figure woman
  • x: coordinate x of the focal point.
  • y: coordinate y of the focal point.
  • focus-detection-algorithm: the algorithm for auto-detecting the focal point, so far just: generic_features_01 is implemented.
  • total-width: the desired width of the cropped image.
  • total-height: the desired width of the cropped image.
  • inner-left: distance to the left from the focal point to the square where the image is cropped.
  • inner-right: distance to the right from the focal point to the square where the image is cropped.
  • inner-top: distance to the top from the focal point to the square where the image is cropped.
  • inner-bottom: distance to the bottom from the focal point to the square where the image is cropped.
  • outer-left: distance from the image’s border to the square where the image is cropped from the left.
  • outer-right: distance from the image’s border to the square where the image is cropped from the right.
  • outer-top: distance from the image’s border to the square where the image is cropped from the top.
  • outer-bottom: distance from the image’s border to the square where the image is cropped from the bottom.
  • distance-to-focus: distance from the original image border (before cropping) to the focus. It is something that we automatically calculate.

As you can see above just either the focal point coordinates or the focus-detection-algorithm is required, so specifying any other combination of the parameters will always give you a cropped image that keeps the focal point. We have a more detailed explanation here about the parameters and how we use them. We will explain below how to use it through our API, and the results you can get.

You can use the SDK to do request to our API. Let’s show examples about how you can use the focal point cropping to transform your images.

Focal point cropping basic example

We will show you how you can send a request to the API that does what we explained here:

focal_point_cropping_basic.js 

import { LUX_API, Toilmore } from '@shimmercat/toilmore-sdk';
import fs from "fs";
import { Readable } from "stream";

let toilmore = new Toilmore(
    {
        'api_config': LUX_API,
        'api_token': 'xxxx-xxxx',   // <-- Use a valid API token here.
        'domain': 'shimmercat.com'
    });

let adjustments = {
    "shifter": {
        "steps": [
            {
                "focal-point-crop": {
                    "focal-point": {
                        "x": "400px",
                        "y": "400px"
                    },
                    "total-width": "800px"
               }
            }
        ]
    }
}

let force_processing = false;

let result_promise =  toilmore.optimize_with_precursor(
    "woman.png",
    "webp0",
    force_processing,
    adjustments
);

result_promise.then((result) => {
        // `result` can contain a short status string or null if the image
        // could not be optimized.
        store_optimized_image(result);
    },
    (err) => {
        console.log('Optimized images is not ready yet. Waiting 10 seconds...');
        // Let's wait a bit
        setTimeout(() => {
            store_optimized_image(result);
        }, 10);
    }
);

function store_optimized_image(result) {
    let w = fs.createWriteStream("./woman__w800.webp");
    result.pipe(w);
}

Let’s suppose you want to run the script above with this image:

Diagram focal point cropping figure woman

You should put the woman.png image above and the focal_point_cropping_basic.js on the same directory, install the SDK as we explain SDK, and then run:


node focal_point_cropping_basic.js

Once you get the optimized image you will get the woman__w800.webp version of this image like so:

Diagram focal point cropping figure woman webp format

We basically cropped the image, and optimized it to webp. You can see at our lux API doc, that you can get optimized images for any of the precursor_name: webp0, prjpg, pngzo, jp2o0, avifo0.

Focal point cropping all parameters included example

focal_point_cropping_all_params.js 

import { LUX_API, Toilmore } from '@shimmercat/toilmore-sdk';
import fs from "fs";
import { Readable } from "stream";

let toilmore = new Toilmore(
    {
        'api_config': LUX_API,
        'api_token': 'xxxx-xxxx',   // <-- Use a valid API token here.
        'domain': 'shimmercat.com'
    });


let adjustments = {
    "shifter": {
        "steps": [
            {
                "focal-point-crop": {
                    "focal-point": {
                        "x": "400px",
                        "y": "400px"
                    },
                    "crop-rims": {
                        "inner-left": "25% of distance-to-focus", // 100
                        "inner-right": "25% of distance-to-focus", // 100
                        "inner-top": "25% of distance-to-focus", // 100
                        "inner-bottom": "25% of distance-to-focus", // 100
                        "outer-left": "25% of total-width", // 200
                        "outer-right": "10% of total-width", // 100
                        "outer-top": "25% of total-height", // 250
                        "outer-bottom": "15% of total-height", // 150
                    },
                    "distance-to-focus": "400px",
                    "total-width": "800px",
                    "total-height": "1000"
               }
            }
        ]
    }
}

let force_processing = false;

let result_promise =  toilmore.optimize_with_precursor(
    "woman.png",
    "webp0",
    force_processing,
    adjustments
);

result_promise.then((result) => {
        // 'result' can contain a short status string or null if the image
        // could not be optimized.
        store_optimized_image(result);
    },
    (err) => {
        console.log('Optimized images is not ready yet. Waiting 10 seconds...');
        // Let's wait a bit
        setTimeout(() => {
            store_optimized_image(result);
        }, 10);
    }
);

function store_optimized_image(result) {
    let w = fs.createWriteStream("./woman__all.webp");
    result.pipe(w);
}

Let’s suppose you run this script with the same base image, then you will get a result like this:

Diagram focal point cropping figure woman all parameters included example

Using our API you can generate different optimized image versions of the same original image using the focal point cropping to get a better art direction.

Updated: