天天看點
傳回

QGIS相關API用法彙總（一）qgis.core包qgis.gui包

QGIS的API參見官方文檔：《QGIS API Documentation 3.22.4-Białowieża (ce8e65e95e)》。

本文僅僅記錄自己在項目中用到的API，記錄自己的了解和總結。

QGIS庫的五個包： 

qgis.core 這樣可以通路整個QGIS中使用的核心GIS功能。
qgis.gui 這定義了一系列GUI小部件，您可以在自己的程式中包含這些小部件。
qgis.analysis 這提供了空間分析工具來分析矢量和栅格格式資料。
qgis.networkanalysis 這提供了建構和分析拓撲的工具。
qgis.utils 這實作了各種功能，允許您使用Python使用QGIS應用程式。

前兩個包（qgis.core和qgis.gui）實作了QGIS庫中最重要的部分，值得花一些時間來熟悉它們定義的概念和類。現在讓我們仔細看看這兩個包。

qgis.core包

qgis.core包定義了整個QGIS系統中使用的基本類。該軟體包的很大一部分專門用于處理矢量和栅格格式的地理空間資料，并在地圖中顯示這些類型的資料。我們來看看這是如何完成的。

地圖和地圖圖層

地圖由一個在另一個上面繪制的多個圖層組成：

QGIS相關API用法彙總（一）qgis.core包qgis.gui包

 我們用的最多的三種類型的地圖圖層如下：

  • 矢量圖層：此圖層繪制地理空間要素，如點，線和多邊形
  • 栅格圖層：此圖層将栅格（位圖）資料繪制到地圖上
  • 插件層：此圖層允許插件直接繪制到地圖上。

所有的圖層類從QgsMapLayer派生，從下圖可以看到有多少個圖層類及派生關系：

QGIS相關API用法彙總（一）qgis.core包qgis.gui包

這些類型的地圖圖層中的每一個都在qgis.core庫中具有相應的類。例如，矢量地圖圖層将由qgis.core.QgsVectorLayer類型的對象表示。

我們将很快詳細介紹矢量和栅格地圖圖層。但是，在我們這樣做之前，我們需要了解地理空間資料（矢量和栅格資料）如何

定位在地圖上。

協調參考系統

由于地球是一個三維物體，地圖隻會将地球表面表示為一個二維平面，是以必須有一種方法将地球表面上的點轉換為地圖内的(x, y)坐标。這是使用坐标參考系統（CRS）完成的：

QGIS相關API用法彙總（一）qgis.core包qgis.gui包

地球圖檔由維基媒體提供（http://commons.wikimedia.org/wiki/File:Rotating_globe.gif） 

CRS有兩個部分：橢圓體，它是地球表面的數學模型，以及投影，它是将球體表面上的點轉換為地圖上(x, y)坐标的公式。

通常，您不必擔心所有這些細節。您隻需選擇與您正在使用的資料的CRS比對的相應CRS即可。但是，由于多年來設計了許多不同的坐标參考系統，是以在繪制地理空間資料時使用正确的CRS至關重要。如果不這樣做，您的功能将顯示在錯誤的位置或形狀錯誤。

目前可用的大多數地理空間資料使用EPSG 4326坐标參考系統（有時也稱為WGS84）。此CRS将坐标定義為緯度和經度值。這是用于導入QGIS的新資料的預設CRS。但是，如果您的資料使用不同的坐标參照系，則需要為地圖圖層建立和使用不同的CRS。

qgis.core.QgsCoordinateReferenceSystem類表示CRS。建立坐标參照系後，可以在通路基礎資料時告訴地圖圖層使用該CRS。例如：

crs = QgsCoordinateReferenceSystem(4326, QgsCoordinateReferenceSystem.EpsgCrsId))
layer.setCrs(crs)

 請注意，不同的地圖圖層可以使用不同的坐标參考系 在将圖層的内容繪制到地圖上時，每個圖層都将使用其CRS。

矢量圖層

矢量圖層以點，線，多邊形等形式将地理空間資料繪制到地圖上。矢量格式地理空間資料通常從矢量資料源（例如shapefile或資料庫）加載。其他矢量資料源可以将矢量資料儲存在存儲器中，或者通過網際網路從Web服務加載資料。

