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:

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:
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:

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:

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
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:

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.