Class: QgsMapSettings¶
-
class
qgis.core.
QgsMapSettings
¶ Bases:
sip.wrapper
The
QgsMapSettings
class contains configuration for rendering of the map. The rendering itself is done byQgsMapRendererJob
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
Gets the background color of the map
Gets custom rendering flags.
returns CRS of destination coordinate reference system
Returns the device output size of the map canvas This is equivalent to the output size multiplicated by the device pixel ratio.
Returns device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi “retina” displays.
Returns ellipsoid’s acronym.
Gets the expression context.
Returns geographical coordinates of the rectangle that should be rendered.
Returns combination of flags used for rendering
returns current extent of layer set
Check whether the map settings are valid and can be used for rendering
Returns the global configuration of the labeling engine.
transform bounding box from layer’s CRS to output CRS
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)
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
transform point coordinates from layer’s CRS to output CRS
Computes an estimated conversion factor between layer and map units: layerUnits * layerToMapUnits = mapUnits
Returns the coordinate transform from layer’s CRS to destination CRS
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)
Returns the magnification factor.
transform point coordinates from output CRS to layer’s CRS
- rtype
QgsMapToPixel
Gets units of map’s geographical coordinates - used for scale calculation
Returns the distance in geographical coordinates that equals to one pixel in the map
Returns DPI used for conversion between real world units (e.g.
transform bounding box from output CRS to layer’s CRS
format of internal QImage, default QImage.Format_ARGB32_Premultiplied
Returns the size of the resulting map image
Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
serialization */
Returns the rotation of the resulting map image, in degrees clockwise.
Returns the calculated map scale.
Gets the segmentation tolerance applied when rendering curved geometries
Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
Gets color that is used for drawing of selected vector features
Sets the background color of the map
Sets the custom rendering flags.
sets destination coordinate reference system
Sets the device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi “retina” displays.
Sets the
ellipsoid
by its acronym.Sets the expression context.
Set coordinates of the rectangle which should be rendered.
Enable or disable a particular flag (other flags are not affected)
Sets combination of flags that will be used for rendering
Sets the global configuration of the labeling engine.
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
Set list of layers for map rendering.
Set the magnification factor.
Sets DPI used for conversion between real world units (e.g.
sets format of internal QImage
Sets the size of the resulting map image
Sets the path
resolver
for conversion between relative and absolute paths during rendering operations, e.g.Sets the
rotation
of the resulting map image, in degrees clockwise.Sets the segmentation tolerance applied when rendering curved geometries
Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
Sets color that is used for drawing of selected vector features
Sets the text render
format
, which dictates how text is rendered (e.g.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.Check whether a particular flag is enabled
Returns the text render format, which dictates how text is rendered (e.g.
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.
Returns the actual extent derived from requested extent that takes takes output image size into account
Returns the visible area as a polygon (may be rotated)
- param node
Attributes
-
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¶ 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 ‘;’
See also
New in version 2.16.
-
destinationCrs
(self) → QgsCoordinateReferenceSystem¶ returns CRS of destination coordinate reference system
- Return type
-
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
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
New in version 2.12.
- Return type
-
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
-
flags
(self) → QgsMapSettings.Flags¶ Returns combination of flags used for rendering
- Return type
-
fullExtent
(self) → QgsRectangle¶ returns current extent of layer set
- Return type
-
hasValidSettings
(self) → bool¶ Check whether the map settings are valid and can be used for rendering
- Return type
bool
-
labelingEngineSettings
(self) → QgsLabelingEngineSettings¶ Returns the global configuration of the labeling engine.
See also
New in version 3.0.
- Return type
-
layerExtentToOutputExtent
(self, layer: QgsMapLayer, extent: QgsRectangle) → QgsRectangle¶ transform bounding box from layer’s CRS to output CRS
See also
- Return type
- Returns
a bounding box (aligned rectangle) containing the transformed extent
- Parameters
layer (QgsMapLayer) –
extent (QgsRectangle) –
-
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 CRSSee also
- Return type
- 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
- 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.
See also
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 CRSSee also
- Return type
- Returns
the transformed rectangle
- Parameters
layer (QgsMapLayer) –
point (QgsPointXY) –
-
mapToPixel
(self) → QgsMapToPixel¶ - Return type
-
mapUnits
(self) → QgsUnitTypes.DistanceUnit¶ Gets units of map’s geographical coordinates - used for scale calculation
- Return type
-
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
See also
- Return type
- 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
- 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
New in version 3.0.
- Return type
-
rotation
(self) → float¶ Returns the rotation of the resulting map image, in degrees clockwise.
See also
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
-
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 ‘;’
See also
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 usingQgsEllipsoidUtils.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
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
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
rect (QgsRectangle) –
magnified (bool = True) –
-
setFlag
(self, flag: QgsMapSettings.Flag, on: bool = True)¶ Enable or disable a particular flag (other flags are not affected)
- Parameters
flag (QgsMapSettings.Flag) –
on (bool = True) –
-
setFlags
(self, flags: Union[QgsMapSettings.Flags, QgsMapSettings.Flag])¶ Sets combination of flags that will be used for rendering
- Parameters
flags (Union[QgsMapSettings.Flags) –
-
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
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
See also
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
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
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) –
-
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.
See also
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.See also
New in version 3.0.
- Parameters
context (QgsCoordinateTransformContext) –
-
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).
See also
New in version 3.4.3.
- Return type
-
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
New in version 3.0.
- Return type
-
updateDerived
(self)¶
-
visibleExtent
(self) → QgsRectangle¶ Returns the actual extent derived from requested extent that takes takes output image size into account
- Return type
-
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) –