Class: QgsLayoutExporter

Handles rendering and exports of layouts to various formats.

Methods

computeWorldFileParameters	Compute world file parameters.
errorFile	Returns the file name corresponding to the last error encountered during an export.
errorMessage	Returns a string describing the last error encountered during an export.
exportToImage	Exports the layout to the filePath, using the specified export settings.
exportToPdf	Exports the layout as a PDF to the filePath, using the specified export settings.
exportToSvg	Exports the layout as an SVG to the filePath, using the specified export settings.
georeferenceOutput	Georeferences a file (image of PDF) exported from the layout.
labelingResults	Returns the labeling results for all map items included in the export.
layout	Returns the layout linked to this exporter.
print	Prints the layout to a printer, using the specified export settings.
renderPage	Renders a full page to a destination painter.
renderPageToImage	Renders a full page to an image.
renderRegion	Renders a region from the layout to a painter.
renderRegionToImage	Renders a region of the layout to an image.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsLayoutExporter. See the FAQ for more details.

generateFileName

Generates the file name for a page during export.

Static Methods

containsAdvancedEffects	Returns True if the specified layout contains visible items which have settings such as opacity which will prevent these individual items from being exported as vector artwork.
exportToPdfs	Exports a layout iterator to multiple PDF files, with the specified export settings.
requiresRasterization	Returns True if the specified layout contains visible items which have settings that require rasterization of the entire export layout in order to reproduce the desired appearance.

Attributes

Canceled
FileError
IteratorError
MemoryError
PrintError
Success
SvgLayerError

class qgis.core.QgsLayoutExporter

Bases: object

__init__(layout: QgsLayout | None)

Constructor for QgsLayoutExporter, for the specified layout.

Parameters:

layout (Optional[QgsLayout])

__init__(a0: QgsLayoutExporter)

Parameters:

a0 (QgsLayoutExporter)

Canceled = 1

class ExportResult

Bases: int

FileError = 3

class ImageExportSettings

Bases: object

Contains settings relating to exporting layouts to raster images

cropMargins: QgsMargins

Crop to content margins, in pixels. These margins will be added to the bounds of the exported layout if cropToContents is True.

cropToContents: bool

Set to True if image should be cropped so only parts of the layout containing items are exported.

dpi: float

Resolution to export layout at. If dpi <= 0 the default layout dpi will be used.

exportMetadata: bool

Indicates whether image export should include metadata generated from the layout’s project’s metadata.

Added in version 3.2.

flags: Qgis.LayoutRenderFlags

Layout context flags, which control how the export will be created.

generateWorldFile: bool

Set to True to generate an external world file alongside exported images.

imageSize: QSize

Manual size in pixels for output image. If imageSize is not set then it will be automatically calculated based on the output dpi and layout size.

If cropToContents is True then imageSize has no effect.

Be careful when specifying manual sizes if pages in the layout have differing sizes! It’s likely not going to give a reasonable output in this case, and the automatic dpi-based image size should be used instead.

pages: List[int]

List of specific pages to export, or an empty list to export all pages.

Page numbers are 0 index based, so the first page in the layout corresponds to page 0.

predefinedMapScales: List[float]

A list of predefined scales to use with the layout. This is used for maps which are set to the predefined atlas scaling mode.

Added in version 3.10.

quality: int

Image quality, typically used for JPEG compression (whose quality ranges from 1 to 100) if quality is set to -1, the default quality will be used.

Added in version 3.42.

IteratorError = 6

MemoryError = 2

class PageExportDetails

Bases: object

Contains details of a page being exported by the class

baseName: str

Base part of filename (i.e. file name without extension or ‘.’)

directory: str

Target folder

extension: str

File suffix/extension (without the leading ‘.’)

page: int

Page number, where 0 = first page.

class PdfExportSettings

Bases: object

Contains settings relating to exporting layouts to PDF

appendGeoreference: bool

