Quarto does not thumbnail images

[danmackinlay]

I notice that most of the discussion here was specifically about thumbnail size so I broke off a new discussion to discuss dynamic loading at #9434.

Description

I noticed that since switching my site to quarto, my bandwidth has gone up by orders of magnitude, and I am regularly threatened with being throttled by my provider (netlify) whereas before I would only hit 1 or 2 percent of my quota.

Checking the firefox web dev tools, I suspect I've found the culprit — it seems my front page is now 135MB:

I assume that this is because the listing on that front page, in order to provide dynamic listing search etc, loads essentially all the posts and their associated images at full resolution. Is there any way I can avoid this behaviour in the quarto website system as it stands? AFAICT quarto does not support image thumbnails, and also AFAICT the listing system is not built around lazy loading, but I would welcome being told I have simply failed to notice a setting. As it stands I suspect this is actually a feature request.

Related: #9330

[mcanouil]

You should set the image key to a small image rather than using the automatic preview image detection as documented in the listing page.

The issue you linked is unrelated to your case.
All CSS/JS is only few Mb and clearly does not account for your 100+Mb.

[mcanouil]

Regarding the "inject metadata", I did not test it in this particular case, so not entirely sure image key in listings "allows" this.

The trick below, uses the fact that Pandoc allows multiple YAML block in a document which are merged together.
Unfortunately, this does not work for all keys, as Quarto needs to know some of them before doing anything such as computations. For instance, you can't do that for format: html, as it's the first thing needed by Quarto.

```{r}
#| output: asis
cat("---", "key: value", "---", sep = "\n")
```

Even though I mentioned this technique, here I would go with something more straightforward.

I would have an images directory next to the Quarto document with the original image in it.
I would probably use a standard default name such as preview.ext.
The thumbnail would be next to the original image and named thumbnail.ext.

---
image: images/thumbnail.ext
---

```{r}
library(magick)
image <- image_read("images/preview.ext")  
image_info <- image_info(image)
max_width <- 200
aspect_ratio <- image_info$height / image_info$width
new_height <- as.integer(max_width * aspect_ratio)
downsampled_image <- image_resize(image, paste0(max_width, "x", new_height))
image_write(downsampled_image, "images/thumbnail.ext")
```

---

I am not sure if shortcodes are evaluated for the image key, if that's the case:

---
image: {{< meta params.image >}}
params:
  image: images/thumbnail.ext
---

```{r}
library(magick)
image <- image_read(params[["image"]])  
image_info <- image_info(image)
max_width <- 200
aspect_ratio <- image_info$height / image_info$width
new_height <- as.integer(max_width * aspect_ratio)
downsampled_image <- image_resize(image, paste0(max_width, "x", new_height))
image_write(downsampled_image, gsub("preview", "thumbnail", params[["image"]]))
```

[danmackinlay]

It seemed to me that writing a filter is kind-of the "correct" way to do this, since injecting an R script into all the files will be tedious over a thousand pages, so I wrote an extension in the hope that would be nicer: https://github.com/danmackinlay/quarto-thumbnail

This generates the thumbnails correctly, but I think I still need advice. I've set it up AFAICT correctly to inject the generated thumbnails into the image metadata, by setting it up like this:

function Meta(meta)
    if firstThumbnailPath then
        meta['image'] = firstThumbnailPath -- Update metadata with the first valid image's thumbnail path
    end
    return meta
end

return {
    { Image = Image, Figure = Figure }, -- Process Images and Figures
    { Meta = Meta }                     -- Update metadata last
}

However! the listing generated do not see the image key that the filter generates in the Meta; it's as if it parses the YAML directly rather than preprocessing it through the filters. I am not sure why, nor how I should debug the listings. Does anyone have tips? The deno listing stuff is dark magic to me

[danmackinlay]

OK, here is a hack that doesn't rely on pandoc fitlers behaving how I imagine: a python script that reads the built file from the _site folder and rewrites the header YAML. I am using it as a post-processing script. It hard-codes lots of things that are specific to my site (some figures are excluded from being preview images).

