= Image Scaling
:description: An image can be scaled using one of the width attributes, such as pdfwidth, scaledwidth, image-width, or width.

PDF is a fixed-width canvas, therefore you almost always need to specify a width to get the image to fit properly on the page.

[#width-attributes]
== Image width attributes

There are several attributes available for specifying the width of an image.
These attributes are listed in the following table in order of precedence.

[cols="1s,3"]
|===
|Attribute{nbsp}Name | Description

|<<pdfwidth,pdfwidth>>
|The display width of the image as an absolute size (e.g., 2in), percentage of the content area width (e.g., 75%), percentage of the intrinsic width of the image (e.g., 50iw), or percentage of the page width (e.g., 100vw).
If a unit of measurement is not specified (or not recognized), points (`pt`) is assumed.
_Intended to be used for the PDF converter only._

|scale
|A percentage of the intrinsic width of the image.

|scaledwidth
|The display width of the image as an absolute size (e.g., 2in) or percentage of the content area width (e.g., 75%).
If a unit of measurement is not specified, percentage (`%`) is assumed.
If a unit of measurement is recognized, points (`pt`) is assumed.
_Intended to be used for print output such as PDF._

|<<image-width,image-width key from theme>>
|Accepts the same values as `pdfwidth`.
_Only applies to block images and xref:theme:block-images.adoc#fallback[is set in the theme], not the content._

|width
|The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image.
If the value ends in `%` (not recommended), it's assumed to be the percentage of the available content area width.
If the width exceeds the content area width, the image is scaled down to the content area width.

|fit
|_(Inline image only)_
If the value is `line`, the image will be scaled down proportionally, as necessary, to fit the height of a line of text.
If the value is `none`, the image will never be scaled down to fit within the height of the content area.
The `none` value should only be used as a workaround in cases when the converter is scaling the image when it shouldn't.

|_unspecified_
|If you don't specify one of the aforementioned width settings, the intrinsic width of the image is used (the px value is multiplied by 75% to convert to pt, assuming canvas is 96 dpi) unless the width exceeds the content area width, in which case the image is scaled down to the content area width.
|===

TIP: Images in running content and page background images also support the `fit` attribute when specified using the image macro.
However, the acceptable values of the `fit` attribute in those cases differs from the acceptable values for an inline image.
See xref:background-images.adoc[] for details.

[#default]
== Default sizing

An image is always sized based on the user-specified or intrinsic width (aka the resolved width), then its height is scaled proportionally.
The computed height of the image is honored unless this value exceeds the height of the content area.
In this case, the image is scaled down to fit within the content area.

The height of the content area is typically the space between the top and bottom margins of the page.
However, the content area in table cells is handled in two phases.

=== Inline image sizing in table cells

In tables, each cell is considered its own content area.
That content area is computed based on how much space the content requires, though still limited to the space between the top and bottom margins of the page.
Inline images in table cells are permitted to increase the height of the cell.
However, there can be differences in how the image is sized in a normal cell compared to an AsciiDoc table cell.

The calculation of the content's height in a normal table cell can be inaccurate, often impacted by the font used.
When the table cell is rendered, its height is restricted to the computed height.
This can impact the sizing of inline images in a normal table cell if `fit=line` is set on the image.
If the computed height ends up being less than the line height, the image will be scaled down to fit.
If you want to prevent the converter from attempting to scale down the height of the inline image in a normal table cell, don't use `fit=line` or set `fit=none` on the inline image.

The content area of an AsciiDoc table cell is computed more accurately.
// NOTE TO AUTHORS: This is because Asciidoctor PDF calculates the content height itself and does so accurately
Thus, when you specify the `a` style on a table cell, the scaling of an inline image is true.
An inline image will never be scaled down if it fits within the maximum available height of a single page.
In this scenario, the `fit=line` attribute will work in the same way it does outside a table cell.

[#pdfwidth]
== pdfwidth attribute

The `pdfwidth` attribute is the recommended way to set the image size for the PDF output.
This attribute is provided for two reasons.
First, the fixed-width canvas often calls for a width that is distinct from other output formats, such as HTML.
Second, this attribute allows the width to be expressed using a variety of units.

The `pdfwidth` attribute supports the following units:

* pt (default)
* in
* cm
* mm
* px
* pc
* iw (percentage of intrinsic width of image)
* vw (percentage of page width)
* % (percentage of content area width)

In all cases, the width is converted to pt internally.

NOTE: See this https://groups.google.com/forum/#!msg/prawn-ruby/MbMsCx862iY/6ImCsvLGfVcJ[discussion about image quality in PDFs^] for more information.

[#image-width]
== Fallback width for block images

To scale all block images that don't define either a `pdfwidth` or `scaledwidth` attribute on an image macro in your document, assign a value to the `image-width` key in your theme file.
If specified, the `image-width` value takes precedence over the `width` attribute on an image macro.
See xref:theme:block-images.adoc[] to learn how to set the `image-width` key in the theme.

== Align block image to page boundaries

If you want a block image to align to the boundaries of the page (not the content margin), specify the `align-to-page` option (e.g., `opts="align-to-page"`).
This is most useful when using vw units because you can make the image cover the entire width of the page.


