Python 主控台
用幾行程式讀圖層、
手上有一個坵塊圖層,要找出所有「四級坡以上」的坵塊、算它們的總面積,再把結果寫回一個欄位。用介面做要開屬性表、用運算式選取、看統計面板、再開欄位計算機。這不難,但如果每個案子都要做、或要對三十個圖層做,就會想問:能不能打幾行指令直接得到答案?
Python 主控台就是做這件事的地方。常見的卡關點是:
- 不知道程式裡要怎麼「拿到」畫面上那個圖層。
- 拿到圖層後跑迴圈,屬性表卻沒有變,或變了但存檔後消失。
- 面積算出來跟欄位計算機的
$area不一樣。
任何一個多邊形圖層都可以,最好是投影坐標系統(例如 TWD97 / TM2 zone 121,EPSG:3826)的 GeoPackage,並有一個數值欄位可以拿來篩選。本單元的範例假設圖層名稱是 坵塊、有一個整數欄位 grade(坡度級別 1~7)。沒有現成資料時,可以用 M2 數化與屬性編輯 的方式自己畫幾個多邊形、手動填 grade。
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
開啟主控台:外掛 Plugins ▸ Python 主控台 Python Console,或按
Ctrl+Alt+P。主控台下方是輸入列,按 顯示編輯器 Show Editor 可以開出多行編輯區,寫好後按 執行腳本 Run script(Ctrl+Shift+E)整段執行。 -
取得圖層。在圖層面板點選
坵塊,然後在主控台輸入:# 測試狀態:未在 QGIS 4 實機執行layer = iface.activeLayer() # 圖層面板目前選取的圖層print(layer.name(), layer.crs().authid(), layer.featureCount())不想依賴「目前選取哪個圖層」時,改用名稱取得:
# 測試狀態:未在 QGIS 4 實機執行layers = QgsProject.instance().mapLayersByName('坵塊')layer = layers[0] # 同名圖層可能不只一個,回傳的是清單 -
看欄位與逐筆讀圖徵:
# 測試狀態:未在 QGIS 4 實機執行print(layer.fields().names())for f in layer.getFeatures():print(f.id(), f['grade'], round(f.geometry().area(), 1)) -
只讀符合條件的圖徵。不要把全部圖徵讀進來再用
if篩,改用QgsFeatureRequest讓資料來源先篩:# 測試狀態:未在 QGIS 4 實機執行req = QgsFeatureRequest().setFilterExpression('"grade" >= 4')total = 0.0n = 0for f in layer.getFeatures(req):total += f.geometry().area()n += 1print(f'四級坡以上 {n} 格,平面面積合計 {total:.1f}(圖層坐標單位的平方)') -
把結果寫回欄位。先用介面或程式新增一個實數欄位
steep,再用edit()包住修改,離開區塊時會自動 commit,出錯時自動回復:# 測試狀態:未在 QGIS 4 實機執行from qgis.core import editidx = 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) -
把結果告訴使用者。主控台的
print()只有開著主控台的人看得到,寫給別人用的程式改用訊息列:# 測試狀態:未在 QGIS 4 實機執行iface.messageBar().pushMessage('坡度統計', f'四級坡以上共 {n} 格',level=Qgis.MessageLevel.Info, duration=5) -
呼叫既有的 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),比全部讀出來再篩快很多。
為什麼要用 edit()
Section titled “為什麼要用 edit()”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 欄位計算機 的平面/橢球面積相同。
主控台預先載入了什麼
Section titled “主控台預先載入了什麼”依 QGIS 3.44 使用手冊,主控台已預先 import QGIS 的 core、gui、analysis、processing 等模組、Qt 的 QtCore、QtGui、QtWidgets 等模組,以及 Python 的 math、os、re、sys。所以在主控台裡可以直接寫 QgsProject、processing;但同一段程式搬到外掛或獨立腳本時,就要自己寫 from qgis.core import ...。
為什麼列舉值要寫全名
Section titled “為什麼列舉值要寫全名”範例裡寫 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()) 確認實際欄位名 |
本單元目前沒有對應影片。
- 寫一段程式,印出目前專案裡每個向量圖層的名稱、坐標系統代碼與圖徵數。
- 檢查方式:結果應與各圖層 屬性 Properties ▸ 資訊 Information 頁顯示的 CRS 與圖徵數一致。
- 對你的多邊形圖層,用
QgsFeatureRequest篩出某個條件的圖徵,算平面面積總和。- 檢查方式:用介面以同一個運算式 依運算式選取 Select by Expression,再用 統計摘要 Statistical Summary 面板看
$area的總和;兩者若有差異,說得出是平面與橢球面積的差別。
- 檢查方式:用介面以同一個運算式 依運算式選取 Select by Expression,再用 統計摘要 Statistical Summary 面板看
- 把練習 2 的結果寫進新欄位,關掉 QGIS 再重開專案。
- 檢查方式:重開後欄位值仍在,代表修改確實寫進檔案而不只在編輯緩衝區。
- PyQGIS Developer Cookbook(撰寫時對應 QGIS 3.44)
- QGIS 使用手冊:Python Console:開啟方式、快捷鍵、預先載入的模組
- QGIS 運算式函式清單:
$area與area()的差別說明 - QGIS Python API 文件