Image sizing

Image sizing
	Chapter 17. Graphics

People who are familiar with HTML markup often try to use the width attribute in an imagedata tag to scale their graphic. And often it works. But when they try to use other image attributes, they get strange results. Image sizing can be somewhat complex because there are many imagedata attributes that affect it. In addition to sizing the image itself, you can specify a viewport area, which is the space reserved for the image. If the viewport area is larger than the final image size, then there is white space around it. If the viewport area is smaller than the final image size, then the image is supposed to be clipped (but it doesn't happen in HTML output, may not happen in print output).

These are the attributes available in the imagedata element for sizing:

Imagedata scaling attributes

contentwidth, contentdepth

Specify the horizontal width or vertical height, respectively, of the image itself. You can specify a size using any of these units (with no space between the number and the unit):

px   Pixels (the default unit if none is specified)
pt   Points (1/72 of an inch)
cm   Centimeters
mm   Millimeters
pc   Picas (1/6 of an inch)
in   Inches
em   Ems (type size)
%    Percentage (of intrinsic image size)

If one of these attributes is specified, then the image is scaled proportionally to that size. You can stretch the image by specifying values for both attributes that differ from the original ratio of width to height of the image.

width, depth

Specify the horizontal width and vertical height, respectively, of the viewport area, not the graphic. It uses the same units as above, except percentage is taken to be of the available area (so 50% means half the available width after the current indent is subtracted). If these attributes are not specified, then the viewport is the whole page. These attributes will not affect the size of the image itself, with one exception. For backwards compatibility, if they are used without any other scaling attributes, the stylesheets will scale the image itself to the specified sizes. Think of it as a way of specifying the viewport area with the assumption that it should be filled up.

scale

A percentage scaling factor, but expressed without the percent sign. A value of 75 means to scale the graphic to 75% of its intrinsic size. It scales both width and height proportionally, so the image retains its original aspect ratio.

scalefit

If set to a value of 1, then the processor will scale the graphic proportionally to fit the allowed area. The image is scaled to fit the specified width or depth viewport dimension, whichever fills up first. If neither are specified, then it will scale to the available page width.

The definitive description of how these attributes are supposed to affect the output appears in the reference page for imagedata in DocBook: The Definitive Guide. In practice, some of the attributes are not fully supported by some processors.

Here is some guidance for using the scaling attributes.

To scale a graphic to a given width, set the contentwidth in the imagedata element to that size, for example contentwidth="8.5cm". If you specify a number without units, it is assumed to be pixels.
To scale a graphic to fit the available width in printed output, use width="100%" and scalefit="1" attributes. For indented text as in a list, the available width is from the current indent to the right margin.
To keep a graphic for printed output at its natural size unless it is too large to fit the available width, in which case shrink it to fit, use scalefit="1", width="100%", and contentheight="100%" attributes.
To set a default viewport width for graphics that have no scaling attributes, set the stylesheet parameter default.image.width parameter to the desired width. This sets only the viewport size, not the image size. For HTML output, if no other scaling attribute is used, then the image will be scaled to fit this viewport. For print output, the image is not scaled to fit this viewport.
Using percentages in contentwidth to scale a graphic for HTML output can be tricky. It means a percentage of the image's intrinsic width, but the XSLT processor may not be able to figure out what is the intrinsic width of a graphic. The HTML stylesheet can use an extension function in Saxon or Xalan to extract the size information from the file, if the use.extensions and graphicsize.extension parameters are set to 1. If the extension is not used, the stylesheet uses a default width specified in the nominal.image.width parameter, which is 540 pixels for HTML output. That is probably not the image's actual size, so the output may not be what you expect. XSL-FO processors don't have to use these extensions because they can determine the intrinsic image size for the formats they support.
In HTML output, combinations of contentwidth and width are handled by putting the graphic in an HTML table. The width attribute sets the table width to create a reserved area, and the contentwidth is used to scale the image within the table.
The following attributes are mutually exclusive: contentwidth, scale, and scalefit. If more than one of these attributes is used on an image, then the earliest one in this list takes precedence.
Some XSL-FO processors don't support all of these attributes. You may need to experiment to see what works. For example, FOP version 0.20.5 treats width as if it were contentwidth and ignores any real contentwidth attribute.

Different sizes for HTML and FO output

You may find that you need to scale an image differently in HTML than in FO output. You can do this by creating nearly duplicate imageobject elements in a mediaobject. You can put different values for the scaling attributes in the imagedata element in each imageobject. Then you let the stylesheet select the appropriate imageobject for a given output. See the section “Selecting file formats” for more information.

If you just want to turn off scaling for HTML output, then that is even easier. If you set the stylesheet parameter ignore.image.scaling to a non-zero value, then all images in HTML output will appear in their intrinsic size. So you use the scaling attributes solely for FO output, and they will be ignored for HTML output.


Stylesheet's selection process		Image alignment