Subgroup: Map

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.

QgsMapSettings and QgsMapRendererJob (+subclasses) are intended to replace QgsMapRenderer class that existed before QGIS 2.4. The advantage of the new classes is that they separate the settings from the rendering and provide asynchronous API for map rendering.

New in version 2.4: Methods

backgroundColor Get the background color of the map
customRenderFlags Get custom rendering flags.
destinationCrs returns CRS of destination coordinate reference system
ellipsoid Returns ellipsoid’s acronym.
expressionContext Gets the expression context.
extent Return geographical coordinates of the rectangle that should be rendered.
flags Return 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
labelingEngineSettings Returns global configuration of the labeling engine
layerExtentToOutputExtent transform bounding box from layer’s CRS to output CRS
layerIds Get 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 Get 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 Return coordinate transform from layer’s CRS to destination CRS
layers Get 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 Return the magnification factor.
mapToLayerCoordinates transform point coordinates from output CRS to layer’s CRS
mapToPixel
mapUnits Get units of map’s geographical coordinates - used for scale calculation
mapUnitsPerPixel Return the distance in geographical coordinates that equals to one pixel in the map
outputDpi Return DPI used for conversion between real world units (e.
outputExtentToLayerExtent transform bounding box from output CRS to layer’s CRS
outputImageFormat format of internal QImage, default QImage.
outputSize Return the size of the resulting map image
pathResolver Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.
readXml serialization */
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 Get color that is used for drawing of selected vector features
setBackgroundColor Set the background color of the map
setCustomRenderFlags Sets the custom rendering flags.
setDestinationCrs sets destination coordinate reference system
setEllipsoid Sets the ellipsoid by its acronym.
setExpressionContext Sets the expression context.
setExtent Set coordinates of the rectangle which should be rendered.
setFlag Enable or disable a particular flag (other flags are not affected)
setFlags Set combination of flags that will be used for rendering
setLabelingEngineSettings Sets 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 Set DPI used for conversion between real world units (e.
setOutputImageFormat sets format of internal QImage
setOutputSize Set the size of the resulting map image
setPathResolver Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.
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 Set color that is used for drawing of selected vector features
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.
testFlag Check whether a particular flag is enabled
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 Return the actual extent derived from requested extent that takes takes output image size into account
visiblePolygon Return the visible area as a polygon (may be rotated)
writeXml

Signals

Attributes

Antialiasing
DrawEditingInfo
DrawLabeling
DrawSelection
DrawSymbolBounds
ForceVectorOutput
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
RenderMapTile = 256
RenderPartialOutput = 512
RenderPreviewJob = 1024
UseAdvancedEffects = 8
UseRenderingOptimization = 32
backgroundColor(self) → QColor

Get the background color of the map

customRenderFlags(self) → str

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

Returns:custom flags strings, separated by ‘;’

New in version 2.16.

destinationCrs(self) → QgsCoordinateReferenceSystem

returns CRS of destination coordinate reference system

ellipsoid(self) → str

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

New in version 3.0.

See also

setEllipsoid()

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.

extent(self) → QgsRectangle

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

flags(self) → QgsMapSettings.Flags

Return combination of flags used for rendering

fullExtent(self) → QgsRectangle

returns current extent of layer set

hasValidSettings(self) → bool

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

labelingEngineSettings(self) → QgsLabelingEngineSettings

Returns global configuration of the labeling engine

New in version 3.0.

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

transform bounding box from layer’s CRS to output CRS

Returns:a bounding box (aligned rectangle) containing the transformed extent
layerIds(self) → List[str]

Get 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(self) → Dict[str, str]

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

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
Returns:the transformed rectangle
layerToMapUnits(self, layer: QgsMapLayer, referenceExtent: QgsRectangle = QgsRectangle()) → float

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

Parameters:
  • layer – The layer
  • referenceExtent – A reference extent based on which to perform the computation. If not specified, the layer extent is used

New in version 2.12.

layerTransform(self, layer: QgsMapLayer) → QgsCoordinateTransform

Return coordinate transform from layer’s CRS to destination CRS

Parameters:layer
Returns:transform - may be invalid if the transform is not needed
layers(self) → List[QgsMapLayer]

Get 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(self) → float

Return the magnification factor.

New in version 2.16.

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
Returns:the transformed rectangle
mapToPixel(self) → QgsMapToPixel
mapUnits(self) → QgsUnitTypes.DistanceUnit

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

mapUnitsPerPixel(self) → float

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

outputDpi(self) → float

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

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

transform bounding box from output CRS to layer’s CRS

Returns:a bounding box (aligned rectangle) containing the transformed extent
outputImageFormat(self) → QImage.Format

format of internal QImage, default QImage.Format_ARGB32_Premultiplied

outputSize(self) → QSize

Return the size of the resulting map image

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.

readXml(self, node: QDomNode)

serialization */

rotation(self) → float

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

New in version 2.8.

See also

setRotation()

scale(self) → float

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

segmentationTolerance(self) → float

Gets the segmentation tolerance applied when rendering curved geometries

segmentationToleranceType(self) → QgsAbstractGeometry.SegmentationToleranceType

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

selectionColor(self) → QColor

Get color that is used for drawing of selected vector features

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

Set the background color of the map

setCustomRenderFlags(self, customRenderFlags: str)

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

Parameters:customRenderFlags – custom flags strings, separated by ‘;’

New in version 2.16.

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)

sets destination coordinate reference system

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.

Returns:true if ellipsoid was successfully set

New in version 3.0.

See also

ellipsoid()

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.

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.

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

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

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

Set combination of flags that will be used for rendering

setLabelingEngineSettings(self, settings: QgsLabelingEngineSettings)

Sets global configuration of the labeling engine

New in version 3.0.

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.

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

setMagnificationFactor(self, factor: float)

Set the magnification factor.

Parameters:factor – the factor of magnification

New in version 2.16.

setOutputDpi(self, dpi: float)

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

setOutputImageFormat(self, format: QImage.Format)

sets format of internal QImage

setOutputSize(self, size: QSize)

Set the size of the resulting map image

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.

New in version 3.0.

See also

pathResolver()

setRotation(self, rotation: float)

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

New in version 2.8.

See also

rotation()

setSegmentationTolerance(self, tolerance: float)

Sets the segmentation tolerance applied when rendering curved geometries

Parameters:tolerance – the segmentation tolerance*
setSegmentationToleranceType(self, type: QgsAbstractGeometry.SegmentationToleranceType)

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

Parameters:type – the segmentation tolerance typename*
setSelectionColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Set color that is used for drawing of selected vector features

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.

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

Check whether a particular flag is enabled

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.

updateDerived(self)
visibleExtent(self) → QgsRectangle

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

visiblePolygon(self) → QPolygonF

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

New in version 2.8.

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