Revela

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:

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):

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:

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.

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 images compares the output with the manifest. revela generate all (or revela 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

  1. 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 #rrggbb in the manifest
  2. Templates write it as a CSS custom property, e.g. style="--image-color:#5a6b7c"
  3. 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.