跳到內容

Python 主控台

用幾行程式讀圖層、篩圖徵、改屬性

M10進階約 40 分鐘

草稿|步驟依 QGIS 3.44 手冊撰寫,尚未在 QGIS 4 實機驗證

手上有一個坵塊圖層,要找出所有「四級坡以上」的坵塊、算它們的總面積,再把結果寫回一個欄位。用介面做要開屬性表、用運算式選取、看統計面板、再開欄位計算機。這不難,但如果每個案子都要做、或要對三十個圖層做,就會想問:能不能打幾行指令直接得到答案?

Python 主控台就是做這件事的地方。常見的卡關點是:

  • 不知道程式裡要怎麼「拿到」畫面上那個圖層。
  • 拿到圖層後跑迴圈,屬性表卻沒有變,或變了但存檔後消失。
  • 面積算出來跟欄位計算機的 $area 不一樣。

任何一個多邊形圖層都可以,最好是投影坐標系統(例如 TWD97 / TM2 zone 121,EPSG:3826)的 GeoPackage,並有一個數值欄位可以拿來篩選。本單元的範例假設圖層名稱是 坵塊、有一個整數欄位 grade(坡度級別 1~7)。沒有現成資料時,可以用 M2 數化與屬性編輯 的方式自己畫幾個多邊形、手動填 grade。

  1. 開啟主控台:外掛 Plugins ▸ Python 主控台 Python Console,或按 Ctrl+Alt+P。主控台下方是輸入列,按 顯示編輯器 Show Editor 可以開出多行編輯區,寫好後按 執行腳本 Run script(Ctrl+Shift+E)整段執行。

  2. 取得圖層。在圖層面板點選 坵塊,然後在主控台輸入:

    # 測試狀態:未在 QGIS 4 實機執行
    layer = iface.activeLayer() # 圖層面板目前選取的圖層
    print(layer.name(), layer.crs().authid(), layer.featureCount())

    不想依賴「目前選取哪個圖層」時,改用名稱取得:

    # 測試狀態:未在 QGIS 4 實機執行
    layers = QgsProject.instance().mapLayersByName('坵塊')
    layer = layers[0] # 同名圖層可能不只一個,回傳的是清單
  3. 看欄位與逐筆讀圖徵:

    # 測試狀態:未在 QGIS 4 實機執行
    print(layer.fields().names())
    for f in layer.getFeatures():
    print(f.id(), f['grade'], round(f.geometry().area(), 1))
  4. 只讀符合條件的圖徵。不要把全部圖徵讀進來再用 if 篩,改用 QgsFeatureRequest 讓資料來源先篩:

    # 測試狀態:未在 QGIS 4 實機執行
    req = QgsFeatureRequest().setFilterExpression('"grade" >= 4')
    total = 0.0
    n = 0
    for f in layer.getFeatures(req):
    total += f.geometry().area()
    n += 1
    print(f'四級坡以上 {n} 格,平面面積合計 {total:.1f}(圖層坐標單位的平方)')
  5. 把結果寫回欄位。先用介面或程式新增一個實數欄位 steep,再用 edit() 包住修改,離開區塊時會自動 commit,出錯時自動回復:

    # 測試狀態:未在 QGIS 4 實機執行
    from qgis.core import edit
    idx = layer.fields().indexOf('steep')
    if idx == -1:
    raise ValueError('找不到 steep 欄位,請先新增')
    with edit(layer):
    for f in layer.getFeatures():
    layer.changeAttributeValue(f.id(), idx, 1 if f['grade'] >= 4 else 0)
  6. 把結果告訴使用者。主控台的 print() 只有開著主控台的人看得到,寫給別人用的程式改用訊息列:

    # 測試狀態:未在 QGIS 4 實機執行
    iface.messageBar().pushMessage('坡度統計', f'四級坡以上共 {n} 格',
    level=Qgis.MessageLevel.Info, duration=5)
  7. 呼叫既有的 Processing 演算法,而不是自己重寫幾何運算:

    # 測試狀態:未在 QGIS 4 實機執行
    result = processing.run('native:buffer', {
    'INPUT': layer,
    'DISTANCE': 10,
    'SEGMENTS': 8,
    'DISSOLVE': False,
    'OUTPUT': 'memory:',
    })
    QgsProject.instance().addMapLayer(result['OUTPUT'])
