Set out-width equal to fig-width for figure created in code block

[see24]

Bug description

I would like the out-width to equal the fig-width that I have specified in inches in a code chunk. In the documentation it says "By default figures are displayed using their actual size" but this does not happen when I have set the dpi of my figure to be larger than the default. I would like the out-width to be equal to the fig-width in terms of the actual space it takes up on my screen rather than the current behaviour where it is much larger if I have set a larger than default dpi. Currently I can only get this outcome by setting all 4 of fig-width, fig-height, out-width and out-height. If the default needs to stay the same could there be a way to set a yaml option that ties out-width to fig-width?

---
title: "Dpi in Yaml"
format: html
fig-dpi: 300
---

## no options

The figure is created with a size that fits the output space.

```{r}
plot(mtcars[1:4])
```

## fig-height and fig-width specified

If fig-height and fig-width are small relative to the output space the figure will be expanded to fill it. Eg the font size is too large.

```{r}
#| fig-width: 3
#| fig-height: 3
plot(mtcars[1:4])
```

## out-height and out-width specified

Only by setting all 4 can I get a figure that is displayed as the size created it with. Despite this statement in quarto docs "[By default figures are displayed using their actual size](https://quarto.org/docs/authoring/figures.html#figure-sizing)"

```{r}
#| fig-width: 3
#| fig-height: 3
#| out-width: 3in
#| out-height: 3in
plot(mtcars[1:4])
```

RStudio version 2023.03.0+386
Windows 10
Checking Quarto installation......OK
Version: 1.2.335
Path: C:\Program Files\RStudio\resources\app\bin\quarto\bin
CodePage: 1252

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.
• Please provide the output of quarto check so we know which version of quarto and its dependencies you're running.

[cderv]

In the documentation it says "By default figures are displayed using their actual size" but this does not happen when I have set the dpi of my figure to be larger than the default.

I believe this sentence apply to figure included from a file. For figure created with computation chunk, the image file included will be created using a graphic device and dimensions set by fig-with and fig.height. Then this image will be included in the file, but a output width will be set by default on the image included, based on fig-width and fig-dpi settings. This is because default is fig-format: retina. If you set fig-format: png for example, you won't have any default width set on the <img>, and figure included will be using the file dimension.

It seems in our doc we don't document that really well, included which default values for those option per format are used.

Let me give more details - Here is how it will work, especially with the knitr engine. I'll put that in a doc somewhere later.

In HTML format, fig-width default to 7 and fig-height to 5. fig-dpi will have effect on the out-width and the dpi value will be multiplied with the width and height value. By default only output width will be set for you.

This is the default, first chunk in your example - width is set to 2100 (7*300).

Though, when you changed fig-width and fig-height, it will change the image dimension and also the output width dimension.

the figure will be expanded to fill it

Also in the first two case, only output width will be set to the <img> and from the doc

Note that if only width is specified then height is calculated automatically. If you need to modify the default behaviour just add 
an explicit height attribute.

So that is why it fills up the all output space (as we use CSS rule for that). Setting out-height explicitly change that as doc says.

.img-fluid {
    max-width: 100%;
    height: auto;
}

This is controlled by the fig-responsive option, which is the default. If you set fig-responsive: false ; then the img in the HTML won't fill the document space if their specified width is much larger. They will go off screen.

Currently I can only get this outcome by setting all 4 of fig-width, fig-height, out-width and out-height.

To make your example complete, which values did you use in the last chunk ?

I would like the out-width to be equal to the fig-width in terms of the actual space it takes up on my screen

I am trying to correctly understand what you are looking for, but I am unsure. If you share the actual solution you are using, that would help me.

Possibly, you are just looking to tweak the figure option and we really don't document that well...

Hope it helps

[see24]

I am trying to correctly understand what you are looking for, but I am unsure. If you share the actual solution you are using, that would help me.

Sorry I missed that in my post. I have edited it to include the solution.

If you set fig-format: png for example, you won't have any default width set on the <img>, and figure included will be using the file dimension.

I tried setting fig-format: png but it did not help with the issue. With the default options the files created in the files folder for this document are pngs that are the same whether or not out width and height are specified. So the issue is not with the file creation but how it is then displayed

This is controlled by the fig-responsive option, which is the default. If you set fig-responsive: false ; then the img in the HTML won't fill the document space if their specified width is much larger. They will go off screen.

Setting fig-responsive: false did not help either the image as you mentioned above is 7*300 pixels across so the size based on pixels is far too large and bleeds over the edge of the screen. This is the crux of my issue. What I want is to create a figure that is print quality (eg 300 dpi) and display it with the same size in inches it was created with. I understand that this is not how size is typically used in html since the png file doesn't store the information on the size it was created with but quarto has that information and could use it to display the figure at the size (eg 3in by 3in) it was created with unless that width would exceed max-width in which case it makes sense to scale the image to fit the page. But also the dpi information is stored in the pngs created so couldn't that info be used to set the size of the image displayed?

