Latex: Figures with no size defined get overscaled

[Blendify]

Describe the bug
When generating a latex/pdf output figures get scaled up too much if the they have no size defined. Instead the image should only be scaled to its natural size (the size in px from the image file) or scaled to the page width if the image file size is too big.

To Reproduce
Rst file

.. figure:: /some/image.png

   Caption.

.. figure:: /some/image.png
  :width: 200px

   Caption.

image.png is 200px wide.

Expected behavior
The results should be the same for the two images

Your project
https://svn.blender.org/svnroot/bf-manual/trunk/blender_docs/

Screenshots
If applicable, add screenshots to help explain your problem.

Environment info

• OS: Ubuntu
• Python version: 3.8
• Sphinx version: 3.2.1
• Sphinx extensions: none
• Extra tools: texlive-xetex latexmk

[jfbu]

Sorry for late, will look into it.

[jfbu]

This is at any rate inherited from LaTeX behaviour. I downloaded your sample image and tried it out in direct latex document this way

\documentclass{article}
\usepackage{graphicx}
\begin{document}

\noindent\includegraphics{render_shader-nodes_input_volume-info_node.png}

\end{document}

this renders exactly at same size as using figure directive as in your index.rst. The latex log file contains

<render_shader-nodes_input_volume-info_node.png, id=1, 223.83624pt x 199.74625p
t>
File: render_shader-nodes_input_volume-info_node.png Graphic file (type png)
<use render_shader-nodes_input_volume-info_node.png>
Package pdftex.def Info: render_shader-nodes_input_volume-info_node.png  used o
n input line 5.
(pdftex.def)             Requested size: 223.8357pt x 199.74576pt.

If I open this image file in Preview.app on my mac it tells me the dimensions are 223 x 199 pixels, with dpi of 72px/inch.

Latex pt unit is 72.27pt per inch, so (it matches the above as 199.74576/72.27 * 72 gives about 199. LaTeX does computation only with at most 4 or 5 decimal digits precision). And fwiw, Preview.app actually shows me by default a slightly wider image than in the pdf viewed in Skim.app.

Does the png file actually contain what the image target dimensions are supposed to be on screen? does it contain a precise ppi spec ?

[jfbu]

And fwiw, Preview.app actually shows me by default a slightly wider image than in the pdf viewed in Skim.app.

this was silly because there was some scaling in the pdf viewer. I opened in Adobe Reader and chose "natural size" (or "real size" don't know the English mine is localized), and the display is a bit wider than the one in Preview.app.

What do you mean by "overscaled"?

[jfbu]

ah I get it, sorry. The precise issue seems rather to be that images with width given in px units are underscaled. For strange reason I had not used your test file comparing two image inclusions. Originally TeX had no px unit. But pdftex engine introduced px as a configurable dimension. Its defautl setting is 72px=1in and this can be configured. For some reason, Sphinx has default 96px=1in. This is decided by the 'pxunit'.

Your test image has a width of 223px (and a height of 199px; maybe there was confusion here? but this does not explain the issue).
As Sphinx by default tells latex that 96px=1in, this is rendered in the pdf as an object of width 2.323in. This is how it will look like when the pdf viewer shows the pdf at its "real size" (and assuming the pdf viewer understands correctly the device resolution).

If you don't specify a width in px, the job of recovering it is done from the pdftex graphicx driver and it handles the px has meaning 72 px to one inch. So you end in pdf with an object of width 223/72in=3.097in which looks overscaled. But it is in fact the correct dimension for 223 pixels at 72 pixels per inch.

I am not competent enough in image format files to know if the 72ppi used both by pdftex graphics inclusion and the Preview app on mac os x is actually hard-coded in the image file or is a default of them.

latex_elements = {
    'pxunit': '1bp',
}

will resolve the discrepancy but then the px width specification too will give you a larger image. Still not as wide, because you use 200px but this image natural width is 223px. So at 223px you get same result. That is the large width result. I will investigate more is there is something at the level of latex graphicx inclusion at odd with the setting done of the pdftex configuration \pdfpxdimen. We set it to 1/96th of an inch (\pdfpxdimen=0.75bp) , but the driver handles for this image 1px as 1/72th of an inch. Either the 72ppi is in the image file as png, or it is default from driver.

[jfbu]

Ok, there is another parameter in pdftex engine (texdoc pdftex on texlive based installations).

\pdfimageresolution (integer)
The integer \pdfimageresolution parameter (unit: dots per inch, dpi) is a last resort value, used only for bitmap (jpeg, png, jbig2) images, but not for pdfs. The priorities are as follows: Often one image dimension (width or height) is stated explicitly in the TEX file. Then the image is properly scaled so that the aspect ratio is kept. If both image dimensions are given, the image will be stretched accordingly, whereby the aspect ratio might get distorted. Only if no image dimension is given in the TEX file, the image size will be calculated from its width and height in pixels, using the x and y resolution values normally contained in the image file. If one of these resolution values is missing or weird (either < 0 or > 65535), the \pdfimageresolution value will be used for both x and y resolution, when calculating the image size. And if the \pdfimageresolution is zero, finally a default resolution of 72 dpi would be taken. The \pdfimageresolution is read when pdfTEX creates an image via \pdfximage. The given value is clipped to the range 0..65535 (dpi).

Now I tested adding \pdfimageresolution=96 and then the two images (the one with no width spec, the other with 223px width) render the same i.e. both handle the image resolution at 96 pixels per inch.

If the documentation above is correct, then this means that this png file has no correct x-resolution and y-resolution data, else my setting of \pdfimageresolution would not have been obeyed.

But in the end it does mean there is a bug of Sphinx here of not setting \pdfimageresolution. I must now investigate if a similar parameter exists in platex and xetex and luatex engines.

The default Sphinx setting says to handle explicitly given px unit as 96 pixels per inch. But Sphinx forgets to inform the pdftex that in case an image does not have x-resolution/y-resolution data that it too should use 96 pixels per inch. We must do that in order for images with un specified or garbage resolution data (or unreadable by pdftex) to give same result when included without width specification or when included with width specification equal to what an image viewer would say is the actual width in pixel.