Package org.apache.pdfbox.rendering

Class PDFRenderer

java.lang.Object

org.apache.pdfbox.rendering.PDFRenderer

public class PDFRenderer
extends java.lang.Object

Renders a PDF document to an AWT BufferedImage. This class may be overridden in order to perform custom rendering.

Author:

John Hewson

Field Summary

Fields

Modifier and Type	Field	Description
protected PDDocument	document

Constructor Summary

Constructors

Constructor	Description
PDFRenderer(PDDocument document)	Creates a new PDFRenderer.

Method Summary

Modifier and Type	Method	Description
protected PageDrawer	createPageDrawer(PageDrawerParameters parameters)	Returns a new PageDrawer instance, using the given parameters.
AnnotationFilter	getAnnotationsFilter()	Return the AnnotationFilter.
RenderDestination	getDefaultDestination()
float	getImageDownscalingOptimizationThreshold()
java.awt.RenderingHints	getRenderingHints()	Get the rendering hints.
boolean	isGroupEnabled(PDOptionalContentGroup group)	Indicates whether an optional content group is enabled.
boolean	isSubsamplingAllowed()	Value indicating if the renderer is allowed to subsample images before drawing, according to image dimensions and requested scale.
java.awt.image.BufferedImage	renderImage(int pageIndex)	Returns the given page as an RGB image at 72 DPI
java.awt.image.BufferedImage	renderImage(int pageIndex, float scale)	Returns the given page as an RGB image at the given scale.
java.awt.image.BufferedImage	renderImage(int pageIndex, float scale, ImageType imageType)	Returns the given page as an RGB or ARGB image at the given scale.
java.awt.image.BufferedImage	renderImage(int pageIndex, float scale, ImageType imageType, RenderDestination destination)	Returns the given page as an RGB or ARGB image at the given scale.
java.awt.image.BufferedImage	renderImageWithDPI(int pageIndex, float dpi)	Returns the given page as an RGB image at the given DPI.
java.awt.image.BufferedImage	renderImageWithDPI(int pageIndex, float dpi, ImageType imageType)	Returns the given page as an RGB image at the given DPI.
void	renderPageToGraphics(int pageIndex, java.awt.Graphics2D graphics)	Renders a given page to an AWT Graphics2D instance at 72 DPI.
void	renderPageToGraphics(int pageIndex, java.awt.Graphics2D graphics, float scale)	Renders a given page to an AWT Graphics2D instance.
void	renderPageToGraphics(int pageIndex, java.awt.Graphics2D graphics, float scaleX, float scaleY)	Renders a given page to an AWT Graphics2D instance.
void	renderPageToGraphics(int pageIndex, java.awt.Graphics2D graphics, float scaleX, float scaleY, RenderDestination destination)	Renders a given page to an AWT Graphics2D instance.
void	setAnnotationsFilter(AnnotationFilter annotationsFilter)	Set the AnnotationFilter.
void	setDefaultDestination(RenderDestination defaultDestination)
void	setImageDownscalingOptimizationThreshold(float imageDownscalingOptimizationThreshold)	Set the image downscaling optimization threshold.
void	setRenderingHints(java.awt.RenderingHints renderingHints)	Set the rendering hints.
void	setSubsamplingAllowed(boolean subsamplingAllowed)	Sets a value instructing the renderer whether it is allowed to subsample images before drawing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

document

protected final PDDocument document

Constructor Detail

PDFRenderer

public PDFRenderer(PDDocument document)

Creates a new PDFRenderer.

Parameters:

document - the document to render

Method Detail

getAnnotationsFilter

public AnnotationFilter getAnnotationsFilter()

Return the AnnotationFilter.

Returns:

the AnnotationFilter

setAnnotationsFilter

public void setAnnotationsFilter(AnnotationFilter annotationsFilter)

Set the AnnotationFilter.

Allows to only render annotation accepted by the filter.

Parameters:

annotationsFilter - the AnnotationFilter

isSubsamplingAllowed

public boolean isSubsamplingAllowed()

Value indicating if the renderer is allowed to subsample images before drawing, according to image dimensions and requested scale. Subsampling may be faster and less memory-intensive in some cases, but it may also lead to loss of quality, especially in images with high spatial frequency.

Returns:

true if subsampling of images is allowed, false otherwise.

setSubsamplingAllowed

public void setSubsamplingAllowed(boolean subsamplingAllowed)

Sets a value instructing the renderer whether it is allowed to subsample images before drawing. The subsampling frequency is determined according to image size and requested scale. Subsampling may be faster and less memory-intensive in some cases, but it may also lead to loss of quality, especially in images with high spatial frequency.

Parameters:

subsamplingAllowed - The new value indicating if subsampling is allowed.

getDefaultDestination

public RenderDestination getDefaultDestination()

Returns:

the defaultDestination

setDefaultDestination

public void setDefaultDestination(RenderDestination defaultDestination)

Parameters:

defaultDestination - the defaultDestination to set

getRenderingHints

public java.awt.RenderingHints getRenderingHints()

Get the rendering hints.

Returns:

the rendering hints or null if none are set.

setRenderingHints

public void setRenderingHints(java.awt.RenderingHints renderingHints)

Set the rendering hints. Use this to influence rendering quality and speed. If you don't set them yourself or pass null, PDFBox will decide at runtime depending on the destination.

Parameters:

renderingHints -

getImageDownscalingOptimizationThreshold

public float getImageDownscalingOptimizationThreshold()

Returns:

get the image downscaling optimization threshold. See getImageDownscalingOptimizationThreshold() for details.

setImageDownscalingOptimizationThreshold

public void setImageDownscalingOptimizationThreshold(float imageDownscalingOptimizationThreshold)

Set the image downscaling optimization threshold. This must be a value between 0 and 1. When rendering downscaled images and rendering hints are set to bicubic+quality and the scaling is smaller than the threshold, a more quality-optimized but slower method will be used. The default is 0.5 which is a good compromise.

Parameters:

imageDownscalingOptimizationThreshold -

renderImage

public java.awt.image.BufferedImage renderImage(int pageIndex)
                                         throws java.io.IOException

Returns the given page as an RGB image at 72 DPI

Parameters:

pageIndex - the zero-based index of the page to be converted.

Returns:

the rendered page image

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

renderImage

public java.awt.image.BufferedImage renderImage(int pageIndex,
                                                float scale)
                                         throws java.io.IOException

Returns the given page as an RGB image at the given scale. A scale of 1 will render at 72 DPI.

Parameters:

pageIndex - the zero-based index of the page to be converted

scale - the scaling factor, where 1 = 72 DPI

Returns:

the rendered page image

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

renderImageWithDPI

public java.awt.image.BufferedImage renderImageWithDPI(int pageIndex,
                                                       float dpi)
                                                throws java.io.IOException

Returns the given page as an RGB image at the given DPI.

Parameters:

pageIndex - the zero-based index of the page to be converted

dpi - the DPI (dots per inch) to render at

Returns:

the rendered page image

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

renderImageWithDPI

public java.awt.image.BufferedImage renderImageWithDPI(int pageIndex,
                                                       float dpi,
                                                       ImageType imageType)
                                                throws java.io.IOException

Returns the given page as an RGB image at the given DPI.

Parameters:

pageIndex - the zero-based index of the page to be converted

dpi - the DPI (dots per inch) to render at

imageType - the type of image to return

Returns:

the rendered page image

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

renderImage

public java.awt.image.BufferedImage renderImage(int pageIndex,
                                                float scale,
                                                ImageType imageType)
                                         throws java.io.IOException

Returns the given page as an RGB or ARGB image at the given scale.

Parameters:

pageIndex - the zero-based index of the page to be converted

scale - the scaling factor, where 1 = 72 DPI

