Class: QgsLayoutAtlas

Used to render QgsLayout as an atlas, by iterating over the features from an associated vector layer.

QgsLayoutAtlas implement the QgsAbstractLayoutIterator interface, allowing them to be used directly with QgsLayoutExporter to automatically output all pages from the atlas.

For QgsPrintLayout layouts, it is not necessary to manually construct a QgsLayoutAtlas object. Instead, the atlas attached to the print layout should be used. This can be retrieved by calling QgsPrintLayout.atlas().

Class Hierarchy

Inheritance diagram of qgis.core.QgsLayoutAtlas

Base classes

QObject

QgsAbstractLayoutIterator

An abstract base class for QgsLayout based classes which can be exported by QgsLayoutExporter.

QgsLayoutSerializableObject

An interface for layout objects which can be stored and read from DOM elements.

QgsLayoutUndoObjectInterface

Interface for layout objects which support undo/redo commands.

QgsExpressionContextGenerator

Abstract interface for generating an expression context.

Methods

coverageLayer

Returns the coverage layer used for the atlas features.

currentFeatureNumber

Returns the current feature number, where a value of 0 corresponds to the first feature.

currentFilename

Returns the current feature filename.

enabled

Returns whether the atlas generation is enabled

filenameExpression

Returns the filename expression used for generating output filenames for each atlas page.

filterExpression

Returns the expression used for filtering features in the coverage layer.

filterFeatures

Returns True if features should be filtered in the coverage layer.

first

Seeks to the first feature, returning False if no feature was found.

hideCoverage

Returns True if the atlas is set to hide the coverage layer.

last

Seeks to the last feature, returning False if no feature was found.

limitCoverageLayerRenderToCurrentFeature

Returns True if the atlas is set to limit rendering on the coverage layer to the current feature.

nameForPage

Returns the calculated name for a specified atlas page number.

pageNameExpression

Returns the expression (or field name) used for calculating the page name.

previous

Iterates to the previous feature, returning False if no previous feature exists.

refreshCurrentFeature

Refreshes the current atlas feature, by refetching its attributes from the vector layer provider

seekTo

Seeks to the specified feature number.

setCoverageLayer

Sets the coverage layer to use for the atlas features.

setEnabled

Sets whether the atlas is enabled.

setFilenameExpression

Sets the filename expression used for generating output filenames for each atlas page.

setFilterExpression

Sets the expression used for filtering features in the coverage layer.

setFilterFeatures

Sets whether features should be filtered in the coverage layer.

setHideCoverage

Sets whether the coverage layer should be hidden in map items in the layouts.

setLimitCoverageLayerRenderToCurrentFeature

Sets whether the rendering of the coverage layer should be limited to the current feature.

setPageNameExpression

Sets the expression (or field name) used for calculating the page name.

setSortAscending

Sets whether features should be sorted in an ascending order.

setSortExpression

Sets the expression (or field name) to use for sorting features.

setSortFeatures

Sets whether features should be sorted in the atlas.

sortAscending

Returns True if features should be sorted in an ascending order.

sortExpression

Returns the expression (or field name) to use for sorting features.

sortFeatures

Returns True if features should be sorted in the atlas.

updateFeatures

Requeries the current atlas coverage layer and applies filtering and sorting.

Signals

changed

Emitted when one of the atlas parameters changes.

coverageLayerChanged

Emitted when the coverage layer for the atlas changes.

featureChanged

Emitted when the current atlas feature changes.

messagePushed

Emitted when the atlas has an updated status bar message.

numberFeaturesChanged

Emitted when the number of features for the atlas changes.

renderBegun

Emitted when atlas rendering has begun.

renderEnded

Emitted when atlas rendering has ended.

toggled

Emitted when atlas is enabled or disabled.

class qgis.core.QgsLayoutAtlas[source]

Bases: QObject, QgsAbstractLayoutIterator, QgsLayoutSerializableObject, QgsExpressionContextGenerator

__init__(layout: QgsLayout | None)

Constructor for new QgsLayoutAtlas.

Parameters:

layout (Optional[QgsLayout])

signal changed[source]

Emitted when one of the atlas parameters changes.

coverageLayer(self) QgsVectorLayer | None[source]

Returns the coverage layer used for the atlas features.

Return type:

Optional[QgsVectorLayer]

signal coverageLayerChanged(layer: QgsVectorLayer)[source]

Emitted when the coverage layer for the atlas changes.

Parameters:

layer (QgsVectorLayer)

currentFeatureNumber(self) int[source]

Returns the current feature number, where a value of 0 corresponds to the first feature.

Return type:

int

currentFilename(self) str[source]

Returns the current feature filename.

Return type:

str

enabled(self) bool[source]

Returns whether the atlas generation is enabled

See also

setEnabled()

Return type:

bool

signal featureChanged(feature: QgsFeature)[source]

Emitted when the current atlas feature changes.

Parameters:

feature (QgsFeature)

filenameExpression(self) str[source]

Returns the filename expression used for generating output filenames for each atlas page.

Return type:

str

filterExpression(self) str[source]

Returns the expression used for filtering features in the coverage layer.

This property has no effect is filterFeatures() is False.

See also

