Class: QgsLayoutAtlas

Class 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

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

Bases: QObject, QgsAbstractLayoutIterator, QgsLayoutSerializableObject, QgsExpressionContextGenerator

__init__(layout: QgsLayout | None)

Constructor for new QgsLayoutAtlas.

Parameters:

layout (Optional[QgsLayout])

signal changed

Emitted when one of the atlas parameters changes.

coverageLayer(self) → QgsVectorLayer | None

Returns the coverage layer used for the atlas features.

See also

setCoverageLayer()

Return type:

Optional[QgsVectorLayer]

signal coverageLayerChanged(layer: QgsVectorLayer)

Emitted when the coverage layer for the atlas changes.

Parameters:

layer (QgsVectorLayer)

currentFeatureNumber(self) → int

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

Return type:

int

currentFilename(self) → str

Returns the current feature filename.

See also

filenameExpression()

See also

setFilenameExpression()

Return type:

str

enabled(self) → bool

Returns whether the atlas generation is enabled

See also

setEnabled()

Return type:

bool

signal featureChanged(feature: QgsFeature)

Emitted when the current atlas feature changes.

Parameters:

feature (QgsFeature)

filenameExpression(self) → str

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

See also

setFilenameExpression()

See also

currentFilename()

Return type:

str

filterExpression(self) → str

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

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

See also

setFilterExpression()

See also

filterFeatures()

Return type:

str

filterFeatures(self) → bool

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

See also

filterExpression()

See also

setFilterExpression()

Return type:

bool

first(self) → bool

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

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

See also

setHideCoverage()

Return type:

bool

last(self) → bool

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

signal messagePushed(message: str)

Emitted when the atlas has an updated status bar message.

Parameters:

message (str)

nameForPage(self, page: int) → str

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

See also

pageNameExpression()

Parameters:

page (int)

Return type:

str

signal numberFeaturesChanged(numFeatures: int)

Emitted when the number of features for the atlas changes.

Parameters:

numFeatures (int)

pageNameExpression(self) → str

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

See also

setPageNameExpression()

See also

nameForPage()

Return type:

str

previous(self) → bool

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)

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

signal renderBegun

Emitted when atlas rendering has begun.

signal renderEnded

Emitted when atlas rendering has ended.

seekTo(self, feature: int) → bool

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

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)

Sets the coverage layer to use for the atlas features.

See also

coverageLayer()

Parameters:

layer (Optional[QgsVectorLayer])

setEnabled(self, enabled: bool)

Sets whether the atlas is enabled.

See also

enabled()

Parameters:

enabled (bool)

setFilenameExpression(self, expression: str | None)

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.

See also

filenameExpression()

See also

currentFilename()

Parameters:

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

setFilterExpression(self, expression: str | None)

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.

See also

filterExpression()

See also

setFilterFeatures()

Parameters:

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

setFilterFeatures(self, filtered: bool)

Sets whether features should be filtered in the coverage layer.

See also

filterFeatures()

See also

setFilterExpression()

Parameters:

filtered (bool)

setHideCoverage(self, hide: bool)

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

See also

hideCoverage()

Parameters:

hide (bool)

setPageNameExpression(self, expression: str | None)

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

See also

pageNameExpression()

Parameters:

expression (Optional[str])

setSortAscending(self, ascending: bool)

Sets whether features should be sorted in an ascending order.

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

See also

setSortFeatures()

See also

sortAscending()

See also

setSortExpression()

Parameters:

ascending (bool)

setSortExpression(self, expression: str | None)

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

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

See also

setSortFeatures()

See also

setSortAscending()

See also

sortExpression()

Parameters:

expression (Optional[str])

setSortFeatures(self, enabled: bool)

Sets whether features should be sorted in the atlas.

See also

sortFeatures()

See also

setSortAscending()

See also

setSortExpression()

Parameters:

enabled (bool)

sortAscending(self) → bool

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

setSortAscending()

See also

sortExpression()

Return type:

bool

sortExpression(self) → str

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()

See also

setSortExpression()

Return type:

str

sortFeatures(self) → bool

Returns True if features should be sorted in the atlas.

See also

setSortFeatures()

See also

sortAscending()

See also

sortExpression()

Return type:

bool

signal toggled(enabled: bool)

Emitted when atlas is enabled or disabled.

Parameters:

enabled (bool)

updateFeatures(self) → int

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

Return type:

int