矢量格式資料源具有許多功能，其中每個功能代表資料源中的單個記錄。qgis.core.QgsFeature類表示資料源中的功能。每個功能都有以下原則：

  • ID：這是資料源中功能的唯一辨別符。
  • 幾何：這是底層的點，線，多邊形等，它代表地圖上的特征。例如，表示城市的資料源将為每個城市提供一個要素，幾何圖形通常是表示城市中心的點，或表示城市輪廓的多邊形（或多邊形）。
  • 屬性：這些是鍵/值對，提供有關該功能的其他資訊。例如，城市資料源可能具有total_area，population，elevation等屬性。屬性值可以是字元串，整數或浮點數。

在QGIS中，資料提供程式允許矢量圖層通路資料源中的要素。資料提供程式是qgis.core.QgsVectorDataProvider的一個執行個體，包括：

  • 存儲在資料源中的幾何類型
  • 提供有關為每個要素存儲的屬性的資訊的字段清單
  • 使用getFeatures()方法和QgsFeatureRequest類搜尋資料源中的功能的能力

您可以使用qgis.core.QgsProviderRegistry類通路各種矢量（以及栅格）資料提供程式。

矢量圖層本身由qgis.core.QgsVectorLayer對象表示。每個矢量圖層包括：

  • 資料提供者：這是與底層檔案或資料庫的連接配接，用于儲存要顯示的地理空間資訊
  • 坐标參照系：這表示地理空間資料使用的CRS
  • 渲染器：選擇如何顯示要素

讓我們仔細看看渲染器的概念以及如何在矢量地圖圖層中顯示要素。

顯示矢量資料

矢量地圖圖層中的要素使用渲染器和符号對象的組合顯示。渲染器選擇用于給定特征的符号，以及執行實際繪制的符号。

QGIS定義了三種基本類型的符号：

  • 标記符号：這将點顯示為實心圓
  • 線符号：使用給定的線寬和顔色繪制線條
  • 填充符号：這将繪制具有給定顔色的多邊形的内部

這三種類型的符号實作為qgis.core.QgsSymbolV2類的子類：

  • qgis.core.QgsMarkerSymbolV2
  • qgis.core.QgsLineSymbolV2
  • qgis.core.QgsFillSymbolV2

在内部，符号相當複雜，因為“符号層”允許多個元素彼此重疊繪制。但是，在大多數情況下，您可以使用符号的“簡單”版本。這使得在不必處理符号層的内部複雜性的情況下更容易建立新符号。例如：

symbol = QgsMarkerSymbolV2.createSimple({'width': 1.0, 'color':"255,0,0"})

當符号将要素繪制到地圖上時，渲染器用于選擇繪制特定要素的符号。在最簡單的情況下，相同的符号用于圖層中的每個要素。這稱為單符号渲染器，由qgis.core.QgsSingleSymbolRenderV2類表示。其他可能性包括：

  • 分類符号渲染器（qgis.core.QgsCategorizedSymbolRendererV2）：此渲染器根據屬性值選擇符号。分類符号渲染器具有從屬性值到符号的映射。
  • 漸變符号渲染器（qgis.core.QgsGraduatedSymbolRendererV2）：此類渲染器具有一系列屬性，值，并将每個範圍映射到适當的符号。

使用單個符号渲染器非常簡單：

symbol = ... 
renderer = QgsSingleSymbolRendererV2(symbol)
layer.setRendererV2(renderer)

要使用分類符号渲染器，首先要定義qgis.core清單。QgsRendererCategoryV2對象，然後使用它來建立渲染器。

例如：

symbol_male = ... 
symbol_female = ... 
 
categories = [] categories.append(QgsRendererCategoryV2("M", symbol_male, "Male"))
categories.append(QgsRendererCategoryV2("F", symbol_female, "Female"))
renderer = QgsCategorizedSymbolRendererV2("", categories)
renderer.setClassAttribute("GENDER")
layer.setRendererV2(renderer)

請注意，QgsRendererCategoryV2構造函數有三個參數：所需的值，使用的符号以及用于描述該類别的标簽。

最後，要使用漸變符号渲染器，您可以定義qgis.core.QgsRendererRangeV2對象的清單，然後使用它來建立渲染器。例如：

symbol1 = ... 
symbol2 = ... 
 
ranges = [] ranges.append(QgsRendererRangeV2(0, 10, symbol1, "Range 1"))
ranges.append(QgsRendererRange(11, 20, symbol2, "Range 2"))
 
renderer = QgsGraduatedSymbolRendererV2("", ranges)
renderer.setClassAttribute("FIELD")
layer.setRendererV2(renderer)

通路矢量資料

除了在地圖中顯示矢量圖層的内容之外，您還可以直接通路基礎資料。這可以使用資料提供程式的getFeatures()方法完成。例如，要疊代圖層中的所有要素，您可以執行以下操作：