Indicates whether PDF export should append georeference data

Added in version 3.10.

dpi: float

Resolution to export layout at. If dpi <= 0 the default layout dpi will be used.

exportLayersAsSeperateFiles: bool

True if individual layers from the layout should be rendered to separate PDF files.

This option allows for separation of logic layout layers to individual PDF files. For instance, if this option is True, then a separate PDF file will be created per layer per map item in the layout. Additionally, separate PDF files may be created for other complex layout items, resulting in a set of PDF files which contain logical atomic components of the layout.

This option is designed to allow the PDF files to be composited back together in an external application (e.g. Adobe Illustrator) as a non-QGIS, post-production step.

Added in version 3.14.

exportMetadata: bool

Indicates whether PDF export should include metadata generated from the layout’s project’s metadata.

Added in version 3.2.

exportThemes: List[str]

Optional list of map themes to export as Geospatial PDF layer groups.

If set, map item’s which are not assigned a specific map theme will iterate through all listed themes and a Geospatial PDF layer group will be created for each.

If PdfExportSettings.writeGeoPdf is False than this option has no effect.

flags: Qgis.LayoutRenderFlags

Layout context flags, which control how the export will be created.

forceVectorOutput: bool

Set to True to force vector object exports, even when the resultant appearance will differ from the layout. If False, some items may be rasterized in order to maintain their correct appearance in the output.

This option is mutually exclusive with rasterizeWholeImage.

includeGeoPdfFeatures: bool

True if feature vector information (such as attributes) should be exported during Geospatial PDF exports.

If PdfExportSettings.writeGeoPdf is False than this option has no effect.

predefinedMapScales: List[float]

A list of predefined scales to use with the layout. This is used for maps which are set to the predefined atlas scaling mode.

Added in version 3.10.

rasterizeWholeImage: bool

Set to True to force whole layout to be rasterized while exporting.

This option is mutually exclusive with forceVectorOutput.

simplifyGeometries: bool

Indicates whether vector geometries should be simplified to avoid redundant extraneous detail, such as vertices which are not visible at the specified dpi of the output.

Added in version 3.10.

textRenderFormat: Qgis.TextRenderFormat

Text rendering format, which controls how text should be rendered in the export (e.g. as paths or real text objects).

Added in version 3.4.3.

useIso32000ExtensionFormatGeoreferencing: bool

True if ISO3200 extension format georeferencing should be used.

This is a recommended setting which results in Geospatial PDF files compatible with the built-in Acrobat geospatial tools.

If PdfExportSettings.writeGeoPdf is False than this option has no effect.

useOgcBestPracticeFormatGeoreferencing: bool

True if OGC “best practice” format georeferencing should be used.

Warning

This results in geospatial PDF files compatible with a unnamed suite of tools starting with Terra and ending with Go, but can break compatibility with the built-in Acrobat geospatial tools (yes, Geospatial PDF format is a mess!).

If PdfExportSettings.writeGeoPdf is False than this option has no effect.

Deprecated since version 3.42: This parameter has no longer any effect. Only ISO 32000 georeferencing is handled.

writeGeoPdf: bool

True if geospatial PDF files should be created, instead of normal PDF files.

Whilst geospatial PDF files can include some desirable properties like the ability to interactively query map features, they also can result in lower-quality output files, or forced rasterization of layers.

Note

Requires builds based on GDAL 3.0 or greater.

Added in version 3.10.

PrintError = 4

class PrintExportSettings

Bases: object

Contains settings relating to printing layouts

dpi: float

Resolution to export layout at. If dpi <= 0 the default layout dpi will be used.

flags: Qgis.LayoutRenderFlags

Layout context flags, which control how the export will be created.

predefinedMapScales: List[float]

A list of predefined scales to use with the layout. This is used for maps which are set to the predefined atlas scaling mode.

Added in version 3.10.

rasterizeWholeImage: bool

Set to True to force whole layout to be rasterized while exporting.

