Class: QgsMapSettings

class qgis.core.QgsMapSettings

Bases: sip.wrapper

The QgsMapSettings class contains configuration for rendering of the map. The rendering itself is done by QgsMapRendererJob subclasses.

In order to set up QgsMapSettings instance, it is necessary to set at least few members: extent, output size and layers.

Some systems use high DPI scaling that is an alternative to the traditional DPI scaling. The operating system provides Qt with a scaling ratio and it scales window, event, and desktop geometry. The Cocoa platform plugin sets the scaling ratio as QWindow.devicePixelRatio(). To properly render the map on such systems, the map settings device pixel ratio shall be set accordingly.

Methods

addRenderedFeatureHandler

Adds a rendered feature handler to use while rendering the map settings.

backgroundColor

Gets the background color of the map

customRenderFlags

Gets custom rendering flags.

destinationCrs

returns CRS of destination coordinate reference system

deviceOutputSize

Returns the device output size of the map canvas This is equivalent to the output size multiplicated by the device pixel ratio.

devicePixelRatio

Returns device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi “retina” displays.

ellipsoid

Returns ellipsoid’s acronym.

expressionContext

Gets the expression context.

extent

Returns geographical coordinates of the rectangle that should be rendered.

extentBuffer

Returns the buffer in map units to use around the visible extent for rendering symbols whose corresponding geometries are outside the visible extent.

flags

Returns combination of flags used for rendering

fullExtent

returns current extent of layer set

hasValidSettings

Check whether the map settings are valid and can be used for rendering

labelBlockingRegions

Returns the list of regions to avoid placing labels within.

labelBoundaryGeometry

Returns the label boundary geometry, which restricts where in the rendered map labels are permitted to be placed.

labelingEngineSettings

Returns the global configuration of the labeling engine.

layerExtentToOutputExtent

transform bounding box from layer’s CRS to output CRS

layerIds

Gets list of layer IDs for map rendering The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)

layerStyleOverrides

Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

layerToMapCoordinates

transform point coordinates from layer’s CRS to output CRS

layerToMapUnits

Computes an estimated conversion factor between layer and map units: layerUnits * layerToMapUnits = mapUnits

layerTransform

Returns the coordinate transform from layer’s CRS to destination CRS

layers

Gets list of layers for map rendering The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)

magnificationFactor

Returns the magnification factor.

mapToLayerCoordinates

transform point coordinates from output CRS to layer’s CRS

mapToPixel

rtype

QgsMapToPixel

mapUnits

Gets units of map’s geographical coordinates - used for scale calculation

mapUnitsPerPixel

Returns the distance in geographical coordinates that equals to one pixel in the map

outputDpi