I also tried setting the dpi option to the same as fig-dpi but that did not help and the description in the docs makes it sound like the information stored in the image should be used if available

For a user it is confusing that fig-height and fig-width seem to use inches as the default (although this doesn't seem to be explicitly stated in the reference docs) but the output you get does not consider that info.

Thanks for your help with this!

[cderv]

With the default options the files created in the files folder for this document are pngs that are the same whether or not out width and height are specified.

They are the same because fig-width and fig-height are what controls the image size in the png, and it is the same no matter fig-format used. out-width and out-height controls the dimension of a file when included inside a document. Not the file size itself at creation.

What I want is to create a figure that is print quality (eg 300 dpi) and display it with the same size in inches it was created with.

Setting fig-format: png will lead to no default out-width calculated, and fig-responsive: false will lead to no CSS to size the img to the space available. So setting both should give you the same size in your document, as the size of the plot.

Doing this, your second and last chunk produce for me the same 900x900px png file. (3*300 x 3 * 300)

The second chunk does not set out-* config, so the file shown in the HTML output has sized 900 x 900 px like the file

When out-width and out-height are set to 3in - this is passed in HTML file CSS style element on the img tag

<img src="test2_files/figure-html/unnamed-chunk-3-1.png" style="width:3in;height:3in">

and this get me a 288*288px image on screen - this is because resolution on my screen is 96dpi as it seems to be usually expected for screen (https://developer.mozilla.org/en-US/docs/Web/CSS/length#absolute_length_units)

If you really want the later, then setting all the fig-* and out-* options is the way to do it IMO.

[see24]

What I am saying is that a user would want a default out-width to be calculated (so not fig-responsive: false) and they would want it to be created in a way that looks good on the screen for the image they created.

Obviously I want the later why would anyone want an image that is displayed much larger (in terms of space occupied on the screen) than the image they created? Why would they have specified fig-width and fig-height if they wanted the image to fill the whole space. I get that an image on screen can't always be displayed with the resolution it was created with but it can be displayed at the size (in inches) it was created with and surely that is more desirable for more users?

When I set the dpi to be larger than the default it is primarily so that I can use the files created in the files folder for the document in another context such as in a powerpoint to be projected on a large screen or in print. That is what changing fig-dpi is useful for, I can't imagine most users would set fig-dpi with the goal of changing the space it occupies on a screen. And I think the default out-width should assume that, this is what happens when I create an image without setting fig-height and fig-width, the image created has the requested dpi but the amount of space occupied on the screen does not change from if I hadn't specified dpi.

If you look at the output in other formats (docx or pdf) the desired behaviour is produced, both chunks 2 and 3 have figures of the same size. It would be great if documents in each format could render the same, or if that can't be the default behaviour for some reason then if there was a global option that could be set so the figure size would be the same.

The best default behaviour IMO would be for the default out-width to be calculated in a way that considers the dpi of the image being rendered such that:
out-width in inches = image px width / dpi = fig-width

in the same way that the image px width created when fig-width is not set is:
image px width = out-width in inches (ie 7) * dpi

In all cases out-width in pixels is subject to the dpi of the screen

[cderv]

Thank you for the explanation - that is really interesting ! I think we have covered the all usage and different scenario

What I understand from all this is that your proposal is to use a default out-width in inches instead of pixels for HTML document too.

Currently we get out-width (in px) = fig-width (in inches) * dpi and you are saying we should do out-width (in inches) = fig-width (in inches).

I'll keep this as the proposal

The best default behaviour IMO would be for the default out-width to be calculated in a way that considers the dpi of the image being rendered such that:
out-width in inches = image px width / dpi = fig-width

This is the last part I am unsure to understand.

• fig-width is used already to get the image size in pixel using fig-width * dpi.
• So doing having an out-width in pixel would just be ignoring dpi information and have out-width = fig-width
• The later can be done at the chunk level by providing the option explicitly, as you've done it

in the same way that the image px width created when fig-width is not set is:
image px width = out-width in inches (ie 7) * dpi

Did you mixed out-* and fig-* ? fig-width default to 7 in HTML format. and out-width is calculated based on this times dpi, for default fig-format = "retina". Otherwise, not specific out-width is applied - in both case, CSS also applies through max-width: 100% rule.

Maybe I am still missing something.

[see24]

Thanks for sticking with me! I think you have captured the proposal correctly.

I am not sure about the last part either, it is not really important other than as an example of the user experience of being able to set dpi and have the file created reflect that but not having the space occupied on screen change. I might have been mistaken about how that is achieved though since it sounds like it has more to do with max-width. But either way not super relevant here.

Documentation wise it was nice to see this section https://quarto.org/docs/computations/execution-options.html#figure-options which I hadn't found before. Maybe it could be linked in the Authoring/Figures/Computations section? Also would be great if out-width and height were described here as well.