Focus Point

Set the important part of an image once; MediaHub uses it when framing auto-generated crops and when you open the crop editor.

A focus point tells MediaHub which part of an image matters most. Once you move the marker away from its default centre position, auto-generated crops frame around that point rather than the geometric centre of the image, keeping your subject in frame regardless of crop ratio.

Focus point scenarios

You can set or adjust the focus point from three places:

#	Where you are	What you click	What opens	What it does
1	Asset detail page	Focus Point (Actions panel)	Editor with focus pre-activated	Sets the focal area on the master image
2	MediaHub field → master image card	Focus Point (drawer)	Editor with focus pre-activated	Sets the focal area on the master image
3	Editor (any create-mode session)	Focus Point toggle in toolbar	Activates focus dot overlay	Sets focus before choosing a crop preset; crop frames centre on focus

Focus point behaviour

Focus point is a property of the master image, not of individual crops.
Saving the focus point is immediate: it persists via AJAX the moment you click "Save focus point". No need to also click a crop save button.
After saving, a green toast confirms "Focus point updated" inside the editor. The Close button lets you exit safely.
The focus point toggle is not available in adjust mode (scenarios where you're repositioning an existing crop). This prevents accidental changes to the master image's focus when the intent is only to resize or reposition a crop.
When cropping with a focus point set, new crop frames auto-centre on the focus area.

How focus point affects crops

Auto-generated crops

When MediaHub generates a crop, through ensureCropImage() in a template, upload automation, or the admin lazy-generation pass when a field renders, it reads the stored focus point and positions the crop window around your subject. If you have not moved the marker from centre, crops use a centred frame as before.

Inline crop badges

Inline crop badges on MediaHub field cards are generated using the focus point when the page editor renders. If you reposition the focus point after badges have already been generated, re-saving the page regenerates any lazily-created crops around the new position.

Manually positioned crops

Auto-generation never overwrites a crop that an editor has manually positioned. To apply a new focus point to an existing manual crop, open the relevant badge or library crop, reposition the selection, and save again.

Choosing a preset in the crop editor also positions the initial crop boundary around your focus point when one has been moved from centre.

Important: changes apply everywhere

The focus point is stored on the source image using ProcessWire's native Pageimage::focus() API. Because MediaHub assets are centralised (one file, referenced from any number of pages) changing the focus point changes it for every page that uses that image across the entire site.

This is by design. If you need different framing on different pages, use manual crop positioning rather than the focus point.

Field setting

The Focus button can be enabled or disabled per MediaHub field:

Setup → Fields → [your field] → Input → Media Hub Picker Settings → Focus point selection

Option	Behaviour
Enabled (default)	Focus button visible on Detail-mode cards and in the edit drawer
Disabled	Focus button hidden for this field, useful for icons, logos, or decorative graphics

SVG assets

Focus point is not available on SVG (vector) assets. SVG files scale to any size without losing detail, so there is no framing decision to make at output time. The Focus button is hidden on SVG cards and on the SVG asset detail page.

Focus point continues to work on raster images (JPG, PNG, GIF, WebP) as usual. See Configuration → SVG Support for opt-in SVG uploads.

Developer reference

Focus point coordinates are available in template code via:

$asset->pkd_mediahub_focus

This returns a JSON object with top and left as percentages (e.g. {"top": 33.5, "left": 60.2}). When no focus point has been set, the values default to centre (50, 50).

The ensureCropImage() method respects the focus point automatically: auto-generated crops are centred on the focus area when one is set. See Crops API for full usage.

Menu