Skip to content

Image Focal Point

Decisions behind image focal points: the part of a picture to keep in view when a carousel or hero crops it to fit.

It came from a fashion demo: campaign photos of models (3:2) in a 1280x620 carousel lost the models' heads, because the slide was cropped object-fit: cover around the centre. Baking a top-weighted crop into the files was ruled out: the same photo is cropped differently on a phone, and the platform should handle it.

On the media item, found by address

The focal point is a property of the picture (Media.focalPoint, x/y percentages), not of each place it is shown: a face is in the same place whichever block shows the photo, so setting it once covers the carousel, the hero and any later use.

The blocks that crop (carousel, hero) store an image address, not a media id. Two ways to connect them were considered:

  • Give each slide and hero its own position setting, copied from the media item when the image is picked. Rejected as the default: the value is copied into every placement and drifts when the merchant corrects it on the image, and blocks written by MCP or the demo generator would never get it, because nothing picks the image there.
  • Look the media item up by address when rendering (chosen). MediaService.findFocalPointsByUrl takes all of a block's addresses and makes one query (catalogueId + url in a set of candidates, only items with a focal point), on a new {catalogueId, url} index. MediaUrlKeys works back from the forms an address takes: the stored key, the full address on the image host (https: or protocol-relative), a Thumbor-resized one (/fit-in/WxH/, URL-encoded key) and a demo site's own image path. The query runs only for slides without their own setting, so a block that sets every slide costs nothing.

Blocks still have an override (focalPoints on the carousel, focalPoint on the hero and each slideshow photo): for a picture from outside the library, and for one cropped differently in one place. It defaults to the media item's when blank.

Cropped in the browser, not by the image host

Stored media go through a Thumbor-style host, which can crop server-side around a focal region. Not used here:

  • The frames change shape with the screen: the carousel is about 2:1 on a desktop and nearer 1.25:1 on a phone, and the hero's height is a share of the window. One server crop is right for one shape; object-position is right for all of them.
  • The carousel and hero send the address as stored, unresized, today. Resizing them (a srcset per breakpoint, where a server crop could then use the focal point) is a separate change with its own cache and quality questions.
  • Demo images and outside addresses don't go through the image host at all.

object-position: x% y% puts the point x% across the picture at x% across the frame. That isn't "centre the point", but it always keeps the point in the frame, needs no knowledge of the picture's size, and is what CSS does natively.

Classes, not inline styles

Storefront templates may not add style="" (StorefrontStyleRatchetTest). The point is drawn by two classes on the picture, nova-focal-x-NN nova-focal-y-NN, in steps of 5% (42 one-line rules in Nova's bdgr.css, so every Nova-based theme has them), which set --focal-x / --focal-y; the crop rules read var(--focal-x, 50%) var(--focal-y, 50%). 5% of a tall photo is a few dozen pixels, finer than a merchant's click needs. The classes go on the element that draws the picture, not a wrapper, since custom properties inherit. FocalPoint#cssClasses produces them, so Java decides and the template only appends the string.

Blogs and the split hero

Blog mastheads and cards already load the post's masthead Media, so they take its focal point directly (no address lookup): BlogMastheadExtension puts imageFocal, and each BlogPost carries imageFocal. The cards draw through fragment/responsive-image, which kept its three-argument signature: a caller sets the local responsiveImageFocal (as it already does responsiveImagePriority), and .nova-responsive-image reads --focal-x/--focal-y in object-position, which only shows where a card's box crops the picture. Ridge's and Diorama's masthead rules read the same variables, from Nova's classes.

The split hero's photo is a jsonComponent image (an address), so it is found by address like the background photo. The split preset has no background photo, so the hero's own focalPoint overrides the photo's there rather than adding a setting.

Where it isn't used

  • Shoppable images are never cropped: their hotspots are positioned on the whole picture.
  • Product cards crop to the shop's image ratio, but product photos are usually centred packshots, and every theme has its own listing card template. Using it there is a later, per-theme change (the card's Media already carries the field).

Suggested by AI image tagging

The upload's tagging call (OpenAiImageAnalysisService) also asks for focalPoint, {x, y} or null, rather than a separate call or a face detector: the model already sees the picture, the extra field costs a few output tokens, and "the face of the main person, otherwise the main subject" is a judgement a vision model makes better than a face box (a back view, a product on a model). The picture is sent resized with fit-in, which keeps its shape, so percentages of it are percentages of the original.

  • Merchant wins. MediaRepository.setFocalPointIfAbsent writes only where focalPoint is null, like title and alt text are only filled when blank. A point set through MCP import before the worker gets to it stays.
  • Null for centred subjects. A centred packshot gets no point, so it still reads as "cropped around the centre" in the editor rather than as a choice someone made.
  • No "suggested" flag stored. The editor says a point came from AI only when the analysis finishes while it is open; after that a suggestion and a merchant's choice look the same. A flag would be worth adding if we ever re-run analysis over existing media, since then it decides what a re-run may replace.
  • The open editor takes it. The editor posts its hidden focalPointText on save, so a page opened while the analysis was pending would have saved a blank and wiped the suggestion. The status poll returns focalPoint and the picker adopts it (unless the merchant already clicked).

Admin

The picker is on the image's edit page, which already shows the picture large: the picture is a button, a click (or the arrow keys) sets the point, and a wide (2:1) and a tall (3:4) preview show the crops a merchant cares about. It posts focalPointText ("x y", blank for none), which the controller parses with FocalPoint.parse, the same parser MCP, block settings and the demo generator use.