DOC: make all images hi-DPI - #19852

Ideally, this should be accompanied by measures to reduce the amount of transferred data again, e.g. one or more of:

• Lazy loading of the thumbnails. I've opened an issue at sphinx-gallery: Lazy loading of gallery thumbnails sphinx-gallery/sphinx-gallery#803
• Providing different images depending on screen resolution, see e.g. https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#resolution_switching_same_size_different_resolutions. This would also require an extension of sphinx-gallery so that it produces multiple thumbnails of different sizes.
• Investigate if SVG thumbnails would easy to generate and if they are smaller than the optimized pngs.

Here is what this looks like: https://55954-1385122-gh.circle-artifacts.com/0/doc/build/html/index.html

Despite what I said above, the thumbnails are the same size regardless of the dpi of the parent.

I don't think that the individual images on the individual pages are so giant that its worth serving different sizes. sphinx_glr_scatter_with_legend.png is 72 dpi (!), and 254 kb; with this change it is now 628 kb, and that is before cloudflare optimizes it.

All my suggestions are primarily intended for the thumbnails. I agree that individual gallery images aren't that important because you only load a few.

I think this looks better...

I looked into svg. a) in quite a few places we have links to pngs. b) animations don't work, c) at east on my version of sphinx :scale: doesn't work with svg. d) pcolormesh defaults to drawing facets edges (maybe a bug?). Anyway, overall there seemed to be enough hurdles that it was more than I wanted to tackle. But upping to 200 dpi seems a reasonable first step to me.

For some reason the scaling is not exactly a factor 2 here:

Also on non-hi-dpi, some lines and text is bulky:

old (unscaled) / new (scaled):

(This does not have to do with the not-exactly factor 2 scaling. Even if I force a scaling of 2x the difference remains).

Tested with Chrome and Firefox: Both give slightly different scaled images but neither looks good.

Compare yourself:
old
new

IMHO this is a deterioration of the non-hi-dpi images and thus a blocker.

In the above, the RHS screenshot looks better on my retina display? Is that a pixel grab from your machine? I'm confused how a 72-dpi image could render better than a 200-dpi image. In general I am confused by what you are trying to say (but I don't have a 100dpi monitor, so..)

The scaling is not a factor of two because it is 72 dpi versus 200 dpi, and then a 70% scaling of the image. So 1280 is 6.4 inches at 200 dpi. That 6.4 inches was 461 pixels at 72 dpi.

This is a pixel-grab from my machine. It might be that these screenshots cannot be reasonably compared on a hidpi screen.

I'm a bit surprised where the 72 dpi / 461px should come from. On the above devdocs build I see

I think we have a 100dpi image, and there we can draw 1px wide lines lines, e.g. for the spines, which are drawn 1:1 and thus look sharp and exactly as intended. Similar with fonts: 2x oversampling + antialiasing + downsampling is different than directly antialiasing on 1x fonts.

Agreed, I think maybe somehow my local machine was defaulting to 72 dpi....

But I'm not sure what to say about the scaling of 200 dpi images. We don't specify any many dimensions in Matplotlib by pixels, we almost always use points. So I'm pretty skeptical that a 1-pt line will look better at 100 dpi than 200 dpi. I guess its possible browser x will do donwsampling poorly, but lets try an exact factor of 2 and see if it improves things?

I really don't understand the scaling. This makes https://56240-1385122-gh.circle-artifacts.com/0/doc/build/html/gallery/lines_bars_and_markers/bar_label_demo.html#sphx-glr-gallery-lines-bars-and-markers-bar-label-demo-py The image is 1280x960 as expected, but it gets scaled to 460x345, which is (1280x960)/2*0.72 I don't understand where the 0.72 comes from...

width: 50%; in CSS is 50% of the container, not the image. Compare the images after shrinking your browser window.

The only way to treat this image as 2x dpi, is to specify it in srcset, I think, as in @timhoffm MDN link.

Ugh, implementing srcset is a bit of a project. sphinx-gallery only makes a sphinx-directive to the image it creates, so modifying the scraper to make both versions of the image was no problem. But we would also need to write a new directive .. image-srcset:: or somesuch to make the html. Maybe that is not as daunting as the plot_directive.py makes it look (since I assume that also makes the plots).

There's a principle willingness at sphinx-gallery to make a custom image directive. That could be combined with the lazy-loading effort (see sphinx-gallery/sphinx-gallery#803 (comment)).

So ideally, this goes upstream and sphinx-gallery provides a more capable figure/image (not sure which one should be adapted) directive.

Seems like docutils itself is not very respnsive. At least there hasn't been any reaction to my lazy loading feature request https://sourceforge.net/p/docutils/feature-requests/78/.

I hacked a proof of concept together. It's not too bad so far. But if we adopt something like it, it would be nice if someone upstream took it on.

OTOH I'm not sure anyone will be happy about the extra render time to make two copies of each image in the gallery.

OTOH I'm not sure anyone will be happy about the extra render time to make two copies of each image in the gallery.

One could introduce an option for this and only enable it for releases (or disable on CI).

@timhoffm I invited you to https://github.com/jklymak/sphinx-image-srcset. It works for the simple gallery that I have put in there. Still pretty messy, and not deployable, but maybe you had feedback...

OTOH I'm not sure anyone will be happy about the extra render time to make two copies of each image in the gallery.

Is it not just a second savefig like we do in plot_directive for multiple formats?

It is just a second savefig with the dpi call changed.

Closing in favour of fixing this in sphinx-gallery...sphinx-gallery/sphinx-gallery#808