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:

"external-graphic" - "content-width" and "content-height"

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

 Introduction of XSL-FO

 Apache™ FOP (Formatting Objects Processor)

 RenderX XEP as an XSL-FO Tool

 Introduction of Area Model

 XSL-FO Document Basics and Examples

 Page Layout Masters

 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

 Table of Rows and Columns

 List, Item, Label, and Body

 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

 RenderX XEP Font Configurations

 References

 PDF Printing Version