#! /usr/bin/env python
r"""
Update doc metadata by parsing HTML version for images.
"""

from pathlib import Path
from cairosvg import svg2png
from PIL import Image, ImageOps
import pillow_avif  # needed to register the AVIF format with Pillow

from ruamel.yaml import YAML
from bs4 import BeautifulSoup
from io import BytesIO
import sys
import os
# import time

THUMB_WIDTH = 300
THUMB_HEIGHT = 200

yaml = YAML(typ='rt')


def read(fname):
    metadata = {}
    outlines = []
    try:
        with open(fname, 'r', encoding='utf8') as fp:
            lines = fp.readlines()

        if len(lines) == 0:
            return {}, ""

        if lines[0] == ('---\n'):  # YAML header
            # Load the data we need to parse
            to_parse = []
            for i, line in enumerate(lines[1:]):
                # When we find a terminator (`---` or `...`), stop.
                if line in ('---\n', '...\n'):
                    # Do not include the terminator itself.
                    break

                # Otherwise, just keep adding the lines to the parseable.
                to_parse.append(line)

            parsed = yaml.load("".join(to_parse))

            for k in parsed:
                name, value = k.lower(), parsed[k]
                metadata[name] = value

        else:
            for i, line in enumerate(lines):
                kv = line.split(':', 1)
                if len(kv) == 2:
                    name, value = kv[0].lower(), kv[1].strip()
                else:
                    break

        if len(lines) > i+2:
            for line in lines[i+2:]:
                outlines.append(line)
        return metadata, "".join(outlines)
    except Exception as e:
        print(f"Failed to read {fname}: {str(e)}")
        return {}, ""


def write(fname, metadata, content):
    with open(fname, 'w', encoding='utf8') as fp:
        fp.write('---\n')
        yaml.dump(
            metadata,
            fp,
        )
        fp.write('---\n')
        fp.write(content)


def get_file_mod_time(path):
    try:
        return os.path.getmtime(path)
    except OSError:
        # Return the Unix epoch time, i.e., time 0 which corresponds to 00:00:00 UTC on 1 January 1970
        # This effectively means the file is "very old" and needs updating
        return 0.0  # This could also be time.mktime(time.gmtime(0)) for clarity but 0.0 is more concise

def rasterise_to_png(image_path):
    # Read SVG and convert to PNG using cairosvg
    with open(image_path, 'rb') as f:
        svg_data = f.read()

    out_buf = BytesIO()
    svg2png(bytestring=svg_data, write_to=out_buf)
    out_buf.seek(0)  # Reset buffer position to the start

    # Load the PNG data into a Pillow Image object
    return Image.open(out_buf)


def create_thumbnail(image_path, thumbnail_path):
    try:
        if str(image_path).endswith('.svg'):
            img = rasterise_to_png(image_path)
        else:
            with Image.open(image_path) as img:
                img = img.convert('RGB')  # Convert to RGB to ensure compatibility for AVIF

        # Resize and crop the image to fit the specified thumbnail size using ImageOps.fit
        img = ImageOps.fit(img, (THUMB_WIDTH, THUMB_HEIGHT), method=Image.Resampling.BICUBIC, centering=(0.5, 0.5))

        # Save the thumbnail
        img.save(thumbnail_path, format='AVIF')

        print(f"Thumbnail created successfully at {thumbnail_path}")
        return True
    except Exception as e:
        print(f"Failed to create/update thumbnail for {image_path}: {repr(e)}")
        return False


