Welcome to the TerraGo Customer Center

Articles in this section

PubPy User Guide

Avatar
TerraGo Support
  • Updated
Follow

PubPy has a number of methods for creating GeoPDFs, plus a few supporting objects. Here we will explain each, describe their many options, and provide samples of their usage. The section includes a summary of the available methods and objects and provides details about additional PubPy resources.

In this section:

Available Methods and Objects

  • geopdf_export 

    • api 

      • DDP(mxd_path) 

        • exportToGeoPDF(geopdf_path, page_range_type, page_range_string, multiple_files, show_selection_symbology, export_config)

        • getPageIDFromName()

        • refresh()

        • setCurrentPageID()

      • ExportGeoPDFConfig() 

        • archive()

        • dearchive()

      • ExportMXDToGeoPDF(mxd_path, geopdf_path)

      • ExportToGeoPDF(map_document, out_geopdf, {data_frame}, {df_export_width}, {df_export_height}, {resolution}, {image_quality}, {colorspace}, {compress_vectors}, {image_compression}, {picture_symbol}, {convert_markers}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality})

      • ExportToGeoPDFWithConfig(map_document, geopdf_path, config)

      • GeoPDFLayerSchemeHelper() 

        • attach(mxd_path, {source_scheme})

        • save()

        • saveAs(mxd_path, {version})

Export GeoPDF Methods 

ExportMXDToGeoPDF

Export a pre-configured MXD to GeoPDF file format. The export configuration is stored in the MXD.

Usage:

ExportMXDToGeoPDF(mxd_path, geopdf_path)

Parameters:

Name

Type

Description

mxd_path

String

A string that represents the path and filename of the MXD to export.

geopdf_path

String

A string that represents the path and filename of the GeoPDF to create.

ExportToGeoPDF

Exports the page layout or data frame of a map document ( .mxd ) to the Portable Document Format (PDF). This function is, so far as possible, a substitute for arcpy.mapping.ExportToPDF(). Not all ExportToPDF() options are supported.

Usage:

ExportToGeoPDF(map_document, out_geopdf, {data_frame}, {df_export_width}, {df_export_height}, {resolution}, {image_quality}, {colorspace}, {compress_vectors}, {image_compression}, {picture_symbol}, {convert_markers}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality})

Parameters:

Name

Type

Description

map_document

MapDocument

A variable that references a MapDocument object.

out_geopdf

String

A string that represents the path and file name for the output export file.

data_frame

          

Object

A variable that references a DataFrame object. Use the string/constant 'PAGE_LAYOUT' to export the map document's page layout instead of an individual data frame.

df_export_width

           

Integer

Ignored by ExportToGeoPDF(). The PDF page width is determined by the map document page width or calculated from the data frame scale and extent.

df_export_height

Integer

Ignored by ExportToGeoPDF(). The PDF page height is determined by the map document page height or calculated from the data frame scale and extent.

resolution

Integer

A number that defines the resolution of the export file in dots per inch (DPI).

image_quality

String

A string that defines output image quality, the draw resolution of map layers that draw as rasters.

  • '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.

colorspace

String

A string that defines the colorspace of the export file. Valid values are 'CYMK' and 'RGB'.

  • 'CMYK':  Cyan, Magenta,Yellow, and blacK color model.

  • 'RGB':  Red, Green, and Blue color model.

compress_vectors

Boolean

A Boolean that controls compression of vector and text portions of the output file. Image compression is defined separately.

image_compression

String

Ignored by ExportToGeoPDF. Image compression algorithms are chosen automatically on an image-by-image basis based on the image type, similar to ESRI's ADAPTIVE mode.

picture_symbol

String

A string that defines whether picture markers and picture fills will be converted to vector or rasterized on output.

  • 'RASTERIZE_BITMAP':  Rasterize layers with bitmap markers/fills.

  • 'RASTERIZE_PICTURE':  Rasterize layers with any picture marker/fill.

  • 'VECTORIZE_BITMAP':  Vectorize layers with bitmap markers/fills.

convert_markers

Boolean

