XSL-FO Tutorials - Herong's Tutorial Examples - Version 2.10, by Dr. Herong Yang
Control DPI with "content-width" and "content-height"
This section provides a tutorial example on how to use 'content-width' and 'content-height' attributes in 'external-graphic' formatting object to control image rendering resolution, DPI (Dot Per Inch).
When you use an "external-graphic" formatting object to display an image, the XSL processor will calculate the inline area size using the default resolution.
For example, Apache FOP uses 72 DPI (Dot Per Inch) as the default resolution. So if you have an image of 277x163 px (pixel), it will be displayed in an inline area of 277/72 x 163/72 = 3.85x2.26 in (inch).
72 DPI is actually a very poor quality. Today's laser printer can print at 600 DPI to give you very sharp images. So the question is how to change the "external-graphic" image rendering resolution?
Unfortunately, XSL 1.1 specification does not give us any attribute to control the image rendering resolution. One workaround is to specify "content-width" and "content-height" values to be lower than the actual image pixel size to get a higher rendering resolution.
For example, if you have an image of 277x163 px and you specify content-width="139px" and content-height="82px" (scaled down by half) in the "external-graphic" formatting object, Apache FOP will apply 72 DPI to the specifies size of 139x82 px and render the image in an inline area of 1.93x1.13 in. This will double the rendering resolution giving us 144 DPI!
Here is my tutorial example, external-graphic-content-width-height.fo, that has two "external-graphic" formatting objects showing the impact of content-width="..." and content-height="...":
<?xml version="1.0" encoding="utf-8"?> <!-- external-graphic-content-width-height.fo - Copyright (c) 2016, HerongYang.com, All Rights Reserved. --> <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> <fo:layout-master-set> <fo:simple-page-master master-name="page" margin="0.1in" page-height="5in" page-width="5in"> <fo:region-body region-name="body" background-color="#eeffff"/> </fo:simple-page-master> </fo:layout-master-set> <fo:page-sequence master-reference="page"> <fo:flow flow-name="body"> <fo:block border-width="1px" border-style="solid"> <fo:block-container width="1in" border-width="1px" border-style="solid"> <fo:block>1 inch</fo:block> </fo:block-container> <fo:block-container width="72px" border-width="1px" border-style="solid"> <fo:block>72 px</fo:block> </fo:block-container> <fo:block border-width="1px" border-style="solid"> Picture size = 277x163 at default resolution: <fo:external-graphic src="Newton-Third-Law-of-Motion.jpg"/> </fo:block> <fo:block border-width="1px" border-style="solid"> Picture size = 277x163 scaled down by half: <fo:external-graphic src="Newton-Third-Law-of-Motion.jpg" content-width="139px" content-height="82px"/> </fo:block> </fo:block> </fo:flow> </fo:page-sequence> </fo:root>
If you process this example XSL-FO document with Apache FOP tool to a PDF file, you should see the second image is having a much higher resolution:
Conclusion: Do not use Apache FOP default resolution. Give "content-width" and "content-height" half of the image real size to get better resolution.
Last update: 2016.
Table of Contents
About This XSL-FO Tutorial Book
Apache™ FOP (Formatting Objects Processor)
XSL-FO Document Basics and Examples
Block-Level Formatting Objects
Inline-Level Formatting Objects
►Including Graphics in XSL-FO document
What Is "external-graphic" Formatting Object?
►Control DPI with "content-width" and "content-height"
Fixed Higher DPI with "scale-to-fit"
Resolution Included in Image Files
Image Over and Under Flow Area
"external-graphic" with SVG Diagram
"instream-foreign-object" Formatting Object
Floating Blocks - "float" and "footnote"
Hyperlinks, Table of Contents and Indexes
Headers and Footers using "static-content"
Font Attributes and Font Families
Apache FOP Font Configurations