imageType - the type of image to return

Returns:

the rendered page image

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

renderImage

public java.awt.image.BufferedImage renderImage(int pageIndex,
                                                float scale,
                                                ImageType imageType,
                                                RenderDestination destination)
                                         throws java.io.IOException

Returns the given page as an RGB or ARGB image at the given scale.

Parameters:

pageIndex - the zero-based index of the page to be converted

scale - the scaling factor, where 1 = 72 DPI

imageType - the type of image to return

destination - controlling visibility of optional content groups

Returns:

the rendered page image

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

renderPageToGraphics

public void renderPageToGraphics(int pageIndex,
                                 java.awt.Graphics2D graphics)
                          throws java.io.IOException

Renders a given page to an AWT Graphics2D instance at 72 DPI.

Read renderPageToGraphics(int, Graphics2D, float, float, RenderDestination) before using this.

Parameters:

pageIndex - the zero-based index of the page to be converted

graphics - the Graphics2D on which to draw the page

Throws:

java.io.IOException - if the PDF cannot be read

renderPageToGraphics

public void renderPageToGraphics(int pageIndex,
                                 java.awt.Graphics2D graphics,
                                 float scale)
                          throws java.io.IOException

Renders a given page to an AWT Graphics2D instance.

Read renderPageToGraphics(int, Graphics2D, float, float, RenderDestination) before using this.

Parameters:

pageIndex - the zero-based index of the page to be converted

graphics - the Graphics2D on which to draw the page

scale - the scaling factor, where 1 = 72 DPI

Throws:

java.io.IOException - if the PDF cannot be read

renderPageToGraphics

public void renderPageToGraphics(int pageIndex,
                                 java.awt.Graphics2D graphics,
                                 float scaleX,
                                 float scaleY)
                          throws java.io.IOException

Renders a given page to an AWT Graphics2D instance.

Read renderPageToGraphics(int, Graphics2D, float, float, RenderDestination) before using this.

Parameters:

pageIndex - the zero-based index of the page to be converted

graphics - the Graphics2D on which to draw the page

scaleX - the scale to draw the page at for the x-axis, where 1 = 72 DPI

scaleY - the scale to draw the page at for the y-axis, where 1 = 72 DPI

Throws:

java.io.IOException - if the PDF cannot be read

renderPageToGraphics

public void renderPageToGraphics(int pageIndex,
                                 java.awt.Graphics2D graphics,
                                 float scaleX,
                                 float scaleY,
                                 RenderDestination destination)
                          throws java.io.IOException

Renders a given page to an AWT Graphics2D instance.

Known problems:

• rendering of PDF files with transparencies is not supported on Ubuntu, see PDFBOX-4581 and JDK-6689349. Rendering will not abort, but the pages will be rendered incorrectly.
• Clipping the Graphics2D will not work properly, see PDFBOX-4583.

If you encounter these problems, then you should render into an image by using the renderImage methods.

Parameters:

pageIndex - the zero-based index of the page to be converted

graphics - the Graphics2D on which to draw the page

scaleX - the scale to draw the page at for the x-axis, where 1 = 72 DPI

scaleY - the scale to draw the page at for the y-axis, where 1 = 72 DPI

destination - controlling visibility of optional content groups

Throws:

java.io.IOException - if the PDF cannot be read

java.lang.IllegalStateException - if the requested index isn't found or doesn't point to a valid page dictionary

java.lang.IndexOutOfBoundsException - if the requested index is higher than the page count

isGroupEnabled

public boolean isGroupEnabled(PDOptionalContentGroup group)

Indicates whether an optional content group is enabled.

Parameters:

group - the group

Returns:

true if the group is enabled

createPageDrawer

protected PageDrawer createPageDrawer(PageDrawerParameters parameters)
                               throws java.io.IOException

Returns a new PageDrawer instance, using the given parameters. May be overridden.

Throws:

java.io.IOException