iface、QgsProject、圖層三者的關係
Section titled “iface、QgsProject、圖層三者的關係”
  • iface 是 QGIS 主視窗介面(QgisInterface)。它管的是「畫面上的東西」:目前選取的圖層、地圖畫布、訊息列、選單與工具列。只有在 QGIS 桌面程式裡才有 iface,獨立執行的 Python 程式或 QGIS Server 沒有它。
  • QgsProject.instance() 是目前開啟的專案。圖層是登記在專案裡的,mapLayersByName()、mapLayers()、addMapLayer() 都是對專案操作。
  • 圖層(QgsVectorLayer)背後接一個資料提供者(provider),例如 GeoPackage、Shapefile、PostGIS。getFeatures() 會向提供者要資料,所以篩選條件寫在 QgsFeatureRequest 裡,提供者可以先篩(PostGIS 會變成 SQL 的 WHERE),比全部讀出來再篩快很多。

QGIS 的向量圖層有「編輯緩衝區」:changeAttributeValue() 只是改在緩衝區裡,要 commitChanges() 才會寫進檔案。手動寫 startEditing()/commitChanges() 時,迴圈中途出錯就會留下一個停在編輯模式、改了一半的圖層。with edit(layer): 進入時開始編輯、正常離開時 commit、發生例外時 rollback,是比較安全的寫法。

另外要注意:在 for f in layer.getFeatures() 迴圈裡改屬性,用的是 layer.changeAttributeValue(f.id(), …);直接改 f['steep'] = 1 只改到記憶體裡那筆圖徵的副本,圖層不會變。

面積為什麼跟欄位計算機不一樣
Section titled “面積為什麼跟欄位計算機不一樣”

QgsGeometry.area() 永遠是平面面積,單位是圖層坐標系統的單位,EPSG:3826 下就是平方公尺,EPSG:4326 經緯度下則是「平方度」,沒有實際意義。欄位計算機的 $area 會依專案的橢球體與面積單位設定計算,可能是橢球面積。兩者在 TWD97 TM2 下通常很接近,但不保證相等。程式裡要算橢球面積,用 QgsDistanceArea 並設定橢球體與坐標轉換環境,觀念與 M2 欄位計算機 的平面/橢球面積相同。

依 QGIS 3.44 使用手冊,主控台已預先 import QGIS 的 core、gui、analysis、processing 等模組、Qt 的 QtCore、QtGui、QtWidgets 等模組,以及 Python 的 math、os、re、sys。所以在主控台裡可以直接寫 QgsProject、processing;但同一段程式搬到外掛或獨立腳本時,就要自己寫 from qgis.core import ...。

範例裡寫 Qgis.MessageLevel.Info 而不是舊寫法 Qgis.Info。QGIS 4 使用 PyQt6,PyQt6 只接受「有範圍的列舉值」(scoped enum),舊寫法在 QGIS 4 可能直接出錯。現在就養成寫全名的習慣,程式在 QGIS 3 新版與 4 都能跑。細節見 04 外掛遷移到 QGIS 4/Qt6。

症狀 原因 解法
AttributeError: 'NoneType' object has no attribute 'name' 圖層面板沒有選取任何圖層,iface.activeLayer() 回傳 None 先點選圖層,或改用 mapLayersByName() 並檢查清單是否為空
IndexError: list index out of range mapLayersByName() 找不到這個名稱(名稱打錯、多了空白、圖層已改名) 印出 [l.name() for l in QgsProject.instance().mapLayers().values()] 核對
迴圈跑完屬性表沒變 改的是圖徵副本(f['x'] = …),或沒有 commit 改用 layer.changeAttributeValue(),並包在 with edit(layer): 裡
面積是很小的小數,例如 0.0000021 圖層是經緯度坐標(EPSG:4326),area() 回傳平方度 先重新投影到 EPSG:3826,或改用 QgsDistanceArea 算橢球面積
KeyError 或欄位找不到 欄位名稱大小寫不符,或 Shapefile 欄位名被截成 10 字元 先 print(layer.fields().names()) 確認實際欄位名

本單元目前沒有對應影片。

  1. 寫一段程式,印出目前專案裡每個向量圖層的名稱、坐標系統代碼與圖徵數。
    • 檢查方式:結果應與各圖層 屬性 Properties ▸ 資訊 Information 頁顯示的 CRS 與圖徵數一致。
  2. 對你的多邊形圖層,用 QgsFeatureRequest 篩出某個條件的圖徵,算平面面積總和。
    • 檢查方式:用介面以同一個運算式 依運算式選取 Select by Expression,再用 統計摘要 Statistical Summary 面板看 $area 的總和;兩者若有差異,說得出是平面與橢球面積的差別。
  3. 把練習 2 的結果寫進新欄位,關掉 QGIS 再重開專案。
    • 檢查方式:重開後欄位值仍在,代表修改確實寫進檔案而不只在編輯緩衝區。