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.findFocalPointsByUrltakes all of a block's addresses and makes one query (catalogueId+urlin a set of candidates, only items with a focal point), on a new{catalogueId, url}index.MediaUrlKeysworks 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-positionis right for all of them. - The carousel and hero send the address as stored, unresized, today. Resizing them (a
srcsetper 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
Mediaalready 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.setFocalPointIfAbsentwrites only wherefocalPointis 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
focalPointTexton save, so a page opened while the analysis was pending would have saved a blank and wiped the suggestion. The status poll returnsfocalPointand 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.