Class: QgsMapSettings¶

class qgis.core.QgsMapSettings¶

Bases: QgsTemporalRangeObject

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.

New in version 2.4:

Enums

Flag

alias of MapSettingsFlag

Methods

`addClippingRegion`	Adds a new clipping `region` to the map settings.
`addRenderedFeatureHandler`	Adds a rendered feature `handler` to use while rendering the map settings.
`backgroundColor`	Returns the background color of the map.
`clearCustomRenderingFlag`	Clears the specified custom rendering `flag`.
`clippingRegions`	Returns the list of clipping regions to apply to the map.
`computeExtentForScale`	Compute the extent such that its `center` is at the specified position (mapped to the destinatonCrs) and the zoom factor corresponds to the specified `scale`
`computeScaleForExtent`	Compute the scale that corresponds to the specified `extent`
`currentFrame`	Returns the current frame number of the map, for maps which are part of an animation.
`customRenderFlags`	Returns custom rendering flags.
`customRenderingFlags`	Returns any custom rendering flags.
`destinationCrs`	Returns the destination coordinate reference system for the map render.
`deviceOutputSize`	Returns the device output size of the map render.
`devicePixelRatio`	Returns the device pixel ratio.
`dpiTarget`	Returns the target DPI (dots per inch) to be taken into consideration when rendering.
`elevationShadingRenderer`	Returns the shading renderer used to render shading on the entire map
`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
`frameRate`	Returns the frame rate of the map (in frames per second), for maps which are part of an animation.
`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`	Returns the list of layer IDs which will be rendered in the map.
`layerStyleOverrides`	Returns the 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`	Returns the list of layers which will be rendered in the map.
`magnificationFactor`	Returns the magnification factor.
`mapToLayerCoordinates`	transform point coordinates from output CRS to layer's CRS
`mapToPixel`	rtype: QgsMapToPixel
`mapUnits`	Returns the units of the 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 the DPI (dots per inch) used for conversion between real world units (e.g. mm) and pixels.
`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, in pixels.
`pathResolver`	Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g. for resolving relative symbol paths.
`readXml`	serialization */
`renderedFeatureHandlers`	Returns the list of rendered feature handlers to use while rendering the map settings.
`rendererUsage`	Returns the rendering usage
`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`	Returns the color that is used for drawing of selected vector features.
`setBackgroundColor`	Sets the background `color` of the map.
`setClippingRegions`	Sets the list of clipping `regions` to apply to the map.
`setCurrentFrame`	Sets the current `frame` of the map, for maps which are part of an animation.
`setCustomRenderFlags`	Sets the custom rendering flags.
`setCustomRenderingFlag`	Sets a custom rendering `flag`.
`setDestinationCrs`	Sets the destination `crs` (coordinate reference system) for the map render.
`setDevicePixelRatio`	Sets the device pixel ratio.
`setDpiTarget`	Sets the target `dpi` (dots per inch) to be taken into consideration when rendering.
`setElevationShadingRenderer`	Sets the shading `renderer` used to render shading on the entire map
`setEllipsoid`	Sets the `ellipsoid` by its acronym.
`setExpressionContext`	Sets the expression context.
`setExtent`	Sets the 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
`setFrameRate`	Sets the frame `rate` of the map (in frames per second), for maps which are part of an animation.
`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`	Sets the 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`	Sets the list of `layers` to render in the map.
`setMagnificationFactor`	Set the magnification factor.
`setOutputDpi`	Sets the `dpi` (dots per inch) used for conversion between real world units (e.g. mm) and pixels.
`setOutputImageFormat`	sets format of internal QImage
`setOutputSize`	Sets the `size` of the resulting map image, in pixels.
`setPathResolver`	Sets the path `resolver` for conversion between relative and absolute paths during rendering operations, e.g. for resolving relative symbol paths.
`setRendererUsage`	Sets the rendering usage
`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 the `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. as paths or real text objects).
`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.
`setZRange`	Sets the `range` of z-values which will be visible in the map.
`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. as paths or real text objects).
`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 output image size into account
`visiblePolygon`	Returns the visible area as a polygon (may be rotated)
`visiblePolygonWithBuffer`	Returns the visible area as a polygon (may be rotated) with extent buffer included
`writeXml`	param node:
`zRange`	Returns the range of z-values which will be visible in the map.

Flag¶: alias of MapSettingsFlag

Flags¶: alias of MapSettingsFlags

addClippingRegion(self, region: QgsMapClippingRegion)¶

Adds a new clipping region to the map settings.

See also

clippingRegions()

See also

setClippingRegions()

New in version 3.16.

Parameters:: region (QgsMapClippingRegion) –

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.

See also

renderedFeatureHandlers()

New in version 3.10.

Parameters:: handler (QgsRenderedFeatureHandlerInterface) –

backgroundColor(self) → QColor¶

Returns the background color of the map.

See also

setBackgroundColor()

Return type:: QColor

clearCustomRenderingFlag(self, flag: str)¶

Clears the specified custom rendering flag.

Parameters:: flag (str) – the flag name

See also

setCustomRenderingFlag()

New in version 3.12.

clippingRegions(self) → List[QgsMapClippingRegion]¶

Returns the list of clipping regions to apply to the map.

See also

addClippingRegion()

See also

setClippingRegions()

New in version 3.16.

Return type:: List[QgsMapClippingRegion]

computeExtentForScale(self, center: QgsPointXY, scale: float) → QgsRectangle¶

Compute the extent such that its center is at the specified position (mapped to the destinatonCrs) and the zoom factor corresponds to the specified scale

Parameters:

center (QgsPointXY) – the center, in map coordinates
scale (float) – the desired zoom factor (the x part of 1:x)

Return type:

QgsRectangle

Returns:

an extent which can be passed to QgsMapCanvas.setExtent

See also

computeScaleForExtent()

New in version 3.22.

computeScaleForExtent(self, extent: QgsRectangle) → float¶

Compute the scale that corresponds to the specified extent

Parameters:: extent (QgsRectangle) – the extent, as passed to QgsMapCanvas.setExtent()
Return type:: float
Returns:: the scale denominator

See also

computeExtentForScale()

Note

This function does not consider any map rotation

New in version 3.22.

currentFrame(self) → int¶

Returns the current frame number of the map, for maps which are part of an animation.

Returns -1 if the map is not associated with an animation.

See also

setCurrentFrame()

New in version 3.26.

Return type:: int

customRenderFlags(self) → str¶

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

Return type:: str
Returns:: custom flags strings, separated by ‘;’

See also

setCustomRenderFlags()

New in version 2.16.

Deprecated since version use: see customRenderingFlags().

customRenderingFlags(self) → Dict[str, Any]¶

Returns any custom rendering flags. Layers might honour these to alter their rendering.

Return type:: Dict[str, Any]
Returns:: a map of custom flags

See also

setCustomRenderingFlag()

New in version 3.12.

destinationCrs(self) → QgsCoordinateReferenceSystem¶

Returns the destination coordinate reference system for the map render.

See also

setDestinationCrs()

Return type:: QgsCoordinateReferenceSystem

deviceOutputSize(self) → QSize¶

Returns the device output size of the map render.

This is equivalent to the output size multiplicated by the device pixel ratio.

See also

outputSize()

See also

devicePixelRatio()

See also

setOutputSize()

New in version 3.4.

Return type:: QSize

devicePixelRatio(self) → float¶

Returns the 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

dpiTarget(self) → float¶

Returns the target DPI (dots per inch) to be taken into consideration when rendering.

The default value is -1, which states no DPI target is provided.

See also

setDpiTarget()

New in version 3.20.

Return type:: float

elevationShadingRenderer(self) → QgsElevationShadingRenderer¶

Returns the shading renderer used to render shading on the entire map

See also

setElevationShadingRenderer()

New in version 3.30.

Return type:: QgsElevationShadingRenderer

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.

See also

setExpressionContext()

New in version 2.12.

Return type:: QgsExpressionContext

extent(self) → QgsRectangle¶

Returns geographical coordinates of the rectangle that should be rendered.

Warning

The actual visible extent used for rendering can be significantly different from this value, since the given extent may be expanded in order to fit the aspect ratio of the outputSize(). Use visibleExtent() to get the actual extent which will be rendered.

See also

visibleExtent()

See also

setExtent()

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.

See also

setExtentBuffer()

New in version 3.10.

Return type:: float

flags(self) → Qgis.MapSettingsFlags¶

Returns combination of flags used for rendering

Return type:: Qgis.MapSettingsFlags

frameRate(self) → float¶

Returns the frame rate of the map (in frames per second), for maps which are part of an animation.

Returns -1 if the map is not associated with an animation.

See also

setFrameRate()

New in version 3.26.

Return type:: float

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.

See also

setLabelBlockingRegions()

See also

labelBoundaryGeometry()

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

See also

setLabelBoundaryGeometry()

See also

labelBlockingRegions()

New in version 3.6.

Return type:: QgsGeometry

labelingEngineSettings(self) → QgsLabelingEngineSettings¶

Returns the global configuration of the labeling engine.

See also

setLabelingEngineSettings()

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

See also

layerToMapCoordinates()

Return type:

QgsRectangle

Returns:

a bounding box (aligned rectangle) containing the transformed extent

Parameters:

layer (QgsMapLayer) –
extent (QgsRectangle) –

layerIds(self, expandGroupLayers: bool = False) → List[str]¶

Returns the list of layer IDs which will be rendered in the map.

The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top).

Since QGIS 3.24, if the expandGroupLayers option is True then group layers will be converted to all their child layers.

See also

layers()

See also

setLayers()

Parameters:: expandGroupLayers (bool = False) –
Return type:: List[str]

layerStyleOverrides(self) → Dict[str, str]¶

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

See also

setLayerStyleOverrides()

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, point: QgsPoint) -> QgsPoint transform point coordinates from layer’s CRS to output CRS

Returns:: the transformed point

New in version 3.16.

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

See also

layerExtentToOutputExtent()

Return type:

QgsPointXY

Returns:

the transformed rectangle

Parameters:

layer (QgsMapLayer) –
point (QgsPointXY) –

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, expandGroupLayers: bool = False) → List[QgsMapLayer]¶

Returns the list of layers which will be rendered in the map.

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

Since QGIS 3.24, if the expandGroupLayers option is True then group layers will be converted to all their child layers.

See also

setLayers()

See also

layerIds()

Parameters:: expandGroupLayers (bool = False) –
Return type:: List[QgsMapLayer]

magnificationFactor(self) → float¶

Returns the magnification factor.

See also

setMagnificationFactor()

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, point: QgsPoint) -> QgsPoint transform point coordinates from output CRS to layer’s CRS

Returns:: the transformed point

New in version 3.16.

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

See also

outputExtentToLayerExtent()

Return type:

QgsPointXY

Returns:

the transformed rectangle

Parameters:

layer (QgsMapLayer) –
point (QgsPointXY) –

mapToPixel(self) → QgsMapToPixel¶

Return type:: QgsMapToPixel

mapUnits(self) → Qgis.DistanceUnit¶

Returns the units of the map’s geographical coordinates - used for scale calculation.

Return type:: Qgis.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 the DPI (dots per inch) used for conversion between real world units (e.g. mm) and pixels.

The default value is 96 dpi.

See also

setOutputDpi()

Return type:: float

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

transform bounding box from output CRS to layer’s CRS

See also

mapToLayerCoordinates()

Return type:

QgsRectangle

Returns:

a bounding box (aligned rectangle) containing the transformed extent

Parameters:

layer (QgsMapLayer) –
extent (QgsRectangle) –

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, in pixels.

See also

deviceOutputSize()

See also

setOutputSize()

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.

See also

setPathResolver()

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.

See also

addRenderedFeatureHandler()

New in version 3.10.

Return type:: List[QgsRenderedFeatureHandlerInterface]

rendererUsage(self) → Qgis.RendererUsage¶

Returns the rendering usage

See also

setRendererUsage()

New in version 3.24.

Return type:: Qgis.RendererUsage

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¶

Returns the color that is used for drawing of selected vector features.

See also

setSelectionColor()

Return type:: QColor

setBackgroundColor(self, color: QColor | Qt.GlobalColor | QGradient)¶

Sets the background color of the map.

See also

backgroundColor()

Parameters:: color (Union[QColor) –

setClippingRegions(self, regions: Iterable[QgsMapClippingRegion])¶

Sets the list of clipping regions to apply to the map.

See also

addClippingRegion()

See also

clippingRegions()

New in version 3.16.

Parameters:: regions (Iterable[QgsMapClippingRegion]) –

setCurrentFrame(self, frame: int)¶

Sets the current frame of the map, for maps which are part of an animation.

Defaults to -1 if the map is not associated with an animation.

See also

currentFrame()

New in version 3.26.

Parameters:: frame (int) –

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 ‘;’

See also

customRenderFlags()

New in version 2.16.

Deprecated since version use: see setCustomRenderingFlag() instead.

setCustomRenderingFlag(self, flag: str, value: Any)¶

Sets a custom rendering flag. Layers might honour these to alter their rendering.

Parameters:

flag (str) – the flag name
value (Any) – the flag value

See also

customRenderingFlags()

New in version 3.12.

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)¶

Sets the destination crs (coordinate reference system) for the map render.

See also

destinationCrs()

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

setDpiTarget(self, dpi: float)¶

Sets the target dpi (dots per inch) to be taken into consideration when rendering.

See also

dpiTarget()

New in version 3.20.

Parameters:: dpi (float) –

setElevationShadingRenderer(self, renderer: QgsElevationShadingRenderer)¶

Sets the shading renderer used to render shading on the entire map

See also

elevationShadingRenderer()

New in version 3.30.

Parameters:: renderer (QgsElevationShadingRenderer) –

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.

See also

expressionContext()

New in version 2.12.

Parameters:: context (QgsExpressionContext) –

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

Sets the coordinates of the rectangle which should be rendered.

Warning

The actual visible extent used for rendering can be significantly different from the specified extent, since the given extent may be expanded in order to match the aspect ratio of outputSize(). Use visibleExtent() to retrieve the actual extent to be rendered.

See also

visibleExtent()

See also

extent()

Parameters:

rect (QgsRectangle) –
magnified (bool = True) –

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: Qgis.MapSettingsFlag, on: bool = True)¶

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

Parameters:

flag (Qgis.MapSettingsFlag) –
on (bool = True) –

setFlags(self, flags: Qgis.MapSettingsFlags | Qgis.MapSettingsFlag)¶

Sets combination of flags that will be used for rendering

Parameters:: flags (Union[Qgis.MapSettingsFlags) –

setFrameRate(self, rate: float)¶

Sets the frame rate of the map (in frames per second), for maps which are part of an animation.

Defaults to -1 if the map is not associated with an animation.

See also

frameRate()

New in version 3.26.

Parameters:: rate (float) –

setLabelBlockingRegions(self, regions: Iterable[QgsLabelBlockingRegion])¶

Sets a list of regions to avoid placing labels within.

See also

labelBlockingRegions()

See also

setLabelBoundaryGeometry()

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

See also

labelBoundaryGeometry()

See also

setLabelBlockingRegions()

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.

See also

labelingEngineSettings()

New in version 3.0.

Parameters:: settings (QgsLabelingEngineSettings) –

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

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

See also

layerStyleOverrides()

New in version 2.8.

Parameters:: overrides (Dict[str) –

setLayers(self, layers: Iterable[QgsMapLayer])¶

Sets the list of layers to render in the map.

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

See also

layers()

See also

layerIds()

Parameters:: layers (Iterable[QgsMapLayer]) –

setMagnificationFactor(self, factor: float, center: QgsPointXY = None)¶

Set the magnification factor.

Parameters:

factor (float) – the factor of magnification
center (QgsPointXY = None) – optional point to re-center the map

See also

magnificationFactor()

New in version 2.16.

setOutputDpi(self, dpi: float)¶

Sets the dpi (dots per inch) used for conversion between real world units (e.g. mm) and pixels.

See also

outputDpi()

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, in pixels.

See also

outputSize()

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

setRendererUsage(self, rendererUsage: Qgis.RendererUsage)¶

Sets the rendering usage

Note

This usage not alter how the map gets rendered but the intention is that data provider knows the context of rendering and may report that to the backend.

See also

rendererUsage()

New in version 3.24.

Parameters:: rendererUsage (Qgis.RendererUsage) –

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: QColor | Qt.GlobalColor | QGradient)¶

Sets the color that is used for drawing of selected vector features.

See also

selectionColor()

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

See also

textRenderFormat()

New in version 3.4.3.

Parameters:: format (Qgis.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.

See also

transformContext()

New in version 3.0.

Parameters:: context (QgsCoordinateTransformContext) –

setZRange(self, range: QgsDoubleRange)¶

Sets the range of z-values which will be visible in the map.

See also

zRange()

New in version 3.18.

Parameters:: range (QgsDoubleRange) –

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.

See also

setSimplifyMethod()

New in version 3.10.

Return type:: QgsVectorSimplifyMethod

testFlag(self, flag: Qgis.MapSettingsFlag) → bool¶

Check whether a particular flag is enabled

Parameters:: flag (Qgis.MapSettingsFlag) –
Return type:: bool

textRenderFormat(self) → Qgis.TextRenderFormat¶

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

See also

setTextRenderFormat()

New in version 3.4.3.

Return type:: Qgis.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.

See also

setTransformContext()

New in version 3.0.

Return type:: QgsCoordinateTransformContext

updateDerived(self)¶

visibleExtent(self) → QgsRectangle¶

Returns the actual extent derived from requested extent that 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

visiblePolygonWithBuffer(self) → QPolygonF¶

Returns the visible area as a polygon (may be rotated) with extent buffer included

See also

extentBuffer()

New in version 3.22.

Return type:: QPolygonF

writeXml(self, node: QDomNode, doc: QDomDocument)¶

Parameters:

node (QDomNode) –
doc (QDomDocument) –

zRange(self) → QgsDoubleRange¶

Returns the range of z-values which will be visible in the map.

See also

setZRange()

New in version 3.18.

Return type:: QgsDoubleRange