This option is mutually exclusive with forceVectorOutput.

Success = 0

class SvgExportSettings

Bases: object

Contains settings relating to exporting layouts to SVG

cropMargins: QgsMargins

Crop to content margins, in layout units. These margins will be added to the bounds of the exported layout if cropToContents is True.

cropToContents: bool

Set to True if image should be cropped so only parts of the layout containing items are exported.

dpi: float

Resolution to export layout at. If dpi <= 0 the default layout dpi will be used.

exportAsLayers: bool

Set to True to export as a layered SVG file. Note that this option is considered experimental, and the generated SVG may differ from the expected appearance of the layout.

exportLabelsToSeparateLayers: bool

Set to True to export labels to separate layers (grouped by map layer) in layered SVG exports.

This option is only used if exportAsLayers is True.

Added in version 3.10.

exportMetadata: bool

Indicates whether SVG export should include RDF metadata generated from the layout’s project’s metadata.

Added in version 3.2.

flags: Qgis.LayoutRenderFlags

Layout context flags, which control how the export will be created.

forceVectorOutput: bool

Set to True to force vector object exports, even when the resultant appearance will differ from the layout. If False, some items may be rasterized in order to maintain their correct appearance in the output.

This option is mutually exclusive with rasterizeWholeImage.

predefinedMapScales: List[float]

A list of predefined scales to use with the layout. This is used for maps which are set to the predefined atlas scaling mode.

Added in version 3.10.

simplifyGeometries: bool

Indicates whether vector geometries should be simplified to avoid redundant extraneous detail, such as vertices which are not visible at the specified dpi of the output.

Added in version 3.10.

textRenderFormat: Qgis.TextRenderFormat

Text rendering format, which controls how text should be rendered in the export (e.g. as paths or real text objects).

Added in version 3.4.3.

SvgLayerError = 5

computeWorldFileParameters(self, dpi: float = -1)

Compute world file parameters. Assumes the whole page containing the reference map item will be exported.

The dpi argument can be set to the actual DPI of exported file, or left as -1 to use the layout’s default DPI.

Parameters:

dpi (float = -1) -> (float)

computeWorldFileParameters(self, region: QRectF, dpi: float = -1)

Computes the world file parameters for a specified region of the layout.

The dpi argument can be set to the actual DPI of exported file, or left as -1 to use the layout’s default DPI.

Parameters:

• region (QRectF)

• dpi (float = -1) -> (float)

static containsAdvancedEffects(layout: QgsLayout | None) → bool

Returns True if the specified layout contains visible items which have settings such as opacity which will prevent these individual items from being exported as vector artwork.

See also

requiresRasterization()

Added in version 3.20.

Parameters:

layout (Optional[QgsLayout])

Return type:

bool

errorFile(self) → str

Returns the file name corresponding to the last error encountered during an export.

Return type:

str

errorMessage(self) → str

Returns a string describing the last error encountered during an export.

Added in version 3.38.

Return type:

str

exportToImage(self, filePath: str | None, settings: QgsLayoutExporter.ImageExportSettings) → QgsLayoutExporter.ExportResult

Exports the layout to the filePath, using the specified export settings.

If the layout is a multi-page layout, then filenames for each page will automatically be generated by appending “_1”, “_2”, etc to the image file’s base name.

Returns a result code indicating whether the export was successful or an error was encountered. If an error code is returned, errorFile() can be called to determine the filename for the export which encountered the error.

Parameters:

• filePath (Optional[str])

• settings (QgsLayoutExporter.ImageExportSettings)

Return type:

QgsLayoutExporter.ExportResult

exportToImage(iterator: QgsAbstractLayoutIterator | None, baseFilePath: str | None, extension: str | None, settings: QgsLayoutExporter.ImageExportSettings, feedback: QgsFeedback | None = None)

Exports a layout iterator to raster images, with the specified export settings.

