Image Processing
Revela automatically processes your images into optimized web formats. This page covers configuration, incremental updates, and cleanup.
Image Configuration
Configure image formats and quality in project.json, or with revela config image:
{
"generate": {
"images": {
"avif": 75,
"webp": 85,
"jpg": 90
}
}
}
Supported formats:
jpg- Universal compatibility (quality 1-100)webp- Smaller files, modern browsers (quality 1-100)avif- Smallest files, newest browsers (quality 1-100)
Set a format to 0 (or leave it out) to disable it. The project wizard enables all three with the values above, and they are a good default: browsers pick the smallest format they support, and JPG remains the fallback. If builds take too long, see Encoding Speed before disabling AVIF, which is the slowest to encode.
revela config image --formats avif:75,webp:85,jpg:90
Image Sizes
Sizes are defined by your theme in its Configuration/images.json. The default Lumina theme generates these widths:
160, 320, 480, 640, 720, 960, 1280, 1440, 1920, 2560
These sizes are optimized for High-DPI displays (1.5x, 2x scaling).
Each photo gets every theme size that is smaller than the photo, plus its original width for the full-resolution view. A 2000-pixel-wide photo, for example, gets 160 to 1920 and 2000. To limit that largest image, see maxSize.
To use different sizes, see Themes.
Color Spaces
Most photos are published in sRGB, the color space browsers assume for web images. Photos exported with another embedded profile (Display P3, Adobe RGB, CMYK) are converted using that profile, so colors look the same as in your editor on standard displays. Your source files are never changed.
Wide Gamut (Display P3)
Many screens show more saturated colors than sRGB can describe: iPhones, iPads and Macs, flagship Android phones and wide-gamut monitors. When a photo actually contains such colors — a sunset, flowers or neon exported in Display P3 or Adobe RGB — Revela publishes it in Display P3 with the color profile embedded (about 480 bytes per file):
- Wide-gamut screens show the full colors.
- Standard screens convert the profile and show the photo like an sRGB version, without a color cast.
- Every other photo is published exactly as before: untagged sRGB, byte for byte.
This works for AVIF, WebP and JPG alike, and themes need no changes. Revela decides per photo during the scan, from a small preview: a photo counts as wide-gamut when a visible part of it (at least 0.1 % of the preview, differing by more than ΔE 3 from the nearest sRGB color) lies outside sRGB. A Display P3 or Adobe RGB profile alone is not enough — most photos with such a profile fit inside sRGB and stay sRGB. Adobe RGB and ProPhoto photos with wider colors are converted to Display P3; colors beyond P3 are mapped into it.
To publish every photo in sRGB, switch it off:
{
"generate": {
"images": {
"wideGamut": false
}
}
}
Switching it off or on re-encodes only the wide-gamut photos.
Social networks and messengers often drop color profiles from link previews, which would make
a P3 photo look dull. Each wide-gamut photo therefore also gets one untagged sRGB JPEG
(<size>.srgb.jpg, the largest size up to 1920 px), and Lumina uses it for og:image.
HDR photos (JPEG with gain map) are published as their standard dynamic range image.
Exporting From Your Photo Editor
Revela re-encodes every photo for the web, so export source files, not web-ready files. A good export preset (Capture One process recipe, Lightroom export preset, …):
| Setting | Recommendation | Why |
|---|---|---|
| Format | JPEG, quality 95–100 | Revela reads JPG, PNG, WebP and GIF (not TIFF or HEIC). 16-bit or PNG gains nothing: web images are 8-bit. |
| Color profile | Display P3, otherwise Adobe RGB (1998), embedded | Exporting in sRGB clips saturated colors for good, so wide-gamut screens can never show them. Avoid ProPhoto RGB in 8-bit JPEG (banding in smooth gradients), monitor profiles and camera profiles. |
| Size | Full resolution, or at least 4000 px on the long edge | Revela makes the theme sizes plus the original for the 100 % zoom; maxSize caps it later without a new export. |
| Metadata | Keep EXIF and title/description/keywords, leave out GPS | Revela reads capture time, camera, title (used as alt text), description, keywords and rating. Published images never contain EXIF or GPS, but your source files might be shared. |
| Output sharpening | Off or light | Most of it is lost when Revela scales the photo down. |
| File names | Keep them stable | Photo page URLs are derived from them. |
No Display P3 in the profile list? Windows ships no Display P3 profile, so Windows editors such as Capture One may not offer it. Either use Adobe RGB (1998), which works just as well (Revela converts wide-gamut photos to Display P3), or install a free Display P3 profile: download DisplayP3Compat-v2-magic.icc from Compact ICC Profiles (public domain), right-click it → Install Profile, and restart the editor. A direct P3 export lets you soft-proof exactly what wide-gamut screens will show.
Re-exporting a library in a wide color space is worth it mainly for saturated motifs: in one 1,197-photo portfolio exported in Adobe RGB, about 20 % of the photos contained colors outside sRGB, and in the most colorful ones up to a third of the image looked visibly different on an iPad.
Detail View Zoom
Canonical photo pages and Lightbox images can be zoomed:
- Mouse or pen: click to zoom to 100 % (one image pixel per screen pixel, also on high-density screens), drag to move around, click again to zoom out.
- Touch: double-tap to zoom to 100 % or back, pinch with two fingers, and move with one finger while zoomed. A pinch past 100 % or below the fitted size springs back when you let go.
Zoom stops at 100 % because beyond it a photo only shows enlarged pixels. Photos that already fit
the screen at 100 % or less are not zoomable and show no zoom cursor. With
maxSize, the largest image is the capped one, so zooming
shows no more detail than that.
The page first loads a photo that fits the screen and fetches the original only when someone zooms; until it has arrived the current photo is shown enlarged, so it never goes blank. Zoom resets when a Lightbox closes or switches images.
A Lightbox fills the whole screen and closes with its × button or the Escape key; clicking around the photo does not close it.
On a photo page and in a Lightbox, the ← and → arrow keys go to the previous and next photo (also while zoomed). They do nothing while you type in a form field or hold a modifier key, so browser shortcuts such as Alt+← (back) keep working. Without JavaScript the ‹ and › links do the same.
Mouse-wheel zoom and swipe-to-close are intentionally not enabled, so vertical scrolling to photo metadata remains predictable.
Generating Images
# Full generation
revela generate images
# Force regenerate all (ignore cache)
revela generate images --force
Incremental Processing
Revela automatically detects what's missing and only generates those variants.
An image is regenerated completely when its source file changes (size or
modification time), when the theme's resize mode changes, or when a Revela
update changes how images are encoded. Revela remembers what each photo's
variants were made from in .revela/core/images.json, separately from the scan
data, so a rescan, revela clean cache or a Revela update that only changes the
scan data never re-encodes your photos. That record belongs to the output:
revela clean output deletes it together with the image files, so the next build
encodes every photo again.
If your site is built on a server, keep the project's .revela/ folder between
builds (it is not part of the published site): with .revela/ and the existing
output in place, a new build only encodes new or changed photos.
Large libraries can take a while, especially the first time or after such an update. If a run is interrupted (Ctrl+C, a closed terminal or a restart), just start it again: Revela saves its progress as it goes and continues with the photos that weren't finished yet.
Adding a New Format
# Before: only jpg configured
# After: add webp to project.json
revela generate images
# → Only webp files are created
# → Existing jpg files are kept
Changing Quality
When you change a format's quality (for example AVIF from 80 to 70), the next build re-encodes only that format for all photos. The other formats are kept, and you don't need --force. Changing avifEffort or webpEffort works the same way, changing maxSize re-encodes only the photos larger than the old or the new limit (see Encoding Speed), and changing wideGamut re-encodes only the wide-gamut photos (see Wide Gamut).
Progress Display
While images are encoded, Revela shows one progress bar for all photos and a status line below it:
Encoding photos ████████████░░░░░░░░ 512/1197 (43%) · 18m elapsed · ~24m left
⠋ 16 workers busy · avif 512 · webp 998 · jpg 1120 · 132 img/min · 3 skipped
The status line shows how many photos are finished per format, the processing rate, and how many photos were skipped because they were already up to date.
Encoding Speed
Almost all of the build time goes into encoding, and AVIF takes most of it, especially the full-resolution image. Revela's defaults are chosen for fast AVIF; three optional settings let you trade build time against file size or zoom detail.
Setting (generate.images) |
Default | Effect |
|---|---|---|
avifEffort |
2 |
AVIF encoder effort, 0 (fastest) to 9 (smallest files) |
webpEffort |
4 |
WebP encoder effort, 0 to 6 |
maxSize |
0 (off) |
Largest image in pixels, measured like the theme sizes (the longest edge in Lumina) |
maxDegreeOfParallelism |
automatic | Photos encoded at the same time |
Why AVIF 75 at Effort 2
The suggested AVIF quality is 75 and the default AVIF effort is 2. In a side-by-side of four very detailed photos, AVIF 75 at effort 2 looked the same as the previous AVIF 80 at effort 4 and encoded about 7× faster.
- Quality 75 instead of 80: at 80, AVIF files were larger than WebP 85, which loses the point of AVIF. At 75 they are about as large as WebP 85 on typical photos (33 random photos, 2560 px) and about 18 % smaller on the very detailed test photos, while measuring closer to the original than WebP 85.
- Effort 2 instead of 4: the encoder spends far less time searching for the smallest file. A full build with AVIF, WebP and JPG took about 3.8× less time (33 photos: 101 s → 27 s). Files range from about 2 % smaller (very detailed photos) to about 15 % larger (typical photos) than with effort 4 at the same quality.
If file size matters more than build time, set a higher effort:
{
"generate": {
"images": {
"avif": 75,
"avifEffort": 4
}
}
}
avifEffort: 4 also keeps AVIF files that an earlier Revela encoded with effort 4. webpEffort
works the same way for WebP; WebP is far less of the build time, so it matters less. Changing an
effort re-encodes only that format's files, like a quality change.
Limit the Largest Image (maxSize)
{
"generate": {
"images": {
"maxSize": 3840
}
}
}
Every photo normally also gets its full resolution, so the photo viewer can zoom to 100 %. With
maxSize, photos larger than the limit get an image of that size instead; smaller photos keep
their full resolution. 3840 (4K) needs about 20–35 % less time per photo (more for larger
photos), and the files of the largest image shrink accordingly, but zooming shows no more detail
than 3840 pixels.
Changing maxSize re-encodes the photos larger than the old or the new limit. The
full-resolution files they had before are no longer used; revela clean images removes them.
Parallel Encoding
Revela encodes several photos at the same time. Without AVIF it encodes about one photo per CPU core, each with one or two threads, because the JPEG and WebP encoders use a single thread. With AVIF it encodes half as many photos as there are cores with up to 8 threads each, which suits the AVIF encoder best.
Each photo being encoded needs up to about 700 MB of memory (a full-resolution AVIF of a
30-megapixel photo), so Revela encodes at most one photo per GB of memory. To use less memory,
set maxDegreeOfParallelism to a smaller number, for example 1 to encode one photo at a time.
Changing it never re-encodes photos.
Cleaning Up
When you change your image configuration (remove a format, change sizes), old files remain. Use clean images to remove them:
# Preview what would be deleted
revela clean images --dry-run
# Actually delete unused files
revela clean images
What Gets Cleaned
| Category | Description | Example |
|---|---|---|
| Orphaned folders | Source image was deleted | output/images/galleries/vacation/deleted-photo/ |
| Unused sizes | Width no longer in theme config | output/images/<gallery>/<photo>/480.jpg when 480 removed |
| Unused formats | Format disabled in project | output/images/<gallery>/<photo>/*.webp when webp removed |
Scan first.
clean imagescompares the output with the manifest.revela generate all(orrevela generate scan) brings the manifest up to date, so run it before cleaning.
Typical Workflow
# 1. Change config (remove webp)
# Edit project.json: remove "webp": 85
# 2. Preview cleanup
revela clean images --dry-run
# → Shows: 4220 webp files (852 MB)
# 3. Delete unused files
revela clean images
# → Deleted: 4220 files (852 MB)
# 4. Verify (optional)
revela generate images
# → Shows: 0 processed, 1153 cached
Photo Placeholders
While a photo loads, Lumina shows a single color: the photo's average color, dimmed towards the page background. Layouts don't shift, there are no extra requests, and nothing needs configuring.
How It Works
- During scan, Revela averages a small preview of each image (the full-size photo is not decoded) in the perceptual Oklab color space and stores it as
#rrggbbin the manifest - Templates write it as a CSS custom property, e.g.
style="--image-color:#5a6b7c" - The theme paints it behind the image; the loaded photo covers it completely
A plain color is deliberately simple: the earlier gradient placeholders made scrolling large galleries stutter, especially on iPad. Themes read the color as image.color (see the template reference); Lumina mixes 70% of it into the page background, adjustable with --image-color-strength in its CSS.
Upgrading from a version with gradient placeholders re-reads the image metadata once on the next scan. Image variants are not re-encoded.
Best Practices
🚀 Keep the Defaults
AVIF 75, WebP 85 and JPG 90 give small files with a safe fallback. If encoding still takes too long, set maxSize before you disable AVIF.
🔄 Incremental Updates
Don't use --force unless necessary. Incremental processing is much faster, and quality changes are picked up automatically.
🧹 Clean After Config Changes
After removing formats or sizes, run clean images to free disk space.
📊 Check Dry-Run First
Always use --dry-run before clean images to preview what will be deleted.
Troubleshooting
If images are missing or generate images fails, run revela check first. It reports problems such as a missing source folder, an output folder Revela can't write to, a missing theme or invalid settings, each with a suggested fix.