Advanced Image with Focal Point in Sitecore 10.1

In this blog, I am sharing details on an approach used for Image cropping based on focal points. Even though, there are lots of blogs talking about how to use it, but none of them shared the technical details about how it actually works, what is the idea behind building the functionality and what each configuration, code or item in Sitecore does. So I decided to share these details with the community.

The Problem 

In Sitecore, content authors are responsible for creating, managing, and publishing digital content across websites and digital platforms. They are also responsible for managing the images in Sitecore media library. Managing image resolutions for different devices involves creating and serving images that look sharp and load efficiently across various screen sizes and resolutions requires images to be uploaded in different resolutions cropped such that the focal point is always in center. 

Content authors wanted the ability to upload a single image in an agreed up (lets say 16x9) aspect ratio in the highest quality recommendation and then be able to select a focal point that would then crop the image to a size and aspect ratio that maintains the focal point as the center of the cropped image. 

The Research

We are aware about lot of options which can provide similar ability. Some of these are listed below -

1. jQuery Focuspoint
2. Cropping Images by CSS
3. Advanced Image Sitecore by Saad and later updated by Amit
4. Advanced Image by Kate
5. Image Focal Point by Anindita

Option 1 & 2 provide ability to crop images based on focal point on client-side only. Problem with this even when images are being cropped, the image is still being sent in high resolution with large size to browsers. This can lead to low core web vital score.

Option 3 & 4 are very similar and seem to be inspired from a common source. They are good options but had few challenges - 

• The Sitecore module referred in these articles was not present in Sitecore Marketplace anymore. Fortunately, Kate Orlova has added the package of Sitecore items to her git repo which saves you from misery.
• They shared steps on how to get modules to work but do not share how the functionality actually work behind the scenes. As such, you will keep reading the code and hitting debug points to understand the module.

Option 5 only lets you select focal point on an image and then store it in Image item's description field. It leaves the question open ended on how to actually crop the images

To us, option 3 or option 4 made more sense as we wanted to crop images on server to avoid sending big images to client side. 

The Solution

Cropping images based on focal point can be considered as a 2 part problem - 

1. Finding a focal point in an image item
2. Cropping image by keeping focal point at the center

Both of these are discussed with code snippets in following sections.

Finding a focal point in an image item

This is achievable by integrating focus-point module in Sitecore client (Read more about this module here). The module js/css are included in below files in the project -

Next, we need to create a new custom field called as AdvancedImage (based on Image field) which will have logic to integrate focus-point module into it. This is done in below item in Core DB -

Content authors also need to have a way of configuring different resolutions in Sitecore so that the AdvancedImage field can use these resolutions to show a preview of the image. This will help content authors to choose the focal point for an image efficiently while previewing it in different resolutions. This is done in below item in Master DB -

The AdvancedImage field shall have a logic to introduce some custom html into the field. This custom html will be responsible for providing a preview of the cropped images with focal point. The project has template.html file for this purpose -

The above HTML is rendered in Sitecore using AdvancedImage.cs DoRender() method as in snapshot below-

Once the focal point is selected for an image item, the focal point coordinates shall be stored into image xml so that they can be referenced when the image is added to a page. If you check the raw value of AdvancedImage field after selecting a focal point, it shall look like this- 

The cropX and cropY values in AdvancedImage field's raw value need to be copied to image request's query parameters. This is done in HTMLExtensions.cs file as in snapshot below. These values are latest used by CropMediaRequest.cs to copy them from query parameters to Media Custom Options and finally by Crop Processor for croppping logic - 

 

Cropping image by keeping focal point at the center

• This can be done by using a library like ImageProcessor or ImageSharp. Developer needs to provide the height, width and (x,y) points for focal points to the library. The library can then resize the image by keeping the focal point at the center and return the cropped image. This is done in CropProcessor.cs file -

Next, we need to know when and where we can hook this processor in Sitecore. An ideal candidate for it is <getMediaStream> pipeline which is responsible for creating an output stream of media item being requested. Logic to resize image with focal point can be hooked into this pipeline logics easily. This is managed in below config -

There should be a way to store the height, width, x, y values in Sitecore and then pass them to the getMediaStream pipeline. This is done by adding custom request parameters to MediaOptions which contains options for media items (this is done in above config).

• These custom options to MediaOptions can be added when the media request is received by Sitecore. 

Hope it helped you guys! Thanks for reading!