A Boolean that controls the coversion of character-based marker symbols to polygons. This allows the symbols to appear correctly if the symbol font is not available or cannot be embedded. However, setting this parameter to True disables font embedding for all character-based marker symbols, which can result in a change in their appearance.

embed_fonts

Boolean

A Boolean that controls the embedding of fonts in the export file. Font embedding allows text and character markers to be displayed correctly when the document is viewed on a computer that does not have the necessary fonts installed.

layers_attributes

String

Ignored by ExporToGeoPDF(). Unlike ESRI PDF export, TerraGo GeoPDF layer and attribute export is not global. Individual layers are selected for attribute export and arbitrary layer schemes are supported.

georef_info

Boolean

Ignored by ExportToGeoPDF(). TerraGo GeoPDF exports are always georegistered, with options for different mapframe styles.

jpeg_compression_quality

Integer

A number that controls compression quality value when image_compression is set to 'ADAPTIVE' or ''JPEG'. The valid range is 1 to 100. A jpeg_compression_quality of 100 provides the best quality images but creates large export files. The recommended range is between 70 and 90.

ExportToGeoPDFWithConfig

Exports a MapDocument to GeoPDF, reading export configuration from an ExportGeoPDFConfig object.

Usage:

ExportToGeoPDFWithConfig(map_document, geopdf_path, config)

Parameters:

Name

Type

Description

map_document

MapDocument

The MapDocument to export.

geopdf_path

String

A string that represents the path and filename of the GeoPDF to create.

config

ExportGeoPDFConfig

An ExportGeoPDFConfig object specifying the GeoPDF export options.

Data Driven Pages

Class DDP

DDP is a class to configure and generate data driven pages. You can use it just like the ArcPy class arcpy.mapping.MapDocument.dataDrivenPages. To create an instance of DDP you must pass a path to valid map document (.mxd).

Usage:

class DDP(mxd_path)

Instance variables:

Name

Type

pageRow

String

pageCount

Integer

dataFrame

String

indexLayer

String

selectedPages

List of Numbers

pageNameField

String

DDP.exportToGeoPDF

Exports a specified set of pages to a multipage GeoPDF document for a map document (.mxd) that has Data Driven Pages enabled.

Usage:

DDP.exportToGeoPDF(geopdf_path, page_range_type, page_range_string, multiple_files,show_selection_symbology, export_config)

Parameters:

Name

Type

Description

geopdf_path

String

The path and file name for the output GeoPDF file.

page_range_type

String

Designates how the pages will be printed, similar to the Pages tab within the ArcMap Export Map dialog box for PDF documents.

Supported values:

  • 'ALL': All pages are exported.

  • 'CURRENT': The active page is exported.

  • 'RANGE': Only pages listed in the page_range_string parameter will be exported.

  • 'SELECTED': Only selected index layer features/pages are exported.

page_range_string

String

The pages to be printed if the 'RANGE' option in the page_range_type parameter is used (for example, '1, 3, 5-12' ).

multiple_files

String

An option to control how the output PDF is created.  By default, all pages are exported into a single, multipage document.  You can also specify that individual, single-page PDF documents be exported using two different options.

Supported values:

  • 'PDF_MULTIPLE_FILES_PAGE_NAME': Export  single-page documents using the page name for the output file name.

  • 'PDF_MULTIPLE_FILES_PAGE_INDEX': Export  single-page documents using the page index value for the output file name.

  • 'PDF_SINGLE_FILE': Export a multipage document.

show_selection_symbology

Boolean

Controls whether the selection symbology should be displayed in the output.

export_config

ExportGEoPDFConfig

An ExportGeoPDFConfig object specifying the GeoPDF export options.

DDP.getPageIDFromName

A passthrough method to arcpy.mapping.MapDocument.dataDrivenPages.getPageIDFromName()

Usage:

DDP.getPageIDFromName(page_name)

Parameters:

Name

Type

Description

page_name

String

A value in the index layer that corresponds to the Name field that was used to set up Data Driven Pages.

DDP.refresh

A passthrough method to arcpy.mapping.MapDocument.dataDrivenPages.getPageIDFromName()

Usage:

DDP.refresh()

DDP.setCurrentPageID

Sets the current page from its ID.

Usage:

DDP.setCurrentPageID(page_id)

Parameters:

Name

Type

Description

page_id

Integer

ID of the page to make current.

Advanced Export Configuration

class ExportGeoPDFConfig()

Stores export configuration information for GeoPDF export as instance variables. Instance variables listed below. Many correspond to ExportToPDF() and ExportToGeoPDF() options. These override any options persisted to the document. If an option is set to None here, the option will be read from the document if present. If not persisted in the document, then the preferences file will be read. If there is no preference, the exporter default will be used.

Usage:

class ExportGeoPDFConfig()

Instance variables:

Name

Type

Description

activeView

String

The view to export. 'PAGE_LAYOUT' or the name of a data frame.

Default: 'PAGE_LAYOUT'.

rasterResolution

Integer

Export resolution to use for raster data. 1-32000.

Default: 300.

imageQuality

String

Resampling of raster data. 'BEST', 'BETTER', 'NORMAL', 'FASTER' or 'FASTEST'.

Default: 'BEST'.

jpegQuality

Integer

JPEG image compression quality. 1-100 supported.

Default: 80.

imagePyramids

Boolean

Possibly generate image pyramids in the PDF. Subject to product preferences file settings.

 Default: False.

vectorResolution

Integer

Export resolution to use for vector data. 1-6400.

Default: 6400.

vectorColorspace

String

PDF self.vectorColorspace for vector data. 'RGB' or 'CMYK'.

Default: 'RGB'.

vectorCompressed

Boolean

Compress vector data?

Default: True.

convertMarkers

Boolean

Export markers as fonts or convert to polygons?

Default: False.

embedFonts

Boolean

Embed fonts in the PDF?

Default: True.

pictureSymbolOptions

Boolean

Options for picutre symbols. 'RASTERIZE_BITMAP', 'RASTERIZE_PICTURE' OR 'VECTORIZE_BITMAP'.

Default: 'RASTERIZE_BITMAP'.

optimizeFileSize

Boolean

Compress objects in the PDF. Older versions of Reader do not support these PDFs.

Default: True.

mapframeStyle

String

Style of mapframes to generate. 'OGC_ONLY', 'OGC_PREFERRED', 'ISO_ONLY'.

Default: 'OGC_PREFERRED'.

attributeFormat

String

Format to use for attribute export. 'NONE', 'OBJECT_DATA', or 'GEOPACKAGE'.

Default: 'OBJECT_DATA'.

attributeLayers

List

Layers to receive attributes. A list of layer specifications as tuples. The tuples are of the (map_name, path) where map_name is expected to be a data frame name. If there is only one data frame in a page layout or if a data frame is being exported this can be an empty string. path is a list of path component names describing the path to a layer within the map. An empty string for map_name will match any map name. An empty string for the path will likewise match any path.

Default: [].

hyperlinkedDocuments

String

Disposition of hyperlinked documents. 'NONE', 'ZIP', or 'EMBED'.

Default: 'EMBED'.

hyperlinkLayers

List

Layers to receive hyperlinks. The list is the same format as for attributeLayers.

Default: [].

layers

String

PDF layering to perform. 'NONE', 'DEFAULT_LAYERS', or 'CUSTOM'.

Default: 'DEFAULT_LAYERS'.

layerLabels

Boolean

Separate PDF layers for labels and features.

Default: True.

visibleScaleRange

Boolean

Generate PDF viewer state-controlled layers for ArcGIS visible scale range-controlled layers.

Default: False.

filterLayers

List

Filter layers from the PDF layers. A list, composed of the value below, representing a bitmask.

Default: ['LAYER_OFF','LAYER_OUTOFSCALE','LAYER_INVALID','LAYER_MISSING'].

  • 'LAYER_OFF': ArcMap layer is turned off.

  • 'LAYER_OUTOFSCALE': ArcMap layer visible scale range does not intersect the map scale.

  • 'LAYER_INVALID': ArcMap layer in invalid state.

  • 'LAYER_MISSING': ArcMap layer is missing.

  • 'GRID_OFF': ArcMap grid is turned off.

  • 'GRID_MISSING': ArcMap grid is missing.

  • 'ANNOGROUP_OFF': ArcMap anno group is turned off.

  • 'ANNOGROUP_MISSING': ArcMap anno group is missing.

  • 'ELEM_MISSING': ArcMap element is missing.

  • 'PDFLAYER_EMPTY': PDF layer does not contain content items.

  • 'PDFGROUP_EMPTY': PDF group does not contain PDF layers or groups.

  • 'PDFMENU_EMPTY': PDF menu does not conatin PDF layers, groups or menus.

  • 'PDF_EMPTY': post-process PDF layer scheme, removing empty menus, groups and layers.