The baseFilePath argument gives a base file path, which is modified by the iterator to obtain file paths for each iterator feature.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

Parameters:

• iterator (Optional[QgsAbstractLayoutIterator])

• baseFilePath (Optional[str])

• extension (Optional[str])

• settings (QgsLayoutExporter.ImageExportSettings)

• feedback (Optional[QgsFeedback] = None) -> (QgsLayoutExporter.ExportResult)

exportToPdf(self, filePath: str | None, settings: QgsLayoutExporter.PdfExportSettings) → QgsLayoutExporter.ExportResult

Exports the layout as a PDF to the filePath, using the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered.

Parameters:

• filePath (Optional[str])

• settings (QgsLayoutExporter.PdfExportSettings)

Return type:

QgsLayoutExporter.ExportResult

exportToPdf(iterator: QgsAbstractLayoutIterator | None, fileName: str | None, settings: QgsLayoutExporter.PdfExportSettings, feedback: QgsFeedback | None = None)

Exports a layout iterator to a single PDF file, with the specified export settings.

The fileName argument gives the destination file name for the output PDF.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

See also

exportToPdfs()

Parameters:

• iterator (Optional[QgsAbstractLayoutIterator])

• fileName (Optional[str])

• settings (QgsLayoutExporter.PdfExportSettings)

• feedback (Optional[QgsFeedback] = None) -> (QgsLayoutExporter.ExportResult)

static exportToPdfs(iterator: QgsAbstractLayoutIterator | None, baseFilePath: str | None, settings: QgsLayoutExporter.PdfExportSettings, feedback: QgsFeedback | None = None)

Exports a layout iterator to multiple PDF files, with the specified export settings.

The baseFilePath argument gives a base file path, which is modified by the iterator to obtain file paths for each iterator feature.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

See also

exportToPdf()

Parameters:

• iterator (Optional[QgsAbstractLayoutIterator])

• baseFilePath (Optional[str])

• settings (QgsLayoutExporter.PdfExportSettings)

• feedback (Optional[QgsFeedback] = None) -> (QgsLayoutExporter.ExportResult)

exportToSvg(self, filePath: str | None, settings: QgsLayoutExporter.SvgExportSettings) → QgsLayoutExporter.ExportResult

Exports the layout as an SVG to the filePath, using the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered.

Parameters:

• filePath (Optional[str])

• settings (QgsLayoutExporter.SvgExportSettings)

Return type:

QgsLayoutExporter.ExportResult

exportToSvg(iterator: QgsAbstractLayoutIterator | None, baseFilePath: str | None, settings: QgsLayoutExporter.SvgExportSettings, feedback: QgsFeedback | None = None)

Exports a layout iterator to SVG files, with the specified export settings.

The baseFilePath argument gives a base file path, which is modified by the iterator to obtain file paths for each iterator feature.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

Parameters:

• iterator (Optional[QgsAbstractLayoutIterator])

• baseFilePath (Optional[str])

• settings (QgsLayoutExporter.SvgExportSettings)

• feedback (Optional[QgsFeedback] = None) -> (QgsLayoutExporter.ExportResult)

virtual generateFileName(self, details: QgsLayoutExporter.PageExportDetails) → str

Generates the file name for a page during export.

Subclasses can override this method to customize page file naming.

Parameters:

details (QgsLayoutExporter.PageExportDetails)

Return type:

str

georeferenceOutput(self, file: str | None, referenceMap: QgsLayoutItemMap | None = None, exportRegion: QRectF = QRectF(), dpi: float = -1) → bool

Georeferences a file (image of PDF) exported from the layout.

The referenceMap argument specifies a map item to use for georeferencing. If left as None, the default layout QgsLayout.referenceMap() will be used.

The exportRegion argument can be set to a valid rectangle to indicate that only part of the layout was exported.

Similarly, the dpi can be set to the actual DPI of exported file, or left as -1 to use the layout’s default DPI.