Returns DPI used for conversion between real world units (e.g.

outputExtentToLayerExtent

transform bounding box from output CRS to layer’s CRS

outputImageFormat

format of internal QImage, default QImage.Format_ARGB32_Premultiplied

outputSize

Returns the size of the resulting map image

pathResolver

Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.

readXml

serialization */

renderedFeatureHandlers

Returns the list of rendered feature handlers to use while rendering the map settings.

rotation

Returns the rotation of the resulting map image, in degrees clockwise.

scale

Returns the calculated map scale.

segmentationTolerance

Gets the segmentation tolerance applied when rendering curved geometries

segmentationToleranceType

Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

selectionColor

Gets color that is used for drawing of selected vector features

setBackgroundColor

Sets the background color of the map

setCustomRenderFlags

Sets the custom rendering flags.

setDestinationCrs

sets destination coordinate reference system

setDevicePixelRatio

Sets the device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi “retina” displays.

setEllipsoid

Sets the ellipsoid by its acronym.

setExpressionContext

Sets the expression context.

setExtent

Set coordinates of the rectangle which should be rendered.

setExtentBuffer

Sets the buffer in map units to use around the visible extent for rendering symbols whose corresponding geometries are outside the visible extent.

setFlag

Enable or disable a particular flag (other flags are not affected)

setFlags

Sets combination of flags that will be used for rendering

setLabelBlockingRegions

Sets a list of regions to avoid placing labels within.

setLabelBoundaryGeometry

Sets the label boundary geometry, which restricts where in the rendered map labels are permitted to be placed.

setLabelingEngineSettings

Sets the global configuration of the labeling engine.

setLayerStyleOverrides

Set map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

setLayers

Set list of layers for map rendering.

setMagnificationFactor

Set the magnification factor.

setOutputDpi

Sets DPI used for conversion between real world units (e.g.

setOutputImageFormat

sets format of internal QImage

setOutputSize

Sets the size of the resulting map image

setPathResolver

Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.

setRotation

Sets the rotation of the resulting map image, in degrees clockwise.

setSegmentationTolerance

Sets the segmentation tolerance applied when rendering curved geometries

setSegmentationToleranceType

Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

setSelectionColor

Sets color that is used for drawing of selected vector features

setSimplifyMethod

Sets the simplification setting to use when rendering vector layers.

setTextRenderFormat

Sets the text render format, which dictates how text is rendered (e.g.

setTransformContext

Sets the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

simplifyMethod

Returns the simplification settings to use when rendering vector layers.

testFlag

Check whether a particular flag is enabled

textRenderFormat

Returns the text render format, which dictates how text is rendered (e.g.

transformContext

Returns the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

updateDerived

visibleExtent

Returns the actual extent derived from requested extent that takes takes output image size into account

visiblePolygon

Returns the visible area as a polygon (may be rotated)

writeXml

param node

Attributes

Antialiasing

DrawEditingInfo

DrawLabeling

DrawSelection

DrawSymbolBounds

ForceVectorOutput

RenderBlocking

RenderMapTile

RenderPartialOutput

RenderPreviewJob

UseAdvancedEffects

UseRenderingOptimization

Antialiasing = 1
DrawEditingInfo = 2
DrawLabeling = 16
DrawSelection = 64
DrawSymbolBounds = 128
class Flag

Bases: int

class Flags

Bases: sip.wrapper

QgsMapSettings.Flags(Union[QgsMapSettings.Flags, QgsMapSettings.Flag]) QgsMapSettings.Flags(QgsMapSettings.Flags)

ForceVectorOutput = 4
RenderBlocking = 2048
RenderMapTile = 256
RenderPartialOutput = 512
RenderPreviewJob = 1024
UseAdvancedEffects = 8
UseRenderingOptimization = 32
addRenderedFeatureHandler(self, handler: QgsRenderedFeatureHandlerInterface)

Adds a rendered feature handler to use while rendering the map settings.

Ownership of handler is NOT transferred, and it is the caller’s responsibility to ensure that the handler exists for the lifetime of the map render job.

New in version 3.10.

Parameters

handler (QgsRenderedFeatureHandlerInterface) –

backgroundColor(self) → QColor

Gets the background color of the map

Return type

QColor

customRenderFlags(self) → str

Gets custom rendering flags. Layers might honour these to alter their rendering.

Return type

str

Returns

custom flags strings, separated by ‘;’

New in version 2.16.

destinationCrs(self)QgsCoordinateReferenceSystem

returns CRS of destination coordinate reference system

Return type

QgsCoordinateReferenceSystem

deviceOutputSize(self) → QSize

Returns the device output size of the map canvas This is equivalent to the output size multiplicated by the device pixel ratio.

New in version 3.4.

Return type

QSize

devicePixelRatio(self) → float

Returns device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi “retina” displays.

New in version 3.4.

Return type

float

ellipsoid(self) → str

Returns ellipsoid’s acronym. Calculations will only use the ellipsoid if a valid ellipsoid has been set.

See also

setEllipsoid()

New in version 3.0.

Return type

str

expressionContext(self)QgsExpressionContext

Gets the expression context. This context should be used for all expression evaluation associated with this map settings.

New in version 2.12.

Return type

QgsExpressionContext

extent(self)QgsRectangle

Returns geographical coordinates of the rectangle that should be rendered. The actual visible extent used for rendering could be slightly different since the given extent may be expanded in order to fit the aspect ratio of output size. Use visibleExtent() to get the resulting extent.

Return type

QgsRectangle

extentBuffer(self) → float

Returns the buffer in map units to use around the visible extent for rendering symbols whose corresponding geometries are outside the visible extent.

New in version 3.10.

Return type

float

flags(self) → QgsMapSettings.Flags

Returns combination of flags used for rendering

Return type

QgsMapSettings.Flags

fullExtent(self)QgsRectangle

returns current extent of layer set

Return type

QgsRectangle

hasValidSettings(self) → bool

Check whether the map settings are valid and can be used for rendering

Return type

bool

labelBlockingRegions(self) → List[QgsLabelBlockingRegion]

Returns the list of regions to avoid placing labels within.

New in version 3.6.

Return type

List[QgsLabelBlockingRegion]

labelBoundaryGeometry(self)QgsGeometry

Returns the label boundary geometry, which restricts where in the rendered map labels are permitted to be placed. By default this is a null geometry, which indicates that labels can be placed anywhere within the map’s visiblePolygon().

The geometry is specified using the map’s destinationCrs().

New in version 3.6.

Return type

QgsGeometry

labelingEngineSettings(self)QgsLabelingEngineSettings

Returns the global configuration of the labeling engine.

New in version 3.0.

Return type

QgsLabelingEngineSettings

layerExtentToOutputExtent(self, layer: QgsMapLayer, extent: QgsRectangle)QgsRectangle

transform bounding box from layer’s CRS to output CRS

Return type

QgsRectangle

Returns

a bounding box (aligned rectangle) containing the transformed extent

Parameters
layerIds(self) → List[str]

Gets list of layer IDs for map rendering The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)

Return type

List[str]

layerStyleOverrides(self) → Dict[str, str]

Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

New in version 2.8.

Return type

Dict[str, str]

layerToMapCoordinates(self, layer: QgsMapLayer, point: QgsPointXY)QgsPointXY

transform point coordinates from layer’s CRS to output CRS

Returns

the transformed point

layerToMapCoordinates(self, layer: QgsMapLayer, rect: QgsRectangle) -> QgsRectangle transform rectangle from layer’s CRS to output CRS

Return type

QgsPointXY

Returns

the transformed rectangle

Parameters
layerToMapUnits(self, layer: QgsMapLayer, referenceExtent: QgsRectangle = QgsRectangle()) → float

Computes an estimated conversion factor between layer and map units: layerUnits * layerToMapUnits = mapUnits

Parameters
  • layer (QgsMapLayer) – The layer

  • referenceExtent (QgsRectangle = QgsRectangle()) – A reference extent based on which to perform the computation. If not specified, the layer extent is used

New in version 2.12.

Return type

float

layerTransform(self, layer: QgsMapLayer)QgsCoordinateTransform

Returns the coordinate transform from layer’s CRS to destination CRS

Return type

QgsCoordinateTransform

Returns

transform - may be invalid if the transform is not needed

Parameters

layer (QgsMapLayer) –

layers(self) → List[QgsMapLayer]

Gets list of layers for map rendering The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)

Return type

List[QgsMapLayer]

magnificationFactor(self) → float

Returns the magnification factor.

New in version 2.16.

Return type

float

mapToLayerCoordinates(self, layer: QgsMapLayer, point: QgsPointXY)QgsPointXY

transform point coordinates from output CRS to layer’s CRS

Returns

the transformed point

mapToLayerCoordinates(self, layer: QgsMapLayer, rect: QgsRectangle) -> QgsRectangle transform rectangle from output CRS to layer’s CRS

Return type

QgsPointXY

Returns

the transformed rectangle

Parameters
mapToPixel(self)QgsMapToPixel
Return type

QgsMapToPixel

mapUnits(self) → QgsUnitTypes.DistanceUnit

Gets units of map’s geographical coordinates - used for scale calculation

Return type

QgsUnitTypes.DistanceUnit

mapUnitsPerPixel(self) → float

Returns the distance in geographical coordinates that equals to one pixel in the map

Return type

float

outputDpi(self) → float

Returns DPI used for conversion between real world units (e.g. mm) and pixels Default value is 96

Return type

float

outputExtentToLayerExtent(self, layer: QgsMapLayer, extent: QgsRectangle)QgsRectangle

transform bounding box from output CRS to layer’s CRS

Return type

QgsRectangle

Returns

a bounding box (aligned rectangle) containing the transformed extent

Parameters
outputImageFormat(self) → QImage.Format

format of internal QImage, default QImage.Format_ARGB32_Premultiplied

Return type

QImage.Format

outputSize(self) → QSize

Returns the size of the resulting map image

Return type

QSize

pathResolver(self)QgsPathResolver

Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g. for resolving relative symbol paths.

New in version 3.0.

Return type

QgsPathResolver

readXml(self, node: QDomNode)

serialization */

Parameters

node (QDomNode) –

renderedFeatureHandlers(self) → List[QgsRenderedFeatureHandlerInterface]

Returns the list of rendered feature handlers to use while rendering the map settings.

New in version 3.10.

Return type

List[QgsRenderedFeatureHandlerInterface]

rotation(self) → float

Returns the rotation of the resulting map image, in degrees clockwise.

See also

setRotation()

New in version 2.8.

Return type

float

scale(self) → float

Returns the calculated map scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

Return type

float

segmentationTolerance(self) → float

Gets the segmentation tolerance applied when rendering curved geometries

Return type

float

segmentationToleranceType(self) → QgsAbstractGeometry.SegmentationToleranceType

Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

Return type

QgsAbstractGeometry.SegmentationToleranceType

selectionColor(self) → QColor

Gets color that is used for drawing of selected vector features

Return type

QColor

setBackgroundColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the background color of the map

Parameters

color (Union[QColor) –

setCustomRenderFlags(self, customRenderFlags: str)

Sets the custom rendering flags. Layers might honour these to alter their rendering.

Parameters

customRenderFlags (str) – custom flags strings, separated by ‘;’

New in version 2.16.

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)

sets destination coordinate reference system

Parameters

crs (QgsCoordinateReferenceSystem) –

setDevicePixelRatio(self, dpr: float)

Sets the device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi “retina” displays.

New in version 3.4.

Parameters

dpr (float) –

setEllipsoid(self, ellipsoid: str) → bool

Sets the ellipsoid by its acronym. Known ellipsoid acronyms can be retrieved using QgsEllipsoidUtils.acronyms() Calculations will only use the ellipsoid if a valid ellipsoid has been set.

Return type

bool

Returns

True if ellipsoid was successfully set

See also

ellipsoid()

New in version 3.0.

Parameters

ellipsoid (str) –

setExpressionContext(self, context: QgsExpressionContext)

Sets the expression context. This context is used for all expression evaluation associated with this map settings.

New in version 2.12.

Parameters

context (QgsExpressionContext) –

setExtent(self, rect: QgsRectangle, magnified: bool = True)

Set coordinates of the rectangle which should be rendered. The actual visible extent used for rendering could be slightly different since the given extent may be expanded in order to fit the aspect ratio of output size. Use visibleExtent() to get the resulting extent.

Parameters
setExtentBuffer(self, buffer: float)

Sets the buffer in map units to use around the visible extent for rendering symbols whose corresponding geometries are outside the visible extent. This is useful when using tiles to avoid cut symbols at tile boundaries.

New in version 3.10.

Parameters

buffer (float) –

setFlag(self, flag: QgsMapSettings.Flag, on: bool = True)

Enable or disable a particular flag (other flags are not affected)

Parameters
setFlags(self, flags: Union[QgsMapSettings.Flags, QgsMapSettings.Flag])

Sets combination of flags that will be used for rendering

Parameters

flags (Union[QgsMapSettings.Flags) –

setLabelBlockingRegions(self, regions: Iterable[QgsLabelBlockingRegion])

Sets a list of regions to avoid placing labels within.

New in version 3.6.

Parameters

regions (Iterable[QgsLabelBlockingRegion]) –

setLabelBoundaryGeometry(self, boundary: QgsGeometry)

Sets the label boundary geometry, which restricts where in the rendered map labels are permitted to be placed.

A null boundary geometry (the default) indicates that labels can be placed anywhere within the map’s visiblePolygon().

The geometry is specified using the map’s destinationCrs().

New in version 3.6.

Parameters

boundary (QgsGeometry) –

setLabelingEngineSettings(self, settings: QgsLabelingEngineSettings)

Sets the global configuration of the labeling engine.

Note

Calling this method will reset the textRenderFormat() to match the default text render format from the label engine settings.

New in version 3.0.

Parameters

settings (QgsLabelingEngineSettings) –

setLayerStyleOverrides(self, overrides: Dict[str, str])

Set map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

New in version 2.8.

Parameters

overrides (Dict[str) –

setLayers(self, layers: Iterable[QgsMapLayer])

Set list of layers for map rendering. The layers must be registered in QgsProject. The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)

Note

Any non-spatial layers will be automatically stripped from the list (since they cannot be rendered!).

Parameters

layers (Iterable[QgsMapLayer]) –

setMagnificationFactor(self, factor: float)

Set the magnification factor.

Parameters

factor (float) – the factor of magnification

New in version 2.16.

setOutputDpi(self, dpi: float)

Sets DPI used for conversion between real world units (e.g. mm) and pixels

Parameters

dpi (float) –

setOutputImageFormat(self, format: QImage.Format)

sets format of internal QImage

Parameters

format (QImage.Format) –

setOutputSize(self, size: QSize)

Sets the size of the resulting map image

Parameters

size (QSize) –

setPathResolver(self, resolver: QgsPathResolver)

Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g. for resolving relative symbol paths.

See also

pathResolver()

New in version 3.0.

Parameters

resolver (QgsPathResolver) –

setRotation(self, rotation: float)

Sets the rotation of the resulting map image, in degrees clockwise.

See also

rotation()

New in version 2.8.

Parameters

rotation (float) –

setSegmentationTolerance(self, tolerance: float)

Sets the segmentation tolerance applied when rendering curved geometries

Parameters

tolerance (float) – the segmentation tolerance*

setSegmentationToleranceType(self, type: QgsAbstractGeometry.SegmentationToleranceType)

Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

Parameters

type (QgsAbstractGeometry.SegmentationToleranceType) – the segmentation tolerance typename*

setSelectionColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets color that is used for drawing of selected vector features

Parameters

color (Union[QColor) –

setSimplifyMethod(self, method: QgsVectorSimplifyMethod)

Sets the simplification setting to use when rendering vector layers.

If the simplify method is enabled, it will override all other layer-specific simplification settings and will apply to all vector layers rendered for the map.

This can be used to specify global simplification methods to apply during map exports, e.g. to allow vector layers to be simplified to an appropriate maximum level of detail during PDF exports.

The default is to use no global simplification, and fallback to individual layer’s settings instead.

See also

simplifyMethod()

New in version 3.10.

Parameters

method (QgsVectorSimplifyMethod) –

setTextRenderFormat(self, format: QgsRenderContext.TextRenderFormat)

Sets the text render format, which dictates how text is rendered (e.g. as paths or real text objects).

Warning

Calling the setLabelingEngineSettings() method will reset the text render format to match the default text render format from the label engine settings.

New in version 3.4.3.

Parameters

format (QgsRenderContext.TextRenderFormat) –

setTransformContext(self, context: QgsCoordinateTransformContext)

Sets the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

New in version 3.0.

Parameters

context (QgsCoordinateTransformContext) –

simplifyMethod(self)QgsVectorSimplifyMethod

Returns the simplification settings to use when rendering vector layers.

If enabled, it will override all other layer-specific simplification settings and will apply to all vector layers rendered for the map.

The default is to use no global simplification, and fallback to individual layer’s settings instead.

New in version 3.10.

Return type

QgsVectorSimplifyMethod

testFlag(self, flag: QgsMapSettings.Flag) → bool

Check whether a particular flag is enabled

Parameters

flag (QgsMapSettings.Flag) –

Return type

bool

textRenderFormat(self) → QgsRenderContext.TextRenderFormat

Returns the text render format, which dictates how text is rendered (e.g. as paths or real text objects).

New in version 3.4.3.

Return type

QgsRenderContext.TextRenderFormat

transformContext(self)QgsCoordinateTransformContext

Returns the coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

New in version 3.0.

Return type

QgsCoordinateTransformContext

updateDerived(self)
visibleExtent(self)QgsRectangle

Returns the actual extent derived from requested extent that takes takes output image size into account

Return type

QgsRectangle

visiblePolygon(self) → QPolygonF

Returns the visible area as a polygon (may be rotated)

New in version 2.8.

Return type

QPolygonF

writeXml(self, node: QDomNode, doc: QDomDocument)
Parameters
  • node (QDomNode) –

  • doc (QDomDocument) –