PDFFormat

Summary

The PDFFormat object represents a collection of Portable Document Format (PDF) file properties that can be configured and used with the export method on the Layout, MapFrame, MapView, MapSeries, BookmarkMapSeries and Report objects to create an output PDF file.

Discussion

PDF files are designed to be consistently viewable and printable across different platforms. They are commonly used for distributing documents on the web, and the format is now an official ISO standard for document interchange. PDFs are editable in many graphics applications. They can retain map georeference information, annotation, labeling, and feature attribute data in the file. Additionally, the entire document or individual layers can be rasterized to simplify the document and decrease file size.

The createExportFormat method can be used to create a PDFFormat object if the format parameter is set to PDF. The returned PDFFormat object contains all the properties associated with a generating a PDF file. These properties can be modified accordingly to produce different output results.

Properties

Name	Explanation	Data type
author (Read and Write)	A string that represents the author of the document.	String
clipToElements (Read and Write)	If set to `True`, include the areas of the page that have map or layout element content only, rather than exporting the entire page. This property only applies when exporting a `Layout` object. The default value is `False`.	Boolean
compressVectorGraphics (Read and Write)	Compress the vector content streams. This option should be kept `True` unless you need clear text for troubleshooting. The default value is `True`.	Boolean
convertMarkers (Read and Write)	Controls whether marker symbols based on font characters are exported as font characters or as polygons. Set this option to `True` to view the output on a machine that does not have the appropriate fonts installed when you cannot embed the fonts due to licensing or file format restrictions. This does not apply to text, only marker symbols based on fonts. The default value is `False`.	Boolean
embedColorProfile (Read and Write)	Include the color profile set for the map or layout in the exported file. This helps create consistency in colors when the file is viewed on different devices. If the profile is not embedded, or a non-color-managed viewer is used, the colors may be significantly different than what is seen on-screen. The default value is `True`. Note: This option is only available when color management is enabled. If color management is not enabled and the colorspace is set to CMYK, the CMYK colorspace is still included in the export. This may cause some colors to appear differently when viewing the exported file.	Boolean
embedFonts (Read and Write)	Include embeddable fonts in the exported file to maintain font consistency across different platforms. Fonts that do not support embedding are not included, regardless of this setting. The default value is `True`. Note: To correctly edit text as graphics, Illustrator requires fonts to be installed and accessible. Check the sharing permissions before embedding and sharing fonts. For high-range characters or ligatures, font embedding should be used to ensure proper addressing of these high-range characters. In the case where a font with high-range characters or ligatures cannot be embedded, check the Draw glyphs as geometry property on the text symbol.	Boolean
filePath (Read and Write)	A string that represents the system path and file name, including the extension, for the exported file.	String
georefInfo (Read and Write)	Include geospatial information from the map or one or more map frames. If this information is included, you can extract x,y coordinate data and perform geographic measurements in supported PDF readers. The default value is `True`.	Boolean
height (Read and Write)	The height, in pixels, of the map area to be exported. This property only applies when exporting a `MapView` object. The default value is `960`.	Double
imageCompression (Read and Write)	The compression scheme used to compress image or raster data in the output file. Choose from the following options below. The default value is `ADAPTIVE`. ADAPTIVE—JPEG and Deflate compression are combined, depending on the contents of the stream. This works well for most cases. DEFLATE—Lossless compression method that works well for most cases. JPEG—Lossy compression method that works well for photographic-type images. JPEG2000—Higher quality compression with file sizes smaller than JPEG. This compression is lossless if `jpeg_compression_quality` is set to 100. LZW—Lossless compression method using a code table. NONE—Compression is not applied. RLE—Run-length encoded compression, a lossless compression method that works well if there are large areas of the same color.	String
imageCompressionQuality (Read and Write)	The amount of image compression applied to the export. Low quality has a smaller file size but less clear data; max quality has a larger file size but crisper data. This only applies when certain compression types are used. The default value is `80`.	Integer
imageQuality (Read and Write)	The amount of image resampling. The property determines the effective resolution of raster content on output. For instance, if `imageQuality` is set to `BETTER`, a resample ratio of `1:2`, and the output `resolution` is set to 300 dpi, the raster content is output at approximately `150` dpi. In many cases, the raster data can be included at a lower dpi than the vector data without visibly affecting quality, reducing the output file size. The default value is `BEST`. BEST—An output image quality resample ratio of 1 BETTER—An output image quality resample ratio of 2 NORMAL—An output image quality resample ratio of 3 FASTER—An output image quality resample ratio of 4 FASTEST—An output image quality resample ratio of 5	String
includeAccessibilityTags (Read and Write)	Output a tagged PDF file where text can be read by screen readers or other assistive technology. A tagged PDF file can include alt text—a text description of a graphic element that a screen reader uses to describe the element—for map frames, pictures, and chart frames. Alt text is added in the Element Pane for each element. The default value is `True`.	Boolean
includeNonVisibleMapLayers (Read and Write)	If set to `True`, this property ensures that all layers in the map are included in the exported file, including layers with visibility unchecked. The visibility status of all layers is retained in the exported file. Use this option to create deliverables with several views of the same data. When this property is set to `False`, only visible layers in the map are included in the exported file. Non-visible layers are dropped. The default value is `False`.	Boolean
keywords (Read and Write)	A string that represents keywords that can assist in document searches.	String
languageCode (Read and Write)	A string that represents a standardized country code abbreviation (ISO3166) and a language code abbreviation (ISO639). For example, `en-us`. The `pdf_language_code` sets the language of the text in the document so a screen reader can interpret it correctly.	String
layersAndAttributes (Read and Write)	Include layers in the map or layout that can be viewed and managed in supported PDF readers. Additionally, you can include the attribute data from the features. Including attributes for a large number of layers can affect performance and increase the size of the output. The default value is `LAYERS_ONLY` LAYERS_AND_ATTRIBUTES—Export PDF layers and feature attributes LAYERS_ONLY—Export PDF layers only NONE—Do not export any PDF information Note: Feature attributes will not be available if `includeAccessibilityTags` is set to `True`.	String
outputAsImage (Read and Write)	Export vector content as an image. For maps or layouts containing vector layers with a high density of vertices, this can drastically reduce the output file size. The default value is `False`. Note: Options specific to vector data, such as `embedFonts`, `georefInfo` and `layersAttributes`, are unavailable when `outputAsImage` is set to `True`.	Boolean
rasterAsSingleTile (Read and Write)	If set to `True`, export raster and rasterized layers as a single tile image to avoid artifacts in transparent layers in some PDF viewers. The default value is `False`. Note: If sufficient memory cannot be allocated, the export process will fail. To reduce memory requirements, set `rasterAsSingleTile` to `False`, and instead, try reducing the `imageQuality`, `resolution`, or set the `antialiasing` value to `None`. The `antialiasing` value is set on the `DisplayOptions` class when running scripts outside of the application, or on the Display tab in the Project options, if running scripts within the application.	Boolean
removeLayoutBackground (Read and Write)	Remove the page background as a graphic when exporting. This property only applies when exporting a `Layout` object. The default value is `False`.	Boolean
resolution (Read and Write)	The effective dpi of the output vector data. The default value is 96. Note: When exporting a `MapView`, the dpi is calculated automatically using system dpi scaling and therefore this value will be ignored.	Integer
showSelectionSymbology (Read and Write)	Show selected features in the map or map frame as selected in the output file. Setting this value to `False` does not affect selection within the view, only in the output file. The default value is `False`.	Boolean
simulateOverprint (Read and Write)	Sometimes called soft proofing, simulate overprint shows a representation of how overlapping areas of ink will appear when printed on a page. You set up overprinting on the symbol layers of symbols or graphics. It is only applies if the color model is set to CMYK. The default value is `False`. Note: When you simulate overprint on export, vector features are rasterized into images. They are not maintained as individual vector layers in the output PDF document. This results in options specific to vector data, such as `embedFonts`, `georefInfo`, and `layersAttributes`, being unavailable. Learn more about overprinting. As a result, when `simulateOverprint` is set to `True`, it will ignore the `outputAsImage` value even if set to `False`.	Boolean
subject (Read and Write)	A string that represents a brief overview of what the document is about.	String
title (Read and Write)	A string that represents the document title. This will be displayed when the document is opened.	String
width (Read and Write)	The width, in pixels, of the map area to be exported. This property only applies when exporting a `MapView` object. The default value is `960`.	Double

