QgsMapSettings class
The QgsMapSettings class contains configuration for rendering of the map.
Contents
- Reference
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.
Public types
- enum Flag { Antialiasing = 0x01, DrawEditingInfo = 0x02, ForceVectorOutput = 0x04, UseAdvancedEffects = 0x08, DrawLabeling = 0x10, UseRenderingOptimization = 0x20, DrawSelection = 0x40, DrawSymbolBounds = 0x80, RenderMapTile = 0x100, RenderPartialOutput = 0x200, RenderPreviewJob = 0x400 }
- Enumeration of flags that adjust the way the map is rendered.
Public functions
- auto backgroundColor() const -> QColor
- Gets the background color of the map.
- auto customRenderFlags() const -> QString
- Gets custom rendering flags.
- auto destinationCrs() const -> QgsCoordinateReferenceSystem
- returns CRS of destination coordinate reference system
- auto deviceOutputSize() const -> QSize
- Returns the device output size of the map canvas This is equivalent to the output size multiplicated by the device pixel ratio.
- auto devicePixelRatio() const -> float
- Returns device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
- auto ellipsoid() const -> QString
- Returns ellipsoid's acronym.
- auto expressionContext() const -> const QgsExpressionContext&
- Gets the expression context.
- auto extent() const -> QgsRectangle
- Returns geographical coordinates of the rectangle that should be rendered.
- auto flags() const -> Flags
- Returns combination of flags used for rendering.
- auto fullExtent() const -> QgsRectangle
- returns current extent of layer set
- auto hasValidSettings() const -> bool
- Check whether the map settings are valid and can be used for rendering.
- auto labelBlockingRegions() const -> QList<QgsLabelBlockingRegion>
- Returns the list of regions to avoid placing labels within.
- auto labelBoundaryGeometry() const -> QgsGeometry
- Returns the label boundary geometry, which restricts where in the rendered map labels are permitted to be placed.
- auto labelingEngineSettings() const -> const QgsLabelingEngineSettings&
- Returns the global configuration of the labeling engine.
- auto layerExtentToOutputExtent(const QgsMapLayer* layer, QgsRectangle extent) const -> QgsRectangle
- transform bounding box from layer's CRS to output CRS
- auto layerIds() const -> QStringList
- 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)
- auto layers() const -> QList<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)
- auto layerStyleOverrides() const -> QMap<QString, QString>
- 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.
- auto layerToMapCoordinates(const QgsMapLayer* layer, QgsPointXY point) const -> QgsPointXY
- transform point coordinates from layer's CRS to output CRS
- auto layerToMapCoordinates(const QgsMapLayer* layer, QgsRectangle rect) const -> QgsRectangle
- transform rectangle from layer's CRS to output CRS
- auto layerToMapUnits(const QgsMapLayer* layer, const QgsRectangle& referenceExtent = QgsRectangle()) const -> double
- Computes an estimated conversion factor between layer and map units: layerUnits * layerToMapUnits = mapUnits.
- auto layerTransform(const QgsMapLayer* layer) const -> QgsCoordinateTransform
- Returns the coordinate transform from layer's CRS to destination CRS.
- auto magnificationFactor() const -> double
- Returns the magnification factor.
- auto mapToLayerCoordinates(const QgsMapLayer* layer, QgsPointXY point) const -> QgsPointXY
- transform point coordinates from output CRS to layer's CRS
- auto mapToLayerCoordinates(const QgsMapLayer* layer, QgsRectangle rect) const -> QgsRectangle
- transform rectangle from output CRS to layer's CRS
-
auto mapUnits() const -> QgsUnitTypes::
DistanceUnit - Gets units of map's geographical coordinates - used for scale calculation.
- auto mapUnitsPerPixel() const -> double
- Returns the distance in geographical coordinates that equals to one pixel in the map.
- auto outputDpi() const -> double
- Returns DPI used for conversion between real world units (e.g.
- auto outputExtentToLayerExtent(const QgsMapLayer* layer, QgsRectangle extent) const -> QgsRectangle
- transform bounding box from output CRS to layer's CRS
- auto outputImageFormat() const -> QImage::Format
- format of internal QImage, default QImage::Format_ARGB32_Premultiplied
- auto outputSize() const -> QSize
- Returns the size of the resulting map image.
- auto pathResolver() const -> const QgsPathResolver&
- Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
- auto rotation() const -> double
- Returns the rotation of the resulting map image, in degrees clockwise.
- auto scale() const -> double
- Returns the calculated map scale.
- auto segmentationTolerance() const -> double
- Gets the segmentation tolerance applied when rendering curved geometries.
-
auto segmentationToleranceType() const -> QgsAbstractGeometry::
SegmentationToleranceType - Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
- auto selectionColor() const -> QColor
- Gets color that is used for drawing of selected vector features.
- void setBackgroundColor(const QColor& color)
- Sets the background color of the map.
- void setCustomRenderFlags(const QString& customRenderFlags)
- Sets the custom rendering flags.
- void setDestinationCrs(const QgsCoordinateReferenceSystem& crs)
- sets destination coordinate reference system
- void setDevicePixelRatio(float dpr)
- Sets the device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
- auto setEllipsoid(const QString& ellipsoid) -> bool
- Sets the ellipsoid by its acronym.
- void setExpressionContext(const QgsExpressionContext& context)
- Sets the expression context.
- void setExtent(const QgsRectangle& rect, bool magnified = true)
- Set coordinates of the rectangle which should be rendered.
- void setFlag(Flag flag, bool on = true)
- Enable or disable a particular flag (other flags are not affected)
- void setFlags(QgsMapSettings::Flags flags)
- Sets combination of flags that will be used for rendering.
- void setLabelBlockingRegions(const QList<QgsLabelBlockingRegion>& regions)
- Sets a list of regions to avoid placing labels within.
- void setLabelBoundaryGeometry(const QgsGeometry& boundary)
- Sets the label boundary geometry, which restricts where in the rendered map labels are permitted to be placed.
- void setLabelingEngineSettings(const QgsLabelingEngineSettings& settings)
- Sets the global configuration of the labeling engine.
- void setLayers(const QList<QgsMapLayer*>& layers)
- Set list of layers for map rendering.
- void setLayerStyleOverrides(const QMap<QString, QString>& overrides)
- 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.
- void setMagnificationFactor(double factor)
- Set the magnification factor.
- void setOutputDpi(double dpi)
- Sets DPI used for conversion between real world units (e.g. mm) and pixels.
- void setOutputImageFormat(QImage::Format format)
- sets format of internal QImage
- void setOutputSize(QSize size)
- Sets the size of the resulting map image.
- void setPathResolver(const QgsPathResolver& resolver)
- Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
- void setRotation(double rotation)
- Sets the rotation of the resulting map image, in degrees clockwise.
- void setSegmentationTolerance(double tolerance)
- Sets the segmentation tolerance applied when rendering curved geometries.
-
void setSegmentationToleranceType(QgsAbstractGeometry::
SegmentationToleranceType type) - Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
- void setSelectionColor(const QColor& color)
- Sets color that is used for drawing of selected vector features.
-
void setTextRenderFormat(QgsRenderContext::
TextRenderFormat format) - Sets the text render format, which dictates how text is rendered (e.g.
- void setTransformContext(const QgsCoordinateTransformContext& context)
- 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.
- auto testFlag(Flag flag) const -> bool
- Check whether a particular flag is enabled.
-
auto textRenderFormat() const -> QgsRenderContext::
TextRenderFormat - Returns the text render format, which dictates how text is rendered (e.g.
- auto transformContext() const -> 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.
- auto visibleExtent() const -> QgsRectangle
- Returns the actual extent derived from requested extent that takes takes output image size into account.
- auto visiblePolygon() const -> QPolygonF
- Returns the visible area as a polygon (may be rotated)
Protected variables
- QString mEllipsoid
- ellipsoid acronym (from table tbl_ellipsoids)
- QgsWeakMapLayerPointerList mLayers
- list of layers to be rendered (stored as weak pointers)
- bool mValid
- Whether the actual settings are valid (set in updateDerived())
- QgsRectangle mVisibleExtent
- Extent with some additional white space that matches the output aspect ratio.
Enum documentation
enum QgsMapSettings::
Enumeration of flags that adjust the way the map is rendered.
| Enumerators | |
|---|---|
| Antialiasing |
Enable anti-aliasing for map rendering. |
| DrawEditingInfo |
Enable drawing of vertex markers for layers in editing mode. |
| ForceVectorOutput |
Vector graphics should not be cached and drawn as raster images. |
| UseAdvancedEffects |
Enable layer opacity and blending effects. |
| DrawLabeling |
Enable drawing of labels on top of the map. |
| UseRenderingOptimization |
Enable vector simplification and other rendering optimizations. |
| DrawSelection |
Whether vector selections should be shown in the rendered map. |
| DrawSymbolBounds |
Draw bounds of symbols (for debugging/testing) |
| RenderMapTile |
Draw map such that there are no problems between adjacent tiles. |
| RenderPartialOutput |
Whether to make extra effort to update map image with partially rendered layers (better for interactive map canvas). Added in QGIS 3.0. |
| RenderPreviewJob |
Render is a 'canvas preview' render, and shortcuts should be taken to ensure fast rendering. |
Function documentation
QString QgsMapSettings::
Gets custom rendering flags.
| Returns | custom flags strings, separated by ';' |
|---|
Layers might honour these to alter their rendering.
QSize QgsMapSettings::
Returns the device output size of the map canvas This is equivalent to the output size multiplicated by the device pixel ratio.
float QgsMapSettings::
Returns device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
QString QgsMapSettings::
Returns ellipsoid's acronym.
Calculations will only use the ellipsoid if a valid ellipsoid has been set.
const QgsExpressionContext& QgsMapSettings::
Gets the expression context.
This context should be used for all expression evaluation associated with this map settings.
QgsRectangle QgsMapSettings::
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.
QList<QgsLabelBlockingRegion> QgsMapSettings::
Returns the list of regions to avoid placing labels within.
QgsGeometry QgsMapSettings::
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().
const QgsLabelingEngineSettings& QgsMapSettings::
Returns the global configuration of the labeling engine.
QgsRectangle QgsMapSettings::
transform bounding box from layer's CRS to output CRS
| Returns | a bounding box (aligned rectangle) containing the transformed extent |
|---|
QMap<QString, QString> QgsMapSettings::
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.
QgsPointXY QgsMapSettings::
transform point coordinates from layer's CRS to output CRS
| Returns | the transformed point |
|---|
QgsRectangle QgsMapSettings::
transform rectangle from layer's CRS to output CRS
| Returns | the transformed rectangle |
|---|
double QgsMapSettings::
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 |
QgsCoordinateTransform QgsMapSettings::
Returns the coordinate transform from layer's CRS to destination CRS.
| Returns | transform - may be invalid if the transform is not needed |
|---|
double QgsMapSettings::
Returns the magnification factor.
QgsPointXY QgsMapSettings::
transform point coordinates from output CRS to layer's CRS
| Returns | the transformed point |
|---|
QgsRectangle QgsMapSettings::
transform rectangle from output CRS to layer's CRS
| Returns | the transformed rectangle |
|---|
double QgsMapSettings::
Returns DPI used for conversion between real world units (e.g.
mm) and pixels Default value is 96
QgsRectangle QgsMapSettings::
transform bounding box from output CRS to layer's CRS
| Returns | a bounding box (aligned rectangle) containing the transformed extent |
|---|
const QgsPathResolver& QgsMapSettings::
Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
for resolving relative symbol paths.
double QgsMapSettings::
Returns the rotation of the resulting map image, in degrees clockwise.
double QgsMapSettings::
Returns the calculated map scale.
The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
void QgsMapSettings::
Sets the custom rendering flags.
| Parameters | |
|---|---|
| customRenderFlags | custom flags strings, separated by ';' |
Layers might honour these to alter their rendering.
void QgsMapSettings::
Sets the device pixel ratio Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
bool QgsMapSettings::
Sets the ellipsoid by its acronym.
| Returns | true if ellipsoid was successfully set |
|---|
Known ellipsoid acronyms can be retrieved using QgsEllipsoidUtils::
void QgsMapSettings::
Sets the expression context.
This context is used for all expression evaluation associated with this map settings.
void QgsMapSettings::
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.
void QgsMapSettings::
Sets a list of regions to avoid placing labels within.
void QgsMapSettings::
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().
void QgsMapSettings::
Sets the global configuration of the labeling engine.
void QgsMapSettings::
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)
void QgsMapSettings::
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.
void QgsMapSettings::
Set the magnification factor.
| Parameters | |
|---|---|
| factor | the factor of magnification |
void QgsMapSettings::
Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
for resolving relative symbol paths.
void QgsMapSettings::
Sets the rotation of the resulting map image, in degrees clockwise.
void QgsMapSettings::
Sets the segmentation tolerance applied when rendering curved geometries.
| Parameters | |
|---|---|
| tolerance | the segmentation tolerance |
void QgsMapSettings::
Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
| Parameters | |
|---|---|
| type | the segmentation tolerance typename |
void QgsMapSettings::
Sets the text render format, which dictates how text is rendered (e.g.
as paths or real text objects).
void QgsMapSettings::
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.
QgsRenderContext::
Returns the text render format, which dictates how text is rendered (e.g.
as paths or real text objects).
QgsCoordinateTransformContext QgsMapSettings::
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.
QPolygonF QgsMapSettings::
Returns the visible area as a polygon (may be rotated)