/
qgsmapsettings.h
601 lines (506 loc) · 22 KB
/
qgsmapsettings.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
/***************************************************************************
qgsmapsettings.h
--------------------------------------
Date : December 2013
Copyright : (C) 2013 by Martin Dobias
Email : wonder dot sk at gmail dot com
***************************************************************************
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License as published by *
* the Free Software Foundation; either version 2 of the License, or *
* (at your option) any later version. *
* *
***************************************************************************/
#ifndef QGSMAPSETTINGS_H
#define QGSMAPSETTINGS_H
#include "qgis_core.h"
#include "qgis_sip.h"
#include <QColor>
#include <QImage>
#include <QPointer>
#include <QSize>
#include <QStringList>
#include "qgsabstractgeometry.h"
#include "qgscoordinatereferencesystem.h"
#include "qgslabelingenginesettings.h"
#include "qgsmaptopixel.h"
#include "qgsrectangle.h"
#include "qgsscalecalculator.h"
#include "qgsexpressioncontext.h"
#include "qgsmaplayer.h"
#include "qgsgeometry.h"
class QPainter;
class QgsCoordinateTransform;
class QgsScaleCalculator;
class QgsMapRendererJob;
/**
* \class QgsLabelBlockingRegion
* \ingroup core
*
* Label blocking region (in map coordinates and CRS).
*
* \since QGIS 3.6
*/
class CORE_EXPORT QgsLabelBlockingRegion
{
public:
/**
* Constructor for a label blocking region
*/
explicit QgsLabelBlockingRegion( const QgsGeometry &geometry )
: geometry( geometry )
{}
//! Geometry of region to avoid placing labels within (in destination map coordinates and CRS)
QgsGeometry geometry;
};
/**
* \ingroup core
* 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.
*
* \since QGIS 2.4
*/
class CORE_EXPORT QgsMapSettings
{
public:
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.
*/
QgsRectangle extent() const;
/**
* 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 setExtent( const QgsRectangle &rect, bool magnified = true );
//! Returns the size of the resulting map image
QSize outputSize() const;
//! Sets the size of the resulting map image
void setOutputSize( QSize size );
/**
* Returns device pixel ratio
* Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
* \since QGIS 3.4
*/
float devicePixelRatio() const;
/**
* Sets the device pixel ratio
* Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
* \since QGIS 3.4
*/
void setDevicePixelRatio( float dpr );
/**
* Returns the device output size of the map canvas
* This is equivalent to the output size multiplicated
* by the device pixel ratio.
* \since QGIS 3.4
*/
QSize deviceOutputSize() const;
/**
* Returns the rotation of the resulting map image, in degrees clockwise.
* \see setRotation()
* \since QGIS 2.8
*/
double rotation() const;
/**
* Sets the \a rotation of the resulting map image, in degrees clockwise.
* \see rotation()
* \since QGIS 2.8
*/
void setRotation( double rotation );
/**
* Returns DPI used for conversion between real world units (e.g. mm) and pixels
* Default value is 96
*/
double outputDpi() const;
//! Sets DPI used for conversion between real world units (e.g. mm) and pixels
void setOutputDpi( double dpi );
/**
* Set the magnification factor.
* \param factor the factor of magnification
* \see magnificationFactor()
* \since QGIS 2.16
*/
void setMagnificationFactor( double factor );
/**
* Returns the magnification factor.
* \see setMagnificationFactor()
* \since QGIS 2.16
*/
double magnificationFactor() const;
/**
* 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)
*/
QStringList layerIds() const;
/**
* 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)
*/
QList<QgsMapLayer *> layers() const;
/**
* 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!).
*/
void setLayers( const QList<QgsMapLayer *> &layers );
/**
* 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
* \since QGIS 2.8
*/
QMap<QString, QString> layerStyleOverrides() const;
/**
* 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
* \since QGIS 2.8
*/
void setLayerStyleOverrides( const QMap<QString, QString> &overrides );
/**
* Gets custom rendering flags. Layers might honour these to alter their rendering.
* \returns custom flags strings, separated by ';'
* \see setCustomRenderFlags()
* \since QGIS 2.16
*/
QString customRenderFlags() const { return mCustomRenderFlags; }
/**
* Sets the custom rendering flags. Layers might honour these to alter their rendering.
* \param customRenderFlags custom flags strings, separated by ';'
* \see customRenderFlags()
* \since QGIS 2.16
*/
void setCustomRenderFlags( const QString &customRenderFlags ) { mCustomRenderFlags = customRenderFlags; }
//! sets destination coordinate reference system
void setDestinationCrs( const QgsCoordinateReferenceSystem &crs );
//! returns CRS of destination coordinate reference system
QgsCoordinateReferenceSystem destinationCrs() const;
//! Gets units of map's geographical coordinates - used for scale calculation
QgsUnitTypes::DistanceUnit mapUnits() const;
/**
* Sets the \a 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
* \see ellipsoid()
* \since QGIS 3.0
*/
bool setEllipsoid( const QString &ellipsoid );
/**
* Returns ellipsoid's acronym. Calculations will only use the
* ellipsoid if a valid ellipsoid has been set.
* \see setEllipsoid()
* \since QGIS 3.0
*/
QString ellipsoid() const { return mEllipsoid; }
//! Sets the background color of the map
void setBackgroundColor( const QColor &color ) { mBackgroundColor = color; }
//! Gets the background color of the map
QColor backgroundColor() const { return mBackgroundColor; }
//! Sets color that is used for drawing of selected vector features
void setSelectionColor( const QColor &color ) { mSelectionColor = color; }
//! Gets color that is used for drawing of selected vector features
QColor selectionColor() const { return mSelectionColor; }
//! Enumeration of flags that adjust the way the map is rendered
enum Flag
{
Antialiasing = 0x01, //!< Enable anti-aliasing for map rendering
DrawEditingInfo = 0x02, //!< Enable drawing of vertex markers for layers in editing mode
ForceVectorOutput = 0x04, //!< Vector graphics should not be cached and drawn as raster images
UseAdvancedEffects = 0x08, //!< Enable layer opacity and blending effects
DrawLabeling = 0x10, //!< Enable drawing of labels on top of the map
UseRenderingOptimization = 0x20, //!< Enable vector simplification and other rendering optimizations
DrawSelection = 0x40, //!< Whether vector selections should be shown in the rendered map
DrawSymbolBounds = 0x80, //!< Draw bounds of symbols (for debugging/testing)
RenderMapTile = 0x100, //!< Draw map such that there are no problems between adjacent tiles
RenderPartialOutput = 0x200, //!< Whether to make extra effort to update map image with partially rendered layers (better for interactive map canvas). Added in QGIS 3.0
RenderPreviewJob = 0x400, //!< Render is a 'canvas preview' render, and shortcuts should be taken to ensure fast rendering
// TODO: ignore scale-based visibility (overview)
};
Q_DECLARE_FLAGS( Flags, Flag )
//! Sets combination of flags that will be used for rendering
void setFlags( QgsMapSettings::Flags flags );
//! Enable or disable a particular flag (other flags are not affected)
void setFlag( Flag flag, bool on = true );
//! Returns combination of flags used for rendering
Flags flags() const;
//! Check whether a particular flag is enabled
bool testFlag( Flag flag ) const;
/**
* Returns the text render format, which dictates how text is rendered (e.g. as paths or real text objects).
*
* \see setTextRenderFormat()
* \since QGIS 3.4.3
*/
QgsRenderContext::TextRenderFormat textRenderFormat() const
{
return mTextRenderFormat;
}
/**
* Sets the text render \a 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 textRenderFormat()
* \since QGIS 3.4.3
*/
void setTextRenderFormat( QgsRenderContext::TextRenderFormat format )
{
mTextRenderFormat = format;
// ensure labeling engine setting is also kept in sync, just in case anyone accesses QgsMapSettings::labelingEngineSettings().defaultTextRenderFormat()
// instead of correctly calling QgsMapSettings::textRenderFormat(). It can't hurt to be consistent!
mLabelingEngineSettings.setDefaultTextRenderFormat( format );
}
//! sets format of internal QImage
void setOutputImageFormat( QImage::Format format ) { mImageFormat = format; }
//! format of internal QImage, default QImage::Format_ARGB32_Premultiplied
QImage::Format outputImageFormat() const { return mImageFormat; }
//! Check whether the map settings are valid and can be used for rendering
bool hasValidSettings() const;
//! Returns the actual extent derived from requested extent that takes takes output image size into account
QgsRectangle visibleExtent() const;
/**
* Returns the visible area as a polygon (may be rotated)
* \since QGIS 2.8
*/
QPolygonF visiblePolygon() const;
//! Returns the distance in geographical coordinates that equals to one pixel in the map
double mapUnitsPerPixel() const;
/**
* Returns the calculated map scale.
* The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
*/
double scale() const;
/**
* Sets the expression context. This context is used for all expression evaluation
* associated with this map settings.
* \see expressionContext()
* \since QGIS 2.12
*/
void setExpressionContext( const QgsExpressionContext &context ) { mExpressionContext = context; }
/**
* Gets the expression context. This context should be used for all expression evaluation
* associated with this map settings.
* \see setExpressionContext()
* \since QGIS 2.12
*/
const QgsExpressionContext &expressionContext() const { return mExpressionContext; }
/**
* 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 setTransformContext()
* \since QGIS 3.0
*/
QgsCoordinateTransformContext transformContext() const;
/**
* Sets the coordinate transform \a context, which stores various
* information regarding which datum transforms should be used when transforming points
* from a source to destination coordinate reference system.
*
* \see transformContext()
* \since QGIS 3.0
*/
void setTransformContext( const QgsCoordinateTransformContext &context );
/**
* Returns the path resolver for conversion between relative and absolute paths
* during rendering operations, e.g. for resolving relative symbol paths.
*
* \see setPathResolver()
* \since QGIS 3.0
*/
const QgsPathResolver &pathResolver() const { return mPathResolver; }
/**
* Sets the path \a resolver for conversion between relative and absolute paths
* during rendering operations, e.g. for resolving relative symbol paths.
*
* \see pathResolver()
* \since QGIS 3.0
*/
void setPathResolver( const QgsPathResolver &resolver ) { mPathResolver = resolver; }
const QgsMapToPixel &mapToPixel() const { return mMapToPixel; }
/**
* Computes an *estimated* conversion factor between layer and map units: layerUnits * layerToMapUnits = mapUnits
* \param layer The layer
* \param referenceExtent A reference extent based on which to perform the computation. If not specified, the layer extent is used
* \since QGIS 2.12
*/
double layerToMapUnits( const QgsMapLayer *layer, const QgsRectangle &referenceExtent = QgsRectangle() ) const;
/**
* \brief transform bounding box from layer's CRS to output CRS
* \see layerToMapCoordinates( const QgsMapLayer *, QgsRectangle ) const if you want to transform a rectangle
* \returns a bounding box (aligned rectangle) containing the transformed extent
*/
QgsRectangle layerExtentToOutputExtent( const QgsMapLayer *layer, QgsRectangle extent ) const;
/**
* \brief transform bounding box from output CRS to layer's CRS
* \see mapToLayerCoordinates( const QgsMapLayer *, QgsRectangle ) const if you want to transform a rectangle
* \returns a bounding box (aligned rectangle) containing the transformed extent
*/
QgsRectangle outputExtentToLayerExtent( const QgsMapLayer *layer, QgsRectangle extent ) const;
/**
* \brief transform point coordinates from layer's CRS to output CRS
* \returns the transformed point
*/
QgsPointXY layerToMapCoordinates( const QgsMapLayer *layer, QgsPointXY point ) const;
/**
* \brief transform rectangle from layer's CRS to output CRS
* \see layerExtentToOutputExtent() if you want to transform a bounding box
* \returns the transformed rectangle
*/
QgsRectangle layerToMapCoordinates( const QgsMapLayer *layer, QgsRectangle rect ) const;
/**
* \brief transform point coordinates from output CRS to layer's CRS
* \returns the transformed point
*/
QgsPointXY mapToLayerCoordinates( const QgsMapLayer *layer, QgsPointXY point ) const;
/**
* \brief transform rectangle from output CRS to layer's CRS
* \see outputExtentToLayerExtent() if you want to transform a bounding box
* \returns the transformed rectangle
*/
QgsRectangle mapToLayerCoordinates( const QgsMapLayer *layer, QgsRectangle rect ) const;
/**
* Returns the coordinate transform from layer's CRS to destination CRS
* \returns transform - may be invalid if the transform is not needed
*/
QgsCoordinateTransform layerTransform( const QgsMapLayer *layer ) const;
//! returns current extent of layer set
QgsRectangle fullExtent() const;
/* serialization */
void readXml( QDomNode &node );
void writeXml( QDomNode &node, QDomDocument &doc );
/**
* Sets the segmentation tolerance applied when rendering curved geometries
\param tolerance the segmentation tolerance*/
void setSegmentationTolerance( double tolerance ) { mSegmentationTolerance = tolerance; }
//! Gets the segmentation tolerance applied when rendering curved geometries
double segmentationTolerance() const { return mSegmentationTolerance; }
/**
* Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
\param type the segmentation tolerance typename*/
void setSegmentationToleranceType( QgsAbstractGeometry::SegmentationToleranceType type ) { mSegmentationToleranceType = type; }
//! Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
QgsAbstractGeometry::SegmentationToleranceType segmentationToleranceType() const { return mSegmentationToleranceType; }
/**
* 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 \a settings.
*
* \see labelingEngineSettings()
*
* \since QGIS 3.0
*/
void setLabelingEngineSettings( const QgsLabelingEngineSettings &settings )
{
mLabelingEngineSettings = settings;
mTextRenderFormat = settings.defaultTextRenderFormat();
}
/**
* Returns the global configuration of the labeling engine.
*
* \see setLabelingEngineSettings()
*
* \since QGIS 3.0
*/
const QgsLabelingEngineSettings &labelingEngineSettings() const { return mLabelingEngineSettings; }
/**
* 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 setLabelBoundaryGeometry()
* \see labelBlockingRegions()
* \since QGIS 3.6
*/
QgsGeometry labelBoundaryGeometry() const;
/**
* Sets the label \a boundary geometry, which restricts where in the rendered map labels are permitted to be
* placed.
*
* A null \a 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 labelBoundaryGeometry()
* \see setLabelBlockingRegions()
* \since QGIS 3.6
*/
void setLabelBoundaryGeometry( const QgsGeometry &boundary );
/**
* Sets a list of \a regions to avoid placing labels within.
* \since QGIS 3.6
* \see labelBlockingRegions()
* \see setLabelBoundaryGeometry()
*/
void setLabelBlockingRegions( const QList< QgsLabelBlockingRegion > ®ions ) { mLabelBlockingRegions = regions; }
/**
* Returns the list of regions to avoid placing labels within.
* \since QGIS 3.6
* \see setLabelBlockingRegions()
* \see labelBoundaryGeometry()
*/
QList< QgsLabelBlockingRegion > labelBlockingRegions() const { return mLabelBlockingRegions; }
protected:
double mDpi;
QSize mSize;
float mDevicePixelRatio = 1.0;
QgsRectangle mExtent;
double mRotation = 0.0;
double mMagnificationFactor = 1.0;
//! list of layers to be rendered (stored as weak pointers)
QgsWeakMapLayerPointerList mLayers;
QMap<QString, QString> mLayerStyleOverrides;
QString mCustomRenderFlags;
QgsExpressionContext mExpressionContext;
QgsCoordinateReferenceSystem mDestCRS;
//! ellipsoid acronym (from table tbl_ellipsoids)
QString mEllipsoid;
QColor mBackgroundColor;
QColor mSelectionColor;
Flags mFlags;
QImage::Format mImageFormat = QImage::Format_ARGB32_Premultiplied;
double mSegmentationTolerance;
QgsAbstractGeometry::SegmentationToleranceType mSegmentationToleranceType = QgsAbstractGeometry::MaximumAngle;
QgsLabelingEngineSettings mLabelingEngineSettings;
// derived properties
bool mValid = false; //!< Whether the actual settings are valid (set in updateDerived())
QgsRectangle mVisibleExtent; //!< Extent with some additional white space that matches the output aspect ratio
double mMapUnitsPerPixel = 1;
double mScale = 1;
// utiity stuff
QgsScaleCalculator mScaleCalculator;
QgsMapToPixel mMapToPixel;
QgsCoordinateTransformContext mTransformContext;
QgsPathResolver mPathResolver;
QgsRenderContext::TextRenderFormat mTextRenderFormat = QgsRenderContext::TextFormatAlwaysOutlines;
QgsGeometry mLabelBoundaryGeometry;
#ifdef QGISDEBUG
bool mHasTransformContext = false;
#endif
void updateDerived();
private:
QList< QgsLabelBlockingRegion > mLabelBlockingRegions;
};
Q_DECLARE_OPERATORS_FOR_FLAGS( QgsMapSettings::Flags )
#endif // QGSMAPSETTINGS_H