Methods

`setImageCompression(image_compression)`

A string constant that represents the compression scheme used to compress image or raster data in the output file.

Name Explanation Data type

Name	Explanation	Data type
image_compression	Below is a list of valid strings. ADAPTIVE—JPEG and Deflate compression are combined, depending on the contents of the stream. This works well for most cases. DEFLATE—Lossless compression method that works well for most cases. JPEG—Lossy compression method that works well for photographic-type images. JPEG2000—Higher-quality compression with file sizes smaller than JPEG . This compression is lossless if `imageQuality` is set to 100. LZW—Lempel-Ziv-Welch, a lossless compression method using a code table. NONE—Compression is not applied. RLE—Run-length encoded compression, a lossless compression method that works well if there are large areas of the same color.	String

image_compression

Below is a list of valid strings.

ADAPTIVE—JPEG and Deflate compression are combined, depending on the contents of the stream. This works well for most cases.
DEFLATE—Lossless compression method that works well for most cases.
JPEG—Lossy compression method that works well for photographic-type images.
JPEG2000—Higher-quality compression with file sizes smaller than JPEG . This compression is lossless if imageQuality is set to 100.
LZW—Lempel-Ziv-Welch, a lossless compression method using a code table.
NONE—Compression is not applied.
RLE—Run-length encoded compression, a lossless compression method that works well if there are large areas of the same color.