provider.getFeatures(QgsFeatureRequest())
中的功能的provider = layer.dataProvider()：

...

如果要根據某些條件搜尋要素，可以使用QgsFeatureRequest對象的setFilterExpression()方法，如下所示：

provider = layer.dataProvider()
request = QgsFeatureRequest()
request.setFilterExpression('"GENDER"="M"')
for provider.getFeatures(QgsFeatureRequest())中的功能：
  ...

獲得這些功能後，可以輕松通路功能的幾何，ID 和屬性。例如：

geometry = feature.geometry()
  id = feature.id()
  name = feature.attribute("NAME")

由feature.geometry()調用傳回的對象（将是qgis.core.QgsGeometry的執行個體）表示要素的幾何。此對象有許多方法可用于提取基礎資料并執行各種地理空間計算。

空間索引

在上一節中，我們根據屬性值搜尋了要素。但是，有時您可能希望根據它們在太空中的位置找到特征。例如，您可能希望查找位于給定點的特定距離内的所有要素。為此，您可以使用空間索引，該索引根據功能的位置和範圍對功能進行索引。空間索引由QgsSpatialIndex類在QGIS中表示。

出于性能原因，不會為每個矢量圖層自動建立空間索引。但是，在您需要時可以輕松建立一個：

provider = layer.dataProvider()
index = QgsSpatialIndex()
用于provider.getFeatures(QgsFeatureRequest())中的
  功能：index.insertFeature(feature)

 不要忘記您可以使用QgsFeatureRequest.SetFilterExpression()方法來限制添加到索引的功能集。

獲得空間索引後，可以使用它根據要素的位置執行查詢。特别是：

  • 您可以使用nearestNeighbor()方法找到最接近給定點的一個或多個要素。例如： 
features = index.nearestNeighbor(QgsPoint(long,lat),5)

 請注意，此方法有兩個參數：作為QgsPoint對象的所需點和要傳回的要素數。

  • 您可以使用intersects()方法找到與給定矩形區域相交的所有要素，如下所示： 
features = index.intersects(QgsRectangle(左,下,右,上))

栅格圖層

栅格格式的地理空間資料本質上是位圖圖像，其中圖像中的每個像素或“單元”對應于地球表面的特定部分。栅格資料通常被組織成頻帶，其中每個頻帶代表不同的資訊。波段的常見用途是将像素顔色的紅色，綠色和藍色分量存儲在單獨的波段中。波段也可能代表其他類型的資訊，例如濕度，海拔或土壤類型。

有許多方法可以顯示栅格資訊。例如：

  • 如果栅格資料隻有一個波段，則像素值可以用作調色闆的索引。調色闆将每個像素值映射映射到特定顔色。
  • 如果栅格資料隻有一個波段但沒有提供調色闆。像素值可以直接用作灰階值; 也就是說，數字越大，數字越小。或者，可以通過僞彩色算法傳遞像素值以計算要顯示的顔色。
  • 如果栅格資料具有多個頻帶，則通常将頻帶組合以生成期望的顔色。例如，一個波段可能代表顔色的紅色分量，另一個波段可能代表綠色分量，而另一個波段可能代表藍色分量。
  • 或者，可以通過選擇用于顔色計算的特定頻帶，使用調色闆或作為灰階或僞彩色圖像來繪制多頻帶光栅資料源。

讓我們仔細看看如何将光栅資料繪制到地圖上。

顯示栅格資料

與栅格波段關聯的繪圖樣式控制栅格資料的顯示方式。目前支援以下繪圖樣式：

繪圖樣式

繪畫風格 描述
PalettedColor 對于單波段栅格資料源，調色闆将每個栅格值映射為顔色。
SingleBandGray 對于單波段栅格資料源，栅格值直接用作灰階值。
SingleBandPseudoColor 對于單波段栅格資料源，栅格值用于計算僞彩色。
PalettedSingleBandGray 對于具有調色闆的單波段栅格資料源，此繪圖樣式告訴QGIS忽略調色闆并直接将栅格值用作灰階值。
PalettedSingleBandPseudoColor 對于具有調色闆的單波段栅格資料源，此繪圖樣式告訴QGIS忽略調色闆并使用栅格值計算僞彩色。
MultiBandColor 對于多波段栅格資料源，請為紅色，綠色和藍色元件中的每一個使用單獨的波段。對于此繪圖樣式，可以使用setRedBand()，setGreenBand()和setBlueBand()方法來選擇要用于每個顔色分量的波段。
MultiBandSingleBandGray 對于多波段栅格資料源，請選擇單個波段作為灰階顔色值。對于此繪圖樣式，請使用setGrayBand()方法指定要使用的波段。
MultiBandSingleBandPseudoColor 對于多波段栅格資料源，選擇用于計算僞彩色的單個波段。對于此繪圖樣式，請使用setGrayBand()方法指定要使用的波段。

