Using the Map Canvas¶
Avertissement
Despite our constant efforts, information beyond this line may not be updated for QGIS 3. Refer to https://qgis.org/pyqgis/master for the python API documentation or, give a hand to update the chapters you know about. Thanks.
The Map canvas widget is probably the most important widget within QGIS because it shows the map composed from overlaid map layers and allows interaction with the map and layers. The canvas always shows a part of the map defined by the current canvas extent. The interaction is done through the use of map tools: there are tools for panning, zooming, identifying layers, measuring, vector editing and others. Similar to other graphics programs, there is always one tool active and the user can switch between the available tools.
The map canvas is implemented with the QgsMapCanvas
class in the qgis.gui
module. The implementation is based on the Qt Graphics View framework.
This framework generally provides a surface and a view where custom graphics
items are placed and user can interact with them. We will assume that you are
familiar enough with Qt to understand the concepts of the graphics scene, view
and items. If not, please read the overview of the framework.
Whenever the map has been panned, zoomed in/out (or some other action that triggers
a refresh), the map is rendered again within the current extent. The layers are
rendered to an image (using the QgsMapRendererJob
class) and that image is
displayed on the canvas. The QgsMapCanvas
class also controls refreshing
of the rendered map. Besides this item which acts as a background, there may be more map canvas items.
Typical map canvas items are rubber bands (used for measuring, vector editing
etc.) or vertex markers. The canvas items are usually used to give visual
feedback for map tools, for example, when creating a new polygon, the map tool
creates a rubber band canvas item that shows the current shape of the polygon.
All map canvas items are subclasses of QgsMapCanvasItem
which adds
some more functionality to the basic QGraphicsItem
objects.
Pour résumer, l’architecture du canevas de carte repose sur trois concepts:
le canevas de carte — pour visualiser la carte
map canvas items — additional items that can be displayed on the map canvas
map tools — for interaction with the map canvas
Intégrer un canevas de carte¶
Le canevas de carte est un objet comme tous les autres objets Qt, on peut donc l’utiliser simplement en le créant et en l’affichant:
canvas = QgsMapCanvas()
canvas.show()
This produces a standalone window with map canvas. It can be also embedded into
an existing widget or window. When using .ui
files and Qt Designer, place a
QWidget
on the form and promote it to a new class: set QgsMapCanvas
as
class name and set qgis.gui
as header file. The pyuic5
utility will
take care of it. This is a very convenient way of embedding the canvas. The
other possibility is to manually write the code to construct map canvas and
other widgets (as children of a main window or dialog) and create a layout.
Par défaut, le canevas de carte a un arrière-plan noir et n’utilise pas l’anticrénelage. Pour afficher un arrière-plan blanc et activer l’anticrénelage pour un rendu plus lisse:
canvas.setCanvasColor(Qt.white)
canvas.enableAntiAliasing(True)
(In case you are wondering, Qt
comes from PyQt.QtCore
module and
Qt.white
is one of the predefined QColor
instances.)
Now it is time to add some map layers. We will first open a layer and add it to the current project. Then we will set the canvas extent and set the list of layers for canvas
path_to_ports_layer = os.path.join(QgsProject.instance().homePath(),
"data", "ports", "ports.shp")
vlayer = QgsVectorLayer(path_to_ports_layer, "Ports layer", "ogr")
if not vlayer.isValid():
print("Layer failed to load!")
# add layer to the registry
QgsProject.instance().addMapLayer(vlayer)
# set extent to the extent of our layer
canvas.setExtent(vlayer.extent())
# set the map canvas layer set
canvas.setLayers([vlayer])
Après exécution de ces commandes, le canevas de carte devrait afficher la couche chargée.
Contour d’édition et symboles de sommets¶
To show some additional data on top of the map in canvas, use map canvas items.
It is possible to create custom canvas item classes (covered below), however
there are two useful canvas item classes for convenience:
QgsRubberBand
for drawing polylines or polygons, and
QgsVertexMarker
for drawing points. They both work with map
coordinates, so the shape is moved/scaled automatically when the canvas is
being panned or zoomed.
Pour afficher une polyligne:
r = QgsRubberBand(canvas, False) # False = not a polygon
points = [QgsPoint(-100, 45), QgsPoint(10, 60), QgsPoint(120, 45)]
r.setToGeometry(QgsGeometry.fromPolyline(points), None)
Pour afficher un polygone:
r = QgsRubberBand(canvas, True) # True = a polygon
points = [[QgsPointXY(-100, 35), QgsPointXY(10, 50), QgsPointXY(120, 35)]]
r.setToGeometry(QgsGeometry.fromPolygonXY(points), None)
Veuillez noter que les points d’un polygone ne sont pas stockés dans une liste. En fait, il s’agit d’une liste d’anneaux contenants les anneaux linéaires du polygones: le premier anneau est la limite extérieure, les autres (optionnels) anneaux correspondent aux trous dans le polygone.
Les contours d’édition peut être personnalisés pour changer leur couleur ou la taille de la ligne:
r.setColor(QColor(0, 0, 255))
r.setWidth(3)
The canvas items are bound to the canvas scene. To temporarily hide them (and
show them again), use the hide()
and show()
combo. To completely remove
the item, you have to remove it from the scene of the canvas
canvas.scene().removeItem(r)
(en C++, il est possible de juste supprimer l’objet mais sous Python del r
détruira juste la référence et l’objet existera toujours étant donné qu’il appartient au canevas).
Rubber band can be also used for drawing points, but the
QgsVertexMarker
class is better suited for this
(QgsRubberBand
would only draw a rectangle around the desired point).
You can use the vertex marker like this:
m = QgsVertexMarker(canvas)
m.setCenter(QgsPointXY(10,40))
This will draw a red cross on position [10,45]. It is possible to customize the icon type, size, color and pen width
m.setColor(QColor(0, 255, 0))
m.setIconSize(5)
m.setIconType(QgsVertexMarker.ICON_BOX) # or ICON_CROSS, ICON_X
m.setPenWidth(3)
For temporary hiding of vertex markers and removing them from canvas, use the same methods as for rubber bands.
Utiliser les outils cartographiques avec le canevas¶
The following example constructs a window that contains a map canvas and basic
map tools for map panning and zooming. Actions are created for activation of
each tool: panning is done with QgsMapToolPan
, zooming in/out with a
pair of QgsMapToolZoom
instances. The actions are set as checkable and
later assigned to the tools to allow automatic handling of checked/unchecked
state of the actions – when a map tool gets activated, its action is marked as
selected and the action of the previous map tool is deselected. The map tools
are activated using setMapTool()
method.
from qgis.gui import *
from qgis.PyQt.QtWidgets import QAction, QMainWindow
from qgis.PyQt.QtCore import Qt
class MyWnd(QMainWindow):
def __init__(self, layer):
QMainWindow.__init__(self)
self.canvas = QgsMapCanvas()
self.canvas.setCanvasColor(Qt.white)
self.canvas.setExtent(layer.extent())
self.canvas.setLayers([layer])
self.setCentralWidget(self.canvas)
self.actionZoomIn = QAction("Zoom in", self)
self.actionZoomOut = QAction("Zoom out", self)
self.actionPan = QAction("Pan", self)
self.actionZoomIn.setCheckable(True)
self.actionZoomOut.setCheckable(True)
self.actionPan.setCheckable(True)
self.actionZoomIn.triggered.connect(self.zoomIn)
self.actionZoomOut.triggered.connect(self.zoomOut)
self.actionPan.triggered.connect(self.pan)
self.toolbar = self.addToolBar("Canvas actions")
self.toolbar.addAction(self.actionZoomIn)
self.toolbar.addAction(self.actionZoomOut)
self.toolbar.addAction(self.actionPan)
# create the map tools
self.toolPan = QgsMapToolPan(self.canvas)
self.toolPan.setAction(self.actionPan)
self.toolZoomIn = QgsMapToolZoom(self.canvas, False) # false = in
self.toolZoomIn.setAction(self.actionZoomIn)
self.toolZoomOut = QgsMapToolZoom(self.canvas, True) # true = out
self.toolZoomOut.setAction(self.actionZoomOut)
self.pan()
def zoomIn(self):
self.canvas.setMapTool(self.toolZoomIn)
def zoomOut(self):
self.canvas.setMapTool(self.toolZoomOut)
def pan(self):
self.canvas.setMapTool(self.toolPan)
You can try the above code in the Python console editor. To invoke the canvas window,
add the following lines to instantiate the MyWnd
class. They will render the currently
selected layer on the newly created canvas
w = MyWnd(iface.activeLayer())
w.show()
Ecrire des outils cartographiques personnalisés¶
You can write your custom tools, to implement a custom behavior to actions performed by users on the canvas.
Map tools should inherit from the QgsMapTool
,
class or any derived class, and selected as active tools in the canvas using
the setMapTool()
method as we have already seen.
Voici un exemple d’outil cartographique qui permet de définir une emprise rectangulaire en cliquant et en déplaçant la souris sur le canevas. Lorsque le rectangle est dessiné, il exporte les coordonnées de ses limites dans la console. On utilise des éléments de contour d’édition décrits auparavant pour afficher le rectangle sélectionné au fur et à mesure de son dessin.
class RectangleMapTool(QgsMapToolEmitPoint):
def __init__(self, canvas):
self.canvas = canvas
QgsMapToolEmitPoint.__init__(self, self.canvas)
self.rubberBand = QgsRubberBand(self.canvas, True)
self.rubberBand.setColor(Qt.red)
self.rubberBand.setWidth(1)
self.reset()
def reset(self):
self.startPoint = self.endPoint = None
self.isEmittingPoint = False
self.rubberBand.reset(True)
def canvasPressEvent(self, e):
self.startPoint = self.toMapCoordinates(e.pos())
self.endPoint = self.startPoint
self.isEmittingPoint = True
self.showRect(self.startPoint, self.endPoint)
def canvasReleaseEvent(self, e):
self.isEmittingPoint = False
r = self.rectangle()
if r is not None:
print("Rectangle:", r.xMinimum(),
r.yMinimum(), r.xMaximum(), r.yMaximum()
)
def canvasMoveEvent(self, e):
if not self.isEmittingPoint:
return
self.endPoint = self.toMapCoordinates(e.pos())
self.showRect(self.startPoint, self.endPoint)
def showRect(self, startPoint, endPoint):
self.rubberBand.reset(QGis.Polygon)
if startPoint.x() == endPoint.x() or startPoint.y() == endPoint.y():
return
point1 = QgsPoint(startPoint.x(), startPoint.y())
point2 = QgsPoint(startPoint.x(), endPoint.y())
point3 = QgsPoint(endPoint.x(), endPoint.y())
point4 = QgsPoint(endPoint.x(), startPoint.y())
self.rubberBand.addPoint(point1, False)
self.rubberBand.addPoint(point2, False)
self.rubberBand.addPoint(point3, False)
self.rubberBand.addPoint(point4, True) # true to update canvas
self.rubberBand.show()
def rectangle(self):
if self.startPoint is None or self.endPoint is None:
return None
elif (self.startPoint.x() == self.endPoint.x() or \
self.startPoint.y() == self.endPoint.y()):
return None
return QgsRectangle(self.startPoint, self.endPoint)
def deactivate(self):
QgsMapTool.deactivate(self)
self.deactivated.emit()
Ecrire des éléments de canevas de carte personnalisés¶
- A FAIRE :
Comment créer un objet de canevas de carte ?
import sys
from qgis.core import QgsApplication
from qgis.gui import QgsMapCanvas
def init():
a = QgsApplication(sys.argv, True)
QgsApplication.setPrefixPath('/home/martin/qgis/inst', True)
QgsApplication.initQgis()
return a
def show_canvas(app):
canvas = QgsMapCanvas()
canvas.show()
app.exec_()
app = init()
show_canvas(app)