String

`setImageQuality(image_quality)`

A string constant that sets the amount of image resampling.

The value determines the effective resolution of raster content on output. For instance, if the output image quality ratio is set to 1:2, an image_quality value of BETTER, and the output resolution is set to 300 dpi, the raster content is output at approximately 150 dpi. In many cases, the raster data can be included at a lower dpi than the vector data without visibly affecting quality, reducing the output file size.

Name	Explanation	Data type
image_quality	Below is a list of valid strings. BEST—An output image quality resample ratio of 1 BETTER—An output image quality resample ratio of 2 NORMAL—An output image quality resample ratio of 3 FASTER—An output image quality resample ratio of 4 FASTEST—An output image quality resample ratio of 5	String

Name

Explanation

Data type

image_quality

Below is a list of valid strings.

BEST—An output image quality resample ratio of 1
BETTER—An output image quality resample ratio of 2
NORMAL—An output image quality resample ratio of 3
FASTER—An output image quality resample ratio of 4
FASTEST—An output image quality resample ratio of 5

String

`setLayersAndAttributes(layers_attributes)`

A string constant that specifies whether the PDF layer and PDF object data (attributes) will be included in the export file.

The output file size can get large depending on the number of features and density of vertices when using a value of LAYERS_ONLY and can get even larger if LAYERS_AND_ATTRIBUTES are exported.

Note:

Feature attributes will not be available if includeAccessibilityTags is set to True.

Name	Explanation	Data type
layers_attributes	Below is a list of valid strings. LAYERS_AND_ATTRIBUTES—Export PDF layers and feature attributes LAYERS_ONLY—Export PDF layers only NONE—Do not export any PDF information	String

Name

Explanation

Data type

layers_attributes

Below is a list of valid strings.

LAYERS_AND_ATTRIBUTES—Export PDF layers and feature attributes
LAYERS_ONLY—Export PDF layers only
NONE—Do not export any PDF information

String

Code sample

PDFFormat example 1

The following script exports a layout to PDF format using default property values.

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts()[0]

pdf = arcpy.mp.CreateExportFormat('PDF', r'C:\Temp\Output.pdf')

lyt.export(pdf)

PDFFormat example 2

The following script does the same export as the example above but then it configures the PDFFormat properties to create a PDF with a smaller file size. Before the script exports a second time, it modifies the original output filePath so you can compare the file sizes of the newly generated PDFs.

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts()[0]

pdf = arcpy.mp.CreateExportFormat('PDF', r'C:\Temp\PDF_output1.pdf')
lyt.export(pdf)                            #Export using default value

pdf.clipToElements = True                  #Default is False
pdf.embedColorProfile = False              #Default is True
pdf.embedFonts = False                     #Default is True
pdf.georefInfo = False                     #Default is True
pdf.outputAsImage = True                   #Default is False
pdf.imageCompressionQuality = 10           #Default is 80
pdf.resolution = 50                        #Default is 96
pdf.setImageQuality('FASTEST')             #Default os BEST
pdf.setLayersAndAttributes('NONE')         #Default is LAYERS_ONLY
pdf.filePath = r'C:\Temp\PDF_output2.pdf'  #Override filePath from original

lyt.export(pdf)                            #Export to smaller PDF