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:

{
  "generate": {
    "images": {
      "jpg": 90,
      "webp": 85
    }
  }
}

Supported formats:

• jpg - Universal compatibility (quality 1-100)
• webp - Smaller files, modern browsers (quality 1-100)
• avif - Smallest files, newest browsers (quality 1-100)

Recommendation: Start with just jpg: 90 for compatibility. Add webp or avif later if needed.

Image Sizes

Sizes are defined by your theme. 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).

Plus the original width for full-resolution lightbox view.

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:

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

Progress Display

image001.jpg  ■ ■ ■ ■ □ □ □ □ □ □ □ □
image002.jpg  ■ ■ ■ □ □ □ □ □ □ □ □ □
image003.jpg  ■ ■ □ □ □ □ □ □ □ □ □ □

• Green ■ = Generated (new file)
• Gray ■ = Skipped (already exists)
• Empty □ = Pending

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

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

Low-Quality Image Placeholders (LQIP)

Revela generates CSS-only placeholders that display while images load. This creates a smooth loading experience without layout shifts.

How It Works

1. During scan, Revela analyzes each image's average color and brightness pattern
2. This data is encoded into a compact integer (e.g., -721311)
3. The theme's CSS decodes this integer into gradient placeholders
4. When the image loads, it smoothly replaces the placeholder

Result: ~7 bytes per image instead of a separate LQIP file. No additional HTTP requests.

Configuration

LQIP is enabled by default. To disable it:

{
  "generate": {
    "images": {
      "placeholder": {
        "strategy": "none"
      }
    }
  }
}

Technical Details

The CSS hash encodes:

• Average color in Oklab color space (8 bits)
• 3×2 brightness grid as grayscale values (12 bits)

The browser reconstructs this as radial gradients with blend modes, creating a blurred approximation of the image. Based on Lean Rada's CSS-only LQIP technique.

Best Practices