Repository navigation
Images in the docs are too large. #11190
Description
Bug report
Noting from #11188, there are a number of examples containing too large figures.
I assume that comes from the figure.dpi change between classic (80dpi) and modern style (100dpi).
Generally, the approach of changing the figsize as in #11188 is not good, as the fonts remain the same size and may become disproportional. Should we instead overwrite the dpi in these examples? Fig sizes in pixels should note be wider than 900px.
Example:
https://matplotlib.org/gallery/showcase/bachelors_degrees_by_gender.html?highlight=bachelor
Probably won't look good with reduced fig size (and keeping text size).
Activity
ImportanceOfBeingErnest commentedon May 7, 2018
In general I'd say that the procedure could be:
subplots_adjust(..))What shouldn't happen though is that like in the case of the colormap reference the text becomes unreadable.
jklymak commentedon May 7, 2018
-1 on
subplots_adjust, though that example already uses it. That example was actually what got me going on making text elements be part of constrained_layout and tight layout.-2 on changing the dpi, just because we don't want a bunch of dpi adjustements in the examples.
I think 14-pt font in the example above is probably way overkill for what is being labelled. Most journals are OK with down to 8-pt, so I imagine 10 pt would be fine. I don't have the PR on this machine, but I had that example much smaller and it looked fine.
ImportanceOfBeingErnest commentedon May 7, 2018
The bachelor degree example was added in version 1.5 where the default screen dpi was 80 indeed. So to keep it close to the original author's intend, one could simply set the dpi back to 80.
jklymak commentedon May 7, 2018
Telling users to change the dpi of a figure when they really want to change the size is wrong in my opinion. I appreciate that the (default) size of the figure in html is set by the number of pixels, but...
Actually, it would be nice if sphinx-gallery set the image width property in the html based on the value of figwidth.
ImportanceOfBeingErnest commentedon May 8, 2018
I really don't know where that idea that scaling an image via the dpi is wrong would originate from. A reference for that would be helpful. One may argue that it is undesired for whatever objective reason in this case. (Although I personally wouldn't know of any.)
Sphinx-gallery has no control over the html. It creates rst files. It could however scale the image itself, or set the width via the rst
:scale:. But it currently does this only in case you have several output figures. (Also quality is not really good if you let the browser scale the image.)ImportanceOfBeingErnest commentedon May 8, 2018
Note that it would be possible to add a css rule to shrink images in the browser:
As said, the quality would not be great, but it may be the least invasive concerning actual example code.
mwaskom commentedon May 8, 2018
This looks a lot like something we ran into with the pysurfer docs after switching over to sphinx-gallery: nipy/PySurfer#225
jklymak commentedon May 8, 2018
Ok so looks like this is in SG master?
ImportanceOfBeingErnest commentedon May 8, 2018
Seems this merged in sphinx-gallery/sphinx-gallery#210, but not released yet.
The idea is essentially the same as the above css, just that they now have their own class for the images.
tacaswell commentedon May 8, 2018
We have two knobs on the output size in pixels (the size in inches and the dpi). It is better to tune the size in inches as it won't make the plots fuzzy.
ImportanceOfBeingErnest commentedon May 8, 2018
As long as there is no way to scale the elements in the plot, i.e. have a "base size" and relative size units for all quantities used for setting a size, using the size in inches to scale a matplotlib figure is purely theoretical. In practice you would never go through all 200 elements of your plot and change their size to scale a plot. This is a design flaw of matplotlib, but it is like it is and one can work around it using dpi. So why advise people differently?
timhoffm commentedon May 9, 2018
As a quick workaround and hard limit the CSS max-width is good.
Nevertheless, we should try to generate doc images in a size so that they don't get scaled. However, this would be a case by case effort. Approximately 38 images will be affected (regexp search
figsize=\(\d{2}). Some images can be made smaller without messing them up severely. Others - like the one linked above would need additional adjustment of text sizes.jklymak commentedon May 9, 2018
Size in inches, points, and other physical units is how most typography and graphics layout is done. Microsoft Word, Illustrator, etc all have the little ruler on the side in inches because you are usually working to make your graphics a certain size. For journal articles, the tradition has either been one column (about 3") or two-column (~6.5") in width, and something less than 8.5" or so in height.
You can always tell the first-time report writers in an undergraduate class by the ones who take the graphic they made in Matlab or Excel and then stretch/shrink it to the size that fits the page in Word; fonts become tiny and unreadable, line widths change, and in really egregious cases the aspect ratio changes. If they had laid it out at their intended size while composing the figure, they would have had a much better final-looking product.
I don't quite understand this statement. If I'm looking at a jpg, most jpg viewers have zoom tools, and I can make it any size I want. If it must be a fixed number of pixels wide, I'd just resample a high-res jpeg with something that does good anti-aliasing on the fully composed image (unlike the native piecemeal native anti-aliasing) like many GUI-based image manipulation tools, or imagemagick.
In this case, a small shrink is probably fine; I do that all the time when I'm preparing for publication, but I do it in the word-processing package, not matplotlib. I just don't think user-facing documentation should have calls to twiddle the dpi.
ImportanceOfBeingErnest commentedon May 9, 2018
The question is: Is this worth fixing before sphinx v0.1.14 is released?
Pro: We don't know when that will eventually happen. (in a recent comment 5 days ago it says "We are still not ready with a release [...]".)
Contra: Unecessary work in the long term, and it would obscure those images where some tweaking is needed.
jklymak commentedon May 9, 2018
I think its worth fixing in general. The example above is comically large, for no good reason that I can discern. 14-pt fonts for labelling on a figure that can be 9" wide is pretty extreme, and shrinking down to 11-pt makes everything fit on a 9" figure w/o a problem. To me 9" is still comically large, but at least it will fit.
https://gist.github.com/jklymak/49f9e53ac6dc7cd7812af59b70a5e38a
timhoffm commentedon Oct 7, 2018
Not sure if all the cases have been fixed by now, or if the gallery got smarter, but I don't observe the behavior anymore.
ImportanceOfBeingErnest commentedon Oct 10, 2018
It's both. Some examples got fixed and mostly it's the new Sphinx gallery version being used by default, which uses a
max-widthin the CSS. Of course those would appear a bit blurry. So in case someone stumbles upon one of those, it would still make sense to restrict the size to 900pixels.