GDAL supports reading Geospatial PDF documents, by extracting georeferencing information and rasterizing the data. Non-geospatial PDF documents will also be recognized by the driver.
Starting with GDAL >= 1.10.0, PDF documents can be created from other GDAL raster datasets, and OGR datasources can also optionally be drawn on top of the raster layer (see OGR_* creation options in the below section).
GDAL must be compiled with libpoppler support (GPL-licensed), and libpoppler itself must have been configured with --enable-xpdf-headers so that the xpdf C++ headers are available. Note: the poppler C++ API isn't stable, so the driver compilation may fail with too old or too recent poppler versions. Successfully tested versions are poppler >= 0.12.X and <= 0.22.0.
Starting with GDAL 1.9.0, as an alternative, the PDF driver can be compiled against libpodofo (LGPL-licensed) to avoid the libpoppler dependency. This is sufficient to get the georeferencing information. However, for getting the imagery, the pdftoppm utility that comes with the poppler distribution must be available in the system PATH. A temporary file will be generated in a directory determined by the following configuration options : CPL_TMPDIR, TMPDIR or TEMP (in that order). If none are defined, the current directory will be used. Successfully tested versions are libpodofo 0.8.4 and 0.9.1.
The driver supports reading georeferencing encoded in either of the 2 current existing ways : according to the OGC encoding best practice, or according to the Adobe Supplement to ISO 32000.
Multipage documents are exposed as subdatasets, one subdataset par page of the document.
The neatline (for OGC best practice) or the bounding box (Adobe style) will be reported as a NEATLINE metadata item, so that it can be later used as a cutline for the warping algorithm.
Starting with GDAL 1.9.0, XMP metadata can be extracted from the file, and will be stored as XML raw content in the xml:XMP metadata domain.
Starting with GDAL 1.10.0, additional metadata, such as found in USGS Topo PDF can be extracted from the file, and will be stored as XML raw content in the EMBEDDED_METADATA metadata domain.
Starting with GDAL >= 1.10.0 and when GDAL is compiled against libpoppler, the following options are also available :
For example :
$ gdalinfo ../autotest/gdrivers/data/adobe_style_geospatial.pdf -mdd LAYERS Driver: PDF/Geospatial PDF Files: ../autotest/gdrivers/data/adobe_style_geospatial.pdf [...] Metadata (LAYERS): LAYER_00_NAME=New_Data_Frame LAYER_01_NAME=New_Data_Frame.Graticule LAYER_02_NAME=Layers LAYER_03_NAME=Layers.Measured_Grid LAYER_04_NAME=Layers.Graticule [...] $ gdal_translate ../autotest/gdrivers/data/adobe_style_geospatial.pdf out.tif --config GDAL_PDF_LAYERS_OFF "New_Data_Frame"
Note: starting with GDAL 1.10, some raster-only PDF files (such as some USGS GeoPDF files), that are regularly tiled are exposed as tiled dataset by the GDAL PDF driver, and can be rendered with either the Poppler or the Podofo backends.
Only a few of the possible Datums available in the OGC best practice spec have been currently mapped in the driver. Unrecognized datums will be considered as being based on the WGS84 ellipsoid.
For documents that contain several neatlines in a page (insets), the georeferencing will be extracted from the inset that has the largest area (in term of screen points).
PDF documents can be created from other GDAL raster datasets, that have 1 band (graylevel or with color table), 3 bands (RGB) or 4 bands (RGBA).
Georeferencing information will be written by default according to the ISO32000 specification. It is also possible to write it according to the OGC Best Practice conventions (but limited to a few datum and projection types).
Note: PDF write support does not require linking to poppler or podofo.
COMPRESS=[NONE/DEFLATE/JPEG/JPEG2000]: Set the compression to use for raster data. DEFLATE is the default.
STREAM_COMPRESS=[NONE/DEFLATE]: Set the compression to use for stream objects. DEFLATE is the default.
DPI=value: Set the DPI to use. Default to 72.
PREDICTOR=[1/2]: Only for DEFLATE compression. Might be set to 2 to use horizontal predictor that can make files smaller (but not always!). 1 is the default.
JPEG_QUALITY=[1-100]: Set the JPEG quality when using JPEG compression. A value of 100 is best quality (least compression), and 1 is worst quality (best compression). The default is 75.
JPEG2000_DRIVER=[JP2KAK/JP2ECW/JP2OpenJPEG/JPEG2000]: Set the JPEG2000 driver to use. If not specified, it will be searched in the previous list.
TILED=YES: By default monoblock files are created. This option can be used to force creation of tiled PDF files.
BLOCKXSIZE=n: Sets tile width, defaults to 256.
BLOCKYSIZE=n: Set tile height, defaults to 256.
CLIPPING_EXTENT=xmin,ymin,xmax,ymax: Set the clipping extent for the main source dataset and for the optional extra rasters. The coordinates are expressed in the units of the SRS of the dataset. If not specified, the clipping extent is set to the extent of the main source dataset.
LAYER_NAME=name: Name for layer where the raster is placed. If specified, the raster will be be placed into a layer that can be toggled/un-toggled in the "Layer tree" of the PDF reader.
EXTRA_RASTERS=dataset_ids: Comma separated list of georeferenced rasters to insert into the page. Those rasters are displayed on top of the main source raster. They must be georeferenced in the same projection, and they will be clipped to CLIPPING_EXTENT if it is specified (otherwise to the extent of the main source raster).
EXTRA_RASTERS_LAYER_NAME=dataset_names: Comma separated list of name for each raster specified in EXTRA_RASTERS. If specified, each extra raster will be be placed into a layer, named with the specified value, that can be toggled/un-toggled in the "Layer tree" of the PDF reader. If not specified, all the extra rasters will be placed in the default layer.
EXTRA_STREAM=content: A PDF content stream to draw after the imagery, typically to add some text. It may refer the /FTimesRoman and /FTimesBold fonts.
EXTRA_IMAGES=image_file_name,x,y,scale[,link=some_url] (possibly repeated): A list of (ungeoreferenced) images to insert into the page as extra content. This is usefull to insert logos, legends, etc... x and y are in user units from the lower left corner of the page, and the anchor point is the lower left pixel of the image. scale is a magnifying ratio (use 1 if unsure). If link=some_url is specified, the image will be selectable and its selection will cause a web browser to be opened on the specified URL.
EXTRA_LAYER_NAME=name: Name for layer where the extra content specified with EXTRA_STREAM or EXTRA_IMAGES is placed. If specified, the extra content will be be placed into a layer that can be toggled/un-toggled in the "Layer tree" of the PDF reader.
MARGIN/LEFT_MARGIN/RIGHT_MARGIN/TOP_MARGIN/BOTTOM_MARGIN=value: Margin around image in user units.
GEO_ENCODING=[NONE/ISO32000/OGC_BP/BOTH]: Set the Geo encoding method to use. ISO32000 is the default.
NEATLINE=polygon_definition_in_wkt: Set the NEATLINE to use.
XMP=[NONE/xml_xmp_content]: By default, if the source dataset has data in the 'xml:XMP' metadata domain, this data will be copied to the output PDF, unless this option is set to NONE. The XMP xml string can also be directly set to this option.
WRITE_INFO=[YES/NO]: By default, the AUTHOR, CREATOR, CREATION_DATE, KEYWORDS, PRODUCER, SUBJECT and TITLE information will be written into the PDF Info block from the corresponding metadata item from the source dataset, or if not set, from the corresponding creation option. If this option is set to NO, no information will be written.
AUTHOR, CREATOR, CREATION_DATE, KEYWORDS, PRODUCER, SUBJECT, TITLE : metadata that can be written into the PDF Info block. Note: the format of the value for CREATION_DATE must be D:YYYYMMDDHHmmSSOHH'mm' (e.g. D:20121122132447+02'00' for 22 nov 2012 13:24:47 GMT+02) (see PDF Reference, version 1.7, page 160)
OGR_DATASOURCE=name : Name of the OGR datasource to display on top of the raster layer.
OGR_DISPLAY_FIELD=name : Name of the field (matching the name of a field from the OGR layer definition) to use to build the label of features that appear in the "Model Tree" UI component of a well-known PDF viewer. For example, if the OGR layer has a field called "ID", this can be used as the value for that option : features in the "Model Tree" will be labelled from their value for the "ID" field. If not specified, sequential generic labels will be used ("feature1", "feature2", etc... ).
OGR_DISPLAY_LAYER_NAMES=names : Comma separated list of names to display for the OGR layers in the "Model Tree". This option is useful to provide custom names, instead of OGR layer name that are used when this option is not specified. When specified, the number of names should be the same as the number of OGR layers in the datasource (and in the order they appear when listed by ogrinfo for example).
OGR_WRITE_ATTRIBUTES=YES/NO : Whether to write attributes of OGR features. Defaults to YES
OGR_LINK_FIELD=name : Name of the field (matching the name of a field from the OGR layer definition) to use to cause clicks on OGR features to open a web browser on the URL specified by the field value.
OFF_LAYERS=names: Comma separated list of layer names that should be initially hidden. By default, all layers are visible. The layer names can come from LAYER_NAME (main raster layer name), EXTRA_RASTERS_LAYER_NAME, EXTRA_LAYER_NAME and OGR_DISPLAY_LAYER_NAMES.
EXCLUSIVE_LAYERS=names: Comma separated list of layer names, such that only one of those layers can be visible at a time. This is the behaviour of radio-buttons in a graphical user interface. he layer names can come from LAYER_NAME (main raster layer name), EXTRA_RASTERS_LAYER_NAME, EXTRA_LAYER_NAME and OGR_DISPLAY_LAYER_NAMES.
JAVASCRIPT=script: Javascript content to run at document opening. See Acrobat(R) JavaScript Scripting Reference.
JAVASCRIPT_FILE=script_filename: Name of Javascript file to embed and run at document opening. See Acrobat(R) JavaScript Scripting Reference.
Updated elements are written at the end of the file, following the incremental update method described in the PDF specification.
gdal_translate -of PDF main_raster.tif my.pdf -co LAYER_NAME=main_raster -co EXTRA_RASTERS=another_raster.tif -co EXTRA_RASTERS_LAYER_NAME=another_raster -co OFF_LAYERS=another_raster -co EXCLUSIVE_LAYERS=main_raster,another_raster
gdal_translate -of PDF my.tif my.pdf -co JAVASCRIPT_FILE=script.jswhere script.js is :
button = app.alert({cMsg: 'This file was generated by GDAL. Do you want to visit its website ?', cTitle: 'Question', nIcon:2, nType:2}); if (button == 4) app.launchURL('http://gdal.org/');
Specifications :
Libraries :
Samples :