要設定繪圖樣式，請使用layer.setDrawingStyle()方法，傳入包含所需繪圖樣式名稱的字元串。您還需要調用各種setXXXBand()方法（如上表所述），以告訴栅格圖層哪些波段包含用于繪制每個像素的值。

請注意，當您調用前面的函數來更改栅格資料的顯示方式時，QGIS不會自動更新地圖。要立即顯示更改，您需要執行以下操作：

  1. 關閉光栅圖像緩存。這可以通過調用layer.setImageCache(None)來完成。
  2. 通過調用layer.triggerRepaint()告訴栅格圖層重繪自身。

通路栅格資料 

provider = layer.dataProvider()
values = provider.identify(QgsPoint(x, y), QgsRaster.IdentifyFormatValue）
if values.isValid():
  for band, values in values.results().items():
    ...

如您所見，您需要檢查栅格資料中是否存在給定坐标（使用isValid()調用）。values.results()方法傳回一個将band編号映射到值的字典。

使用此技術，您可以提取與栅格圖層中給定坐标關聯的所有基礎數​​據。

您還可以使用Provider.Block()方法一次性檢索大量坐标的波段資料。我們将在本文後面介紹如何執行此操作。

其他有用的qgis.core類

除了處理資料源和地圖圖層所涉及的所有類和功能之外，qgis.core庫還定義了許多您可能會覺得有用的其他類：

其他qgis.core的有用類

類 描述
QgsProject 這代表了目前的QGIS項目。請注意，這是一個單例對象，因為一次隻能打開一個項目。所述QgsProject類負責加載和存儲的特性，其可以是對插件有用。
QGIS 該類定義了整個QGIS系統中使用的各種常量，資料類型和函數。
QgsPoint 這是一個通用類，用于存儲二維平面内點的坐标。
QgsRectangle 這是一個通用類，用于存儲二維平面内矩形區域的坐标。
QgsRasterInterface 這是用于處理栅格資料的基類。這可以用于将一組栅格資料重新投影到新的坐标系中，應用濾鏡來更改栅格資料的亮度或顔色，重新采樣栅格資料，以及通過渲染現有資料來生成新的栅格資料各種方式。
QgsDistanceArea 此類可用于計算給定幾何體的距離和面積，自動從源坐标參考系統轉換為米。
QgsMapLayerRegistry 此類提供對目前項目中所有已注冊地圖圖層的通路。
QgsMessageLog 此類提供QGIS程式中的正常日志記錄功能。這使您可以将調試消息，警告和錯誤發送到QGIS“日志消息”面闆。

qgis.gui包

qgis.gui包定義了許多可以包含在程式中的使用者界面小部件。讓我們從檢視最重要的qgis.gui類開始，然後簡要介紹一下您可能會覺得有用的其他類。

QgisInterface類

QgisInterface表示QGIS系統的使用者界面。它允許以程式設計方式通路地圖畫布，菜單欄和QGIS應用程式的其他部分。在腳本或插件中運作Python代碼時，或直接從QGIS Python控制台運作時，通常可以通過iface全局變量引用QgisInterface。

 您可以使用QgisInterface對象執行的一些更重要的事情是：

  • 通過legendInterface()方法擷取目前QGIS項目中的圖層清單的引用。
  • 使用mapCanvas()方法擷取對主應用程式視窗中顯示的地圖畫布的引用。
  • 使用activeLayer()方法檢索項目中目前活動的圖層，并使用setActiveLayer()方法設定目前活動圖層。

  • 通過調用mainWindow()方法擷取對應用程式主視窗的引用。如果要建立

    使用主視窗作為其父視窗的其他Qt視窗或對話框，這将非常有用。

  • 通過調用messageBar()方法擷取對QGIS系統消息欄的引用。這允許您直接在QGIS主視窗中向使用者顯示消息。

QgsMapCanvas類

地圖畫布負責将各種地圖圖層繪制到視窗中。QgsMapCanvas類表示地圖畫布。這堂課包括：

  • 目前顯示的地圖圖層清單。這可以使用layers()方法通路。
 請注意，地圖畫布中可用的地圖圖層清單與QgisInterface.LegendInterface()方法中包含的地圖圖層清單之間存在細微差别。地圖畫布的圖層清單僅包含目前可見的圖層清單，而QgisInterface.LegendInterface()則傳回所有地圖圖層，包括目前隐藏的圖層。 
  • 此地圖使用的地圖機關（米，英尺，度等）。可以通過調用mapUnits()方法來檢索地圖的機關。
  • 範圍，即目前在畫布中顯示的地圖區域。地圖的範圍将随着使用者放大和縮小而變化，并在地圖上平移。可以通過調用extent()方法擷取目前地圖範圍。
  • 一種目前地圖工具，用于控制使用者與地圖畫布内容的互動。可以使用setMapTool()方法設定目前地圖工具，并且可以通過調用mapTool()方法檢索目前地圖工具（如果有）。
  • 用于在所有地圖圖層後面繪制背景的背景顔色。您可以通過調用canvasColor()方法更改地圖的背景顔色。
  • 從地圖坐标（即資料源的坐标參考系中的坐标）轉換為視窗内的像素的坐标變換。您可以通過調用getCoordinateTransform()方法來檢索目前坐标轉換。

QgsMapCanvasItem類

地圖畫布項是在地圖畫布頂部繪制的項。地圖畫布項目将顯示在地圖圖層的前面。雖然如果要在地圖畫布上繪制自定義項目，可以建立自己的QgsMapCanvasItem子類，但是使用現有的子類來為您完成工作會更有用。目前有三個QgsMapCanvasItem的子類，您可能會發現它們很有用：

  • QgsVertexMarker：這會繪制一個以地圖上給定點為中心的圖示（“X”，“+”或小方框）。
  • QgsRubberBand：這會在地圖上繪制任意多邊形或折線。當使用者在地圖上繪制多邊形時，它旨在提供視覺回報。
  • QgsAnnotationItem：用于以連接配接到要素的氣球形式顯示有關要素的其他資訊。QgsAnnotationItem類具有各種子類，允許您自定義資訊的顯示方式。

QgsMapTool類

地圖工具允許使用者與地圖畫布互動并操縱地圖畫布，捕獲滑鼠事件并進行适當的響應。許多QgsMapTool子類提供标準的地圖互動行為，例如單擊以放大，拖動以平移地圖，以及單擊要識别的特征。您還可以通過繼承QgsMapTool并實作響應使用者界面事件的各種方法（如按下滑鼠按鈕，拖動畫布等）來建立自己的自定義地圖工具。

建立地圖工具後，您可以允許使用者通過将地圖工具與工具欄按鈕相關聯來激活它。或者，您可以通過調用mapCanvas.setMapTool(...)方法在Python代碼中激活它。

我們将在下表中使用PyQGIS庫一節中檢視建立自定義地圖工具的過程：

其他有用的qgis.gui類

雖然qgis.gui包定義了大量類，但您最有可能發現有用的類在下表中給出：

其他qgis.gui有用的類

類 描述
QgsLegendInterface 這樣可以通路地圖圖例，即目前項目中的地圖圖層清單。請注意，地圖圖層可以在地圖圖例中進行分組，隐藏和顯示。
QgsMapTip 當使用者将滑鼠懸停在要素上時，這會在地圖畫布上顯示提示。地圖提示将顯示該功能的顯示字段; 你可以通過調用layer.setDisplayField("FIELD")來設定它。
QgsColorDialog 這是一個允許使用者選擇顔色的對話框。
QgsDialog 這是一個帶有垂直框布局和按鈕框的通用對話框，可以輕松地向對話框添加内容和标準按鈕。
QgsMessageBar 這是一個使用者界面小部件，用于向使用者顯示非阻止消息。我們檢視了上一篇文章中的消息欄類。
QgsMessageViewer 這是一個通用類，它在模式對話框中向使用者顯示長消息。

QgsBlendModeComboBox

QgsBrushStyleComboBox

QgsColorRampComboBox

QgsPenCapStyleComboBox

QgsPenJoinStyleComboBox

QgsScaleComboBox

 這些QComboBox使用者界面小部件允許您提示使用者使用各種繪圖選項。除了允許使用者選擇地圖比例的QgsScaleComboBox之外，所有其他QComboBox子類都允許使用者選擇各種Qt繪圖選項。

本文轉自：學習QGIS Python API（應用程式程式設計接口）_Tiny_Feng的部落格-CSDN部落格

qgis開發 QGIS相關API用法彙總
上一篇: Optional java 用法_JAVA Optional類用法分享
下一篇: csv 和DataProvider用法

繼續閱讀