Import Page Images
A per-field import button that scans other image fields on the same page and intelligently matches against the MediaHub library, with deduplication, perceptual hashing, and confidence badges.
Beta feature. Import page images is available today but still maturing. Test on a staging copy and verify matches before large migrations. See Limitations & planned improvements for context.
Since MediaHub v1. Per-field import has been part of MediaHub since launch, not only in recent releases. Version 1.19.25 refreshed the modal UI, added Repeater/Matrix scanning, and hardened scan/import for large pages. The matching logic below is unchanged in spirit: multi-signal comparison with a dHash perceptual hash so confirmed duplicates become Hub references instead of new files.
What it does
When Import from page images is enabled on a MediaHub field, an Import page images button appears next to the Choose button in the page editor.
This feature is designed for gradual rollouts when you're adding MediaHub fields to templates that already have standard image fields. Rather than hunting through the library picker to find images that are already visible on the page, one click opens a modal that scans the other image fields on that specific page.
The payoff is duplicate-aware migration: images already in the Hub (even under a different filename) can be matched and referenced; only genuinely new files are copied in. That is what makes page-by-page migration practical on large sites.
The button only appears when the page has other image fields that contain images. There's no dead UI on pages where there's nothing to import.
Enabling it
- Open the MediaHub field in Setup → Fields
- Go to the Input tab → Media Hub Picker Settings
- Enable Import from page images
- Save
Repeater and RepeaterMatrix fields (1.19.25)
The scan now walks image fields inside Repeater and RepeaterMatrix items, up to three levels deep. Images from each path are grouped under a breadcrumb heading in the modal (for example Gallery → Slides → Images). The import endpoint uses each image's physical source page id so files inside repeater item pages resolve correctly.
On pages where images exist only inside repeaters (no top-level image fields), the Import page images button still appears when the feature is enabled.
Large pages and shared hosting (1.19.25)
Scan and import endpoints use extended time and memory limits and return JSON errors instead of HTML on failure. Import is capped at 200 selections per request. On pages with many images or on modest hosting, import in smaller batches. The modal header reminds editors of this when relevant.
How matching works
When the import modal opens, each source image is compared against every asset in the Hub using four independent signals:
| Signal | Description |
|---|---|
| Filename stem | Baseline check: same filename without extension |
| File size | Exact byte count comparison |
| Dimensions | Width and height comparison |
| Perceptual hash (dHash) | A 64-bit visual fingerprint (see below) |
Perceptual hashing
The perceptual hash (dHash) is computed by resizing the image to 9×8 pixels, converting to grayscale, and comparing adjacent pixel brightness to produce a 64-bit fingerprint.
Two images with a Hamming distance ≤ 5 are considered visually identical, even across different filenames, compression levels, or re-saves. This catches the common case where IMG_4523.jpg on a page is the same photo as office-team.jpg in the Hub.
The system uses ProcessWire's existing 64×64 thumbnails for dHash computation; no extra dependencies or large memory loads.
Confidence badges
Each image gets a confidence label based on how many signals agree (from 1.19.25 the copy is rationalised across badges, legend, and tooltips):
| Badge | Meaning | Basis |
|---|---|---|
| Exact match | Almost certainly the same image already in the Hub | Stem + filesize + dimensions, or stem + dHash match |
| Likely match | Very probably the same image | Stem + one secondary signal, or different filename but dHash ≤ 5 |
| Possible match | Same filename but different image | Stem matches; size, dimensions, and visual content all differ |
| New | Not found in the Hub | No stem match and no visual similarity |
| Already added | Already referenced | The Hub asset is already selected in this field |
What happens on import
When you select images and click Import:
- If the image is already in the Hub (confirmed by at least one secondary signal beyond filename): a reference to the existing asset is added to the field; no duplicate file is created.
- If the image is new (or confidence is too low): the image is copied into the Hub as a new asset.
During import, some built-in metadata is carried over:
- The original image's description becomes the asset's alt text
- Any PW image tags are converted to Hub labels
- The source page and field are recorded in the asset's About field as an audit trail
Custom fields on the source image are not imported. If your legacy image fields use per-file custom fields, those values stay on the original files and are not copied to the MediaHub asset. See Limitations & planned improvements.
Use case: gradual migration
This feature shines when you're incrementally migrating a site from native ProcessWire image fields to MediaHub:
- Add MediaHub fields to your templates alongside existing image fields
- When editing a page, use "Import page images" to pull in the existing images
- The matching logic avoids duplicates: images already in the Hub are referenced, not re-uploaded
- Once migrated, remove the old image fields from the template
This approach is gentler than a bulk migration because it lets editors verify each page as they go, rather than flipping the entire site at once.
Last updated