The function will return True if the output was successfully georeferenced.

See also

computeWorldFileParameters()

Parameters:

• file (Optional[str])

• referenceMap (Optional[QgsLayoutItemMap] = None)

• exportRegion (QRectF = QRectF())

• dpi (float = -1)

Return type:

bool

labelingResults(self) → Any

Returns the labeling results for all map items included in the export. Map keys are the item UUIDs (see QgsLayoutItem.uuid()).

Ownership of the results remains with the layout exporter.

Added in version 3.20.

Return type:

Any

layout(self) → QgsLayout | None

Returns the layout linked to this exporter.

Return type:

Optional[QgsLayout]

print(self, printer: QPrinter, settings: QgsLayoutExporter.PrintExportSettings) → QgsLayoutExporter.ExportResult

Prints the layout to a printer, using the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered.

Parameters:

• printer (QPrinter)

• settings (QgsLayoutExporter.PrintExportSettings)

Return type:

QgsLayoutExporter.ExportResult

print(iterator: QgsAbstractLayoutIterator | None, printer: QPrinter, settings: QgsLayoutExporter.PrintExportSettings, feedback: QgsFeedback | None = None)

Exports a layout iterator to a printer, with the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

Parameters:

• iterator (Optional[QgsAbstractLayoutIterator])

• printer (QPrinter)

• settings (QgsLayoutExporter.PrintExportSettings)

• feedback (Optional[QgsFeedback] = None) -> (QgsLayoutExporter.ExportResult)

renderPage(self, painter: QPainter | None, page: int)

Renders a full page to a destination painter.

The page argument specifies the page number to render. Page numbers are 0 based, such that the first page in a layout is page 0.

See also

renderRegion()

Parameters:

• painter (Optional[QPainter])

• page (int)

renderPageToImage(self, page: int, imageSize: QSize = QSize(), dpi: float = -1) → QImage

Renders a full page to an image.

The page argument specifies the page number to render. Page numbers are 0 based, such that the first page in a layout is page 0.

The optional imageSize parameter can specify the target image size, in pixels. It is the caller’s responsibility to ensure that the ratio of the target image size matches the ratio of the corresponding layout page size.

The dpi parameter is an optional dpi override. Set to -1 to use the default layout print resolution. This parameter has no effect if imageSize is specified.

Returns the rendered image, or a null QImage if the image does not fit into available memory.

See also

renderPage()

See also

renderRegionToImage()

Parameters:

• page (int)

• imageSize (QSize = QSize())

• dpi (float = -1)

Return type:

QImage

renderRegion(self, painter: QPainter | None, region: QRectF)

Renders a region from the layout to a painter. This method can be used to render sections of pages rather than full pages.

See also

renderPage()

See also

renderRegionToImage()

Parameters:

• painter (Optional[QPainter])

• region (QRectF)

renderRegionToImage(self, region: QRectF, imageSize: QSize = QSize(), dpi: float = -1) → QImage

Renders a region of the layout to an image. This method can be used to render sections of pages rather than full pages.

The optional imageSize parameter can specify the target image size, in pixels. It is the caller’s responsibility to ensure that the ratio of the target image size matches the ratio of the specified region of the layout.

The dpi parameter is an optional dpi override. Set to -1 to use the default layout print resolution. This parameter has no effect if imageSize is specified.

Returns the rendered image, or a null QImage if the image does not fit into available memory.

See also

renderRegion()

See also

renderPageToImage()

Parameters:

• region (QRectF)

• imageSize (QSize = QSize())

• dpi (float = -1)

Return type:

QImage

static requiresRasterization(layout: QgsLayout | None) → bool

Returns True if the specified layout contains visible items which have settings that require rasterization of the entire export layout in order to reproduce the desired appearance.

See also

containsAdvancedEffects()

Added in version 3.20.

Parameters:

layout (Optional[QgsLayout])

Return type:

bool