def massage_one_file(fname):
    htmlname = Path("_site") / fname.with_suffix('.html')
    qmdname = fname.with_suffix('.qmd')
    if not (htmlname.exists() and qmdname.exists()):
        return

    _, htmlcontent = read(htmlname)
    metadata, qmdcontent = read(qmdname)

    thumbnail_url = None
    soup = BeautifulSoup(htmlcontent, 'html.parser')

    if soup.body:
        for img in soup.find_all('img'):
            img_url = img.get('src')
            if img_url.startswith('http') or img_url.startswith('data:'):
                continue

            enclosure = img.find_parent(['div'], class_=('figure', 'illustration'))
            if (enclosure is None) or ('foreign' in enclosure['class']) or ('sep' in enclosure['class']):
                continue

            # thumbnail URL has the extension changed to .thumbnail.avif
            thumbnail_url = img_url.rsplit('.', 1)[0] + '.thumbnail.avif'
            # print(f"Found image {img_url} in {htmlname} -> {thumbnail_url}.")

            #paths are always relative to the qmd file in the HTML output
            img_path = fname.parent / img_url
            thumbnail_path = fname.parent / thumbnail_url

            if (
                    get_file_mod_time(thumbnail_path) >
                    get_file_mod_time(img_path)):
                # thumbnail exists and is is newer than the image
                break

            if create_thumbnail(img_path, thumbnail_path):
                # successfully created or updated thumbnail
                break

    old_thumbnail = metadata.get('image', None)
    if old_thumbnail != thumbnail_url:
        if thumbnail_url is None and 'image' in metadata:
            del metadata['image']
        else:
            metadata['image'] = thumbnail_url
        print(f"{htmlname} metadata updated to include thumbnail.")
        write(qmdname, metadata, qmdcontent)


def main(glb0="**/*.qmd", *glbs):
    # TODO: handle "/*.qmd" per default
    for glb in [glb0, *glbs]:
        #TODO: check for non-relative paths
        paths = Path('').glob(glb)
        for fname in paths:
            massage_one_file(fname)


if __name__ == "__main__":
    main(*sys.argv[1:])

It depends upon

Pillow = "^9.0.0"
beautifulsoup4 = "^4.10.0"
"ruamel.yaml" = "^0.17.16"
pillow-avif-plugin = "^1.4.3"
defusedxml = "^0.7.1"
cairosvg = "^2.7.1"

I would have gone with libvips which looks generally nicer, but pyvips currently won't install on macos.

This has got my front page from 135MB down to only 25MB, which is still not amazing, especially since it still requests 1000+ images most of which are never displayed. I guess additional improvements would by via lazy loading images (#9434 )

[cscheid]

Looks great. This is the kind of thing we should offer in our html postprocessor. The main constraint on our side is that we can't depend on Python libraries in the main Quarto install, so we'd have to find a binary that's small enough to ship and exists portably across linux, windows, and macOS.

[danmackinlay]

Yeah, python is not really the most elegant tool for this job, it's just the one I had to hand. It's a pity that the quarto filter route does not seem to work; it could notionally leverage something like the hypothetical embedded libvips as discusse in #9053 .

on THAT note, I rewrote the python script to invoke libvips cli instead of using python Pillow; it turns out to be faster, more reliable and the generated thumbnails seem to be more compatible.

def create_thumbnail(image_path, thumbnail_path):
    try:
        # Constructing the command
        cmd = [
            "vips",
            "thumbnail",
            str(image_path),         
            str(thumbnail_path),   
            str(THUMB_WIDTH),       
            "--height", str(THUMB_HEIGHT), 
            "--size", "down",         # never upscale
            "--crop", "entropy"      # Crop to the interesting bit
        ]

        result = subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

        print(f"Thumbnail created successfully at {thumbnail_path}")
        return True
    except subprocess.CalledProcessError as e:
        print(f"Failed to create/update thumbnail for {image_path}: {e.stderr.decode()}")
        return False
    except Exception as e:
        print(f"An error occurred: {str(e)}")
        return False

[danmackinlay]

Also related:

• Automatically reduce thumbnail image size on Quarto website #3793
• Automatically reduce thumbnail image size on Quarto website - Stack Overflow

[mcanouil]

The SO post is by the same author.
It's only a cross post.
No need to link all cross posts.

[cscheid]

Starting with the next prerelease version, images in Quarto listings will now default to loading="lazy". See #9447