GeoPDFLayerSchemeHelper 

class GeoPDFLayerSchemeHelper()

Supports editing a MapDocument's custom GeoPDF layer scheme. GeoPDF layer schemes are a representation of a PDF's Layers pane, which is a tree structure composed of menu, group and layer nodes. Menu nodes are items that can be expanded and collapsed but do not control the visibility of their contents. Group nodes are similar but control the visibility of their contents. Layer nodes only control visibility. Menu nodes can contain menu, group and layer child nodes. Group nodes can contain group and layer child nodes. All node types have names. Only layer nodes contain references to MapDocument content.  

Returns the MapDocument's custom layer scheme as a list of dicts. Each dict is a node at the root of the custom layer scheme. Each dict minimally contains the keys 'type' and 'name'. The 'type' value is one of 'MENU', 'GROUP or 'LAYER'. The remaining keys of the dict differ by type. Menu and group nodes have a 'children' key. The value of this key is a list of dicts in the same format as the root of the custom layer scheme. Group and layer nodes have a 'visible' key. The value of this key is a boolean. Layer nodes have a 'content' key. The value is a list of dicts, each dict describing a content item. Content item dicts have 'type' and 'tag' keys. The type value is either 'SIMPLE' or 'ANNOGROUP'. The tag value is a delimited text string that is unique to each component of the MapDocument. 

The MapDocument's PageLayout represent the document page. The PageLayout's content is a tree structure composed of elements. Most elements are simple, but one type is complex the MapFrame element. One of the subelements of a MapFrame element is a Map. The Map contains layers, which themselves form a tree. Tags represent paths in the PageLayout element tree. The paths are constructed of labels delimited by ':' characters. Because many elements in this tree are often unnamed and duplicate names are possible, labels are generated based component type and position. The elements at the root level are labeled 'elem_0', 'elem_1', and so on. If an element is a group element, its children are labeled 'elem_0', 'elem_1', and so on. Layers in a map follow a similar pattern, 'layer_n'. A full specification is not presented. Dumping the default layer scheme is a viable way of learning the system.

GeoPDFLayerSchemeHelper.attach()

Attach this class instance to a MapDocument and optionally load its custom or default layer scheme into the instance layer scheme.

Usage:

GeoPDFLayerSchemeHelper.attach(mxd_path, {source_scheme})

Parameters:

Name

Type

Description

mxd_path

String

The path of the MXD to attach to.

source_scheme

String

Optional. 'CUSTOM' or 'DEFAULT' if present. The custom layer scheme is user-defined.

It may be empty. The default layer scheme is calculated from the MapDocument.

GeoPDFLayerSchemeHelper.save()

Save the layer scheme to the MXD. This action replaces the document's custom layer scheme with the current layer scheme.

GeoPDFLayerSchemeHelper.saveAs()

Save the layer scheme to a different MXD, optionally specifying the ArcGIS version. The saved document's custom layer scheme will be the current layer scheme.

Usage:

GeoPDFLayerSchemeHelper.saveAs(mxd_path, {version})

Parameters:

Name

Type

Description

mxd_path

String

Path to the MXD.

More Resources

There are currently two sample scripts/tools on our GitHub site:

  1. A command-line utility that creates a GeoPDF given a path to an MXD and an output file name: https://github.com/GeoPDF/pub4server_samples/blob/master/MXD2GeoPDF.py

  2. A geoprocessing service that will take the current state of a web map and generate a GeoPDF: https://github.com/GeoPDF/pub4server_samples/tree/master/WebMap2GeoPDF

Comments

0 comments

Please sign in to leave a comment.