---
title: "How to use metadata to substitute lo-res with hi-res images"
source: https://dev.pageseeder.com/get_started/tutorials/substitute_lo-res_with_hi-res_images.html
description: "How to use image metadata to substitute a lo-res image for a hi-res image when exporting to PDF or DocX"
last_updated: 2026-08-11T16:31:05+10:00
tokens: ~2143
---
# How to use metadata to substitute lo-res with hi-res images
| Property | Value |
| --- | --- |
| Skills required | XML |
| Time required (minutes) | 30 |
| Intended audience | Developer |
| Difficulty | Medium |
| Category | Document |
## Objective
This tutorial describes how image metadata can control which version of an image is used when PageSeeder outputs a document. For example, publishing a document to a website or mobile device might use the same resolution image as the editing process. However, when the same document is output for print, the images might be substituted with a higher resolution version.
## Prerequisites
This tutorial assumes:
- [Administrator](/reference/glossary/administrator.md) rights on a PageSeeder server.
- A **[project](/reference/glossary/project.md)** to host the customization and a **group** for the example document.
- A PSML document which has a low resolution image inserted.
- A high resolution version of the same image used in the PSML document.
All the files for this tutorial are on [GitHub](https://github.com/pageseeder/pageseeder-tutorials/tree/master/substitute_lo-res_with_hi-res_images).
## Tutorial
### Configure image metadata
Determine the image type to be used, and then configure the metadata using the [media template](/guide/configuration/media_types.md). In the project selected for this tutorial, in the admin menu for the project, go to the **Template configuration** page, **Media types** tab, then click plus **Create media type**. In this example, we use "png" as image type.
Use the interface to add support for `.png` images by either **create** or **edit** of the following two files:
**`media-template.psml`**
```xml
```
**`editor-config.json` **
```json
{
"PSMLMetadataConfig": {
"fields": {
"action" : {
"type": "checkbox",
"label": "Action",
"values": ["None", "Zoom", "Fullscreen"]
}
}
}
}
```
> **Note:** The `caption` and `action` properties and the `editor-config.json` file are not required for the image substitution. This is simply a convenient opportunity to illustrate how to configure an object for multiple metadata properties.
### Edit image metadata
Ensure the following:
- Both the lo-res and hi-res versions of the image have been uploaded to a group in the correct project.
- The lo-res image has been referenced by document created using the correct template.
Then, **view **the lo-res image file and **edit** the Document info & metadata.
In the **Document info & metadata** panel, open the **Metadata** tab and select the property with the file-tree browse option. Navigate to the hi-res image file and select it. This creates a cross-reference to the hi-res image in the metadata of the lo-res image.
Follow these steps to complete the connection of the images:
1. Edit the hi-res link.
2. Select a 'Link Type' of '**Alternate**'.
3. Select 'Save'.
4. Select 'Save'.
### Configure the 'Exporting with Substitution' function
Follow these steps to log on to the Publish server:
1. Select '**Toolbox**' located under the **Dev** tab in the **Developer perspective**,
2. Select 'Project files',
3. Use an account with Administrator privileges.
Once logged on to the Publish server, create the following location for the configuration file under '`Template`':
```
[project]/document/psml/export
```
From the material downloaded from GitHub (see **Prerequisites** above), upload the following files to the `export` folder:
```text
build.xml
```
```text
alternate-images.xsl
```
```text
numbering-config.xml
```
```text
validate-psml.sch
```
```text
word-export-config.xml
```
```text
word-export-template.docx
```
```text
ant-schematron-2010-04-14.jar
```
`alternate-images.xsl` – is the code that actually substitutes the images, see the following:
```xml
```
`build.xml` – has been modified so the following elements have been added to `` This initiates the XSLT and embeds the metadata:
```xml
```
### Prepare publish config file for PDF and DOCX format
Through the user interface, in the admin menu for the project, select **Template files** and **create **the following folder:
```text
[project]/publish
```
then **upload** the following file that should have been retrieved from Github in Step 3.
```text
publish-config.xml
```
### Test
To ensure that process is functioning as expected:
1. Select the rocket Export icon for the document that contains the lo-res image.
2. Select the option labelled 'Create PDF with Image Replacement*'.*
3. Click the 'Run' button.
After completion, the PDF document features a hi-resolution image in place of the low-resolution image.
## Validation
When substituting with hi-res images it might be useful to validate your images to ensure that all have hi-res alternatives defined. This can be done using schematron as follows:
1. In PageSeeder, select the **Documents** page for the group containing your images.
2. Select the **Template configuration **page.
3. Click **create** under **Schematron** next to the `PNG` media type.
4. Copy and paste the following Schematron code and click **Save**.
5. Select the **Documents page** for the group containing your images again.
6. Click the file-validate **Validate** button at the top right of the page.
7. Select `.png` and click **Validate** (any `PNG` images without a hi-res alternative should be listed in the validation report).
```xml
Rules for images
Document
No hi-res alternative defined.
```
> **Note:** This process can be repeated for other image types (e.g. `.jpg`, `.gif`).