filterFeatures()

Return type:

str

filterFeatures(self) bool[source]

Returns True if features should be filtered in the coverage layer.

Return type:

bool

first(self) bool[source]

Seeks to the first feature, returning False if no feature was found.

See also

next()

See also

previous()

See also

last()

See also

seekTo()

Return type:

bool

hideCoverage(self) bool[source]

Returns True if the atlas is set to hide the coverage layer.

Return type:

bool

last(self) bool[source]

Seeks to the last feature, returning False if no feature was found.

See also

next()

See also

previous()

See also

first()

See also

seekTo()

Return type:

bool

limitCoverageLayerRenderToCurrentFeature(self) bool[source]

Returns True if the atlas is set to limit rendering on the coverage layer to the current feature.

Added in version 4.0.

Return type:

bool

signal messagePushed(message: str)[source]

Emitted when the atlas has an updated status bar message.

Parameters:

message (str)

nameForPage(self, page: int) str[source]

Returns the calculated name for a specified atlas page number. Page numbers start at 0.

Parameters:

page (int)

Return type:

str

signal numberFeaturesChanged(numFeatures: int)[source]

Emitted when the number of features for the atlas changes.

Parameters:

numFeatures (int)

pageNameExpression(self) str[source]

Returns the expression (or field name) used for calculating the page name.

See also

nameForPage()

Return type:

str

previous(self) bool[source]

Iterates to the previous feature, returning False if no previous feature exists.

See also

next()

See also

last()

See also

first()

See also

seekTo()

Return type:

bool

refreshCurrentFeature(self)[source]

Refreshes the current atlas feature, by refetching its attributes from the vector layer provider

signal renderBegun[source]

Emitted when atlas rendering has begun.

signal renderEnded[source]

Emitted when atlas rendering has ended.

seekTo(self, feature: int) bool[source]

Seeks to the specified feature number.

See also

first()

See also

previous()

See also

next()

See also

last()

Parameters:

feature (int)

Return type:

bool

seekTo(self, feature: QgsFeature) bool[source]

Seeks to the specified feature.

See also

first()

See also

previous()

See also

next()

See also

last()

Parameters:

feature (QgsFeature)

Return type:

bool

setCoverageLayer(self, layer: QgsVectorLayer | None)[source]

Sets the coverage layer to use for the atlas features.

See also

coverageLayer()

Parameters:

layer (Optional[QgsVectorLayer])

setEnabled(self, enabled: bool)[source]

Sets whether the atlas is enabled.

See also

enabled()

Parameters:

enabled (bool)

setFilenameExpression(self, expression: str | None)[source]

Sets the filename expression used for generating output filenames for each atlas page. If an invalid expression is passed, False will be returned and errorString will be set to the expression error.

Parameters:

expression (Optional[str]) -> (bool)

setFilterExpression(self, expression: str | None)[source]

Sets the expression used for filtering features in the coverage layer.

This property has no effect is filterFeatures() is False.

If an invalid expression is passed, False will be returned and errorString will be set to the expression error.

Parameters:

expression (Optional[str]) -> (bool)

setFilterFeatures(self, filtered: bool)[source]

Sets whether features should be filtered in the coverage layer.

See also

filterFeatures()

Parameters:

filtered (bool)

setHideCoverage(self, hide: bool)[source]

Sets whether the coverage layer should be hidden in map items in the layouts.

See also

hideCoverage()

Parameters:

hide (bool)

setLimitCoverageLayerRenderToCurrentFeature(self, limit: bool)[source]

Sets whether the rendering of the coverage layer should be limited to the current feature.

See also

hideCoverage()

Added in version 4.0.

Parameters:

limit (bool)

setPageNameExpression(self, expression: str | None)[source]

Sets the expression (or field name) used for calculating the page name.

Parameters:

expression (Optional[str])

setSortAscending(self, ascending: bool)[source]

Sets whether features should be sorted in an ascending order.

This property has no effect is sortFeatures() is False.

See also

sortAscending()

Parameters:

ascending (bool)

setSortExpression(self, expression: str | None)[source]

Sets the expression (or field name) to use for sorting features.

This property has no effect is sortFeatures() is False.

See also

sortExpression()

Parameters:

expression (Optional[str])

setSortFeatures(self, enabled: bool)[source]

Sets whether features should be sorted in the atlas.

See also

sortFeatures()

Parameters:

enabled (bool)

sortAscending(self) bool[source]

Returns True if features should be sorted in an ascending order.

This property has no effect is sortFeatures() is False.

See also

sortFeatures()

See also

sortExpression()

Return type:

bool

sortExpression(self) str[source]

Returns the expression (or field name) to use for sorting features.

This property has no effect is sortFeatures() is False.

See also

sortFeatures()

See also

sortAscending()

Return type:

str

sortFeatures(self) bool[source]

Returns True if features should be sorted in the atlas.

See also

sortAscending()

See also

sortExpression()

Return type:

bool

signal toggled(enabled: bool)[source]

Emitted when atlas is enabled or disabled.

Parameters:

enabled (bool)

updateFeatures(self) int[source]

Requeries the current atlas coverage layer and applies filtering and sorting. Returns number of matching features.

Return type:

int