focuspoint for TYPO3: Intelligent Image Cropping

focuspoint prevents images from losing important parts of the subject when cropped responsively; the extension sets a focus point around which the crop stays oriented at every aspect ratio

Anyone using images on a responsive website knows the problem: a portrait photo that is shown in a teaser only 200 pixels tall suddenly shows only the neck or the forehead. A landscape photo displayed as a narrow strip in the hero area shows the sky instead of the mountains. Blanket centring leads to main subjects being cut off because the mathematical centre rarely coincides with the actual subject centre. focuspoint solves this by letting editors set a point on the image in the backend that must remain visible on every crop. The output adapts to all aspect ratios without having to generate a separate image variant for every format.

The difference to a classic image pipeline with fixed crops is large. Instead of maintaining separately cropped versions for desktop, tablet and mobile, there is one original image with a focus point and an arbitrary number of output formats that the system computes automatically. For editorial teams with many images, this dramatically reduces maintenance time, and for marketing it opens the possibility of introducing new aspect ratios without rework.

Typical use cases

The first classic case are people and team pages. A corporate website shows staff portraits in different layouts, as a round avatar in the header, as a square tile in the team list, as a wide format on the detail page. Without a focus point, the photographer has to shoot exactly centred, or the editorial team creates a separate variant for every layout. With focuspoint, the editor sets a point on the face once and the image works in all contexts.

The second case are product and room photos. Estate agents, hoteliers and furniture retailers work with photos where the actual subject, a sofa, a view of a room, a product detail, is not in the middle of the image. focuspoint makes it possible to pick exactly that subject and ensures that it is not lost on mobile devices either.

Third use: magazine and article teasers. Editorial article images often have a clear focal point, for example a speaker on a stage or a product in a scene. In teaser lists with portrait thumbnails, this focal point would often be outside the visible area without a focus point.

Technical architecture

focuspoint adds two metadata fields to the TYPO3 FAL system: focus_point_x and focus_point_y. Both are maintained in the backend through a form element that displays the original image as a selection area. The editor clicks on the relevant point, and the relative position is stored. Technically, these are two floating point values between zero and one describing the share of image width and height.

When rendering in the frontend, the focus point is evaluated by the Fluid ViewHelper. Instead of the usual “f:image” ViewHelper, the extension uses its own ViewHelper that performs the crop calculation taking the focus point into account and generates the image at the desired target size through the TYPO3 GIFBUILDER pipeline. The result is cached and only regenerated on changes.

The extension plays well with all common image formats (JPEG, PNG, WebP, AVIF) and uses ImageMagick or GraphicsMagick for the actual image processing, the same stack TYPO3 already builds on. For lazy loading and srcset integration there are no conflicts: the ViewHelper can be nested inside picture elements with multiple sources and delivers the right crop for every breakpoint.

Common problems and solutions

The first problem is the order of ViewHelpers. Anyone adding focuspoint to existing templates that already work with “f:image” and manual crop arguments has to replace the standard with the focuspoint ViewHelper rather than wrap around it. Otherwise both logics run against each other and the result ignores the focus point. The solution is a clean migration of all image references in the sitepackage to the new ViewHelper.

Second problem: cache invalidation. When editors change the focus point, the image cache has to be discarded, otherwise they still see the old crop. TYPO3 usually clears the image cache on changes to the original image, not on metadata changes. The solution is an event listener that specifically deletes the affected processed files on changes to the focus point fields.

Third problem: inconsistent results between backend preview and frontend. The preview in the backend uses a different render path than the frontend, which can lead to small deviations. Pragmatic solution: show only a rough preview in the backend and point editors at the frontend as the authoritative reference.

Migration and version compatibility

Since version 9, TYPO3 ships a native crop editor in the backend that allows individual variants per image. For simple cases, that is enough. focuspoint differs in that the focus point is set once and automatically feeds into all crop variants, instead of editing every variant individually. Anyone with many images and little editorial time is better off with focuspoint in the long run.

The extension is compatible with TYPO3 v11, v12 and v13. On upgrades from older versions, the FAL metadata structure and the ViewHelpers in use should be brought to the current syntax.

A new class of alternatives are AI-based saliency detections that derive the focus point automatically from the image content. These approaches further reduce editorial work, because editors no longer have to set the point themselves and only correct in exceptional cases. For TYPO3 there are first integrations of this technique, but they are not yet standard and should be evaluated per project.

Gosign configures focuspoint and integrates it into Fluid template architectures. AI-supported analysis of the design layouts proposes optimal crop presets for all breakpoints, so that editors do not have to try every format individually when maintaining images.