把重複操作寫成腳本
Processing 腳本放進處理工具箱
在主控台寫的幾行程式很方便,但只有自己會用:換一個圖層要改程式裡的名稱,同事也不知道要怎麼跑。數化完的多邊形常有一堆面積不到幾平方公尺的碎面,每次都要「算面積→選取→刪除」,這種固定流程最適合做成一支工具:
- 出現在 處理工具箱 Processing Toolbox 裡,有輸入框、說明文字,跟內建演算法一樣用。
- 可以按右鍵 以批次處理執行 Execute as Batch Process 一次處理幾十個檔案。
- 可以拖進 圖形模型器 Graphical Modeler 跟其他演算法串在一起。
寫成 Processing 腳本,上面三件事 QGIS 會自動處理。
一個投影坐標系統(例如 EPSG:3826,單位公尺)的多邊形圖層。可以拿 M2 數化與屬性編輯 練習時畫的圖層,故意多畫幾個很小的多邊形當碎面。
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
在處理工具箱上方的 腳本 Scripts 按鈕(Python 圖示)選 建立新腳本 Create New Script,開啟 Processing 腳本編輯器。也可以選 從範本建立新腳本 Create New Script from Template,看官方範本的完整結構。
-
貼上以下程式:
# 測試狀態:未在 QGIS 4 實機執行from qgis.PyQt.QtCore import QCoreApplication, QMetaTypefrom qgis.core import (Qgis,QgsFeature,QgsFeatureSink,QgsField,QgsFields,QgsProcessingAlgorithm,QgsProcessingException,QgsProcessingParameterFeatureSink,QgsProcessingParameterFeatureSource,QgsProcessingParameterNumber,)class RemoveSlivers(QgsProcessingAlgorithm):INPUT = 'INPUT'MIN_AREA = 'MIN_AREA'OUTPUT = 'OUTPUT'def tr(self, text):return QCoreApplication.translate('Processing', text)def createInstance(self):return RemoveSlivers()def name(self):return 'removeslivers' # 唯一識別名稱:小寫、不含空白def displayName(self):return self.tr('刪除小碎面並加上面積欄位')def group(self):return self.tr('書齋範例')def groupId(self):return 'shuzhaiexamples'def shortHelpString(self):return self.tr('刪除平面面積小於門檻值的多邊形,保留者加上 area_m2 欄位。''輸入圖層必須是以公尺為單位的投影坐標系統。')def initAlgorithm(self, config=None):self.addParameter(QgsProcessingParameterFeatureSource(self.INPUT, self.tr('輸入多邊形圖層'),[Qgis.ProcessingSourceType.VectorPolygon]))self.addParameter(QgsProcessingParameterNumber(self.MIN_AREA, self.tr('最小面積(平方公尺)'),type=Qgis.ProcessingNumberParameterType.Double,defaultValue=10.0, minValue=0.0))self.addParameter(QgsProcessingParameterFeatureSink(self.OUTPUT, self.tr('輸出圖層'),Qgis.ProcessingSourceType.VectorPolygon))def processAlgorithm(self, parameters, context, feedback):source = self.parameterAsSource(parameters, self.INPUT, context)if source is None:raise QgsProcessingException(self.invalidSourceError(parameters, self.INPUT))if source.sourceCrs().isGeographic():raise QgsProcessingException(self.tr('輸入圖層是經緯度坐標,請先重新投影(例如 EPSG:3826)'))min_area = self.parameterAsDouble(parameters, self.MIN_AREA, context)fields = QgsFields(source.fields())fields.append(QgsField('area_m2', QMetaType.Type.Double))sink, dest_id = self.parameterAsSink(parameters, self.OUTPUT, context,fields, source.wkbType(), source.sourceCrs())if sink is None:raise QgsProcessingException(self.invalidSinkError(parameters, self.OUTPUT))total = source.featureCount() or 1kept = removed = 0for i, f in enumerate(source.getFeatures()):if feedback.isCanceled():breakarea = f.geometry().area()if area >= min_area:out = QgsFeature(fields)out.setGeometry(f.geometry())out.setAttributes(f.attributes() + [area])sink.addFeature(out, QgsFeatureSink.Flag.FastInsert)kept += 1else:removed += 1feedback.setProgress(int(100 * (i + 1) / total))# 不在 tr() 裡用 f-string,翻譯工具才抓得到原字串feedback.pushInfo(self.tr('保留 {kept} 筆,刪除 {removed} 筆').format(kept=kept, removed=removed))return {self.OUTPUT: dest_id} -
按編輯器的 儲存腳本 Save Script,存在預設的
scripts資料夾(副檔名.py)。存檔後,工具箱的 腳本 Scripts ▸ 書齋範例 底下會出現「刪除小碎面並加上面積欄位」。 -
雙擊執行,選輸入圖層、填門檻值、輸出可先選暫存圖層。看 記錄 Log 分頁的「保留 N 筆,刪除 M 筆」訊息。
-
在工具上按右鍵 以批次處理執行 Execute as Batch Process,一次加入多個圖層,確認批次也能跑。
-
開 處理 Processing ▸ 圖形模型器 Graphical Modeler,在演算法清單搜尋「碎面」,把它拖進模型,接在 修復幾何 Fix geometries 之後,組成「修復→去碎面」的兩步流程。
每個方法負責什麼
Section titled “每個方法負責什麼”| 方法 | 作用 | 寫錯的後果 |
|---|---|---|
createInstance() |
回傳一個新的演算法物件。Processing 每次執行(包括批次的每一列)都會建立新實例 | 類別改名後忘了改這裡,執行時會建出錯誤的類別 |
name() |
唯一 ID,模型與 processing.run('script:removeslivers', …) 用這個名稱呼叫 |
改名後,用到它的模型會找不到演算法 |
displayName() |
工具箱顯示的名稱,可翻譯 | 只影響顯示 |
group()/groupId() |
工具箱裡的分組 | groupId 不同但 group 相同,會出現兩個同名分組 |
initAlgorithm() |
宣告輸入與輸出參數 | 參數名稱就是 parameters 字典的鍵,前後要一致 |
processAlgorithm() |
真正的計算,回傳所有輸出的字典 | 沒回傳宣告過的輸出,模型裡下一步會接不到 |
官方建議主要輸入命名為 INPUT、主要輸出命名為 OUTPUT,這樣在模型與批次介面裡最好辨認。
為什麼用 FeatureSource 與 FeatureSink,而不是直接拿圖層
Section titled “為什麼用 FeatureSource 與 FeatureSink,而不是直接拿圖層”QgsProcessingParameterFeatureSource 讓使用者可以選圖層、選檔案,或勾選「僅使用選取的圖徵」,演算法本身不用處理這些差別。QgsProcessingParameterFeatureSink 同理:輸出可以是暫存圖層、GeoPackage、Shapefile 或資料庫,parameterAsSink() 會依使用者的選擇建立對應的寫入目標,回傳 (sink, dest_id),最後回傳 dest_id 給 Processing 載入結果。這也是同一支腳本能直接用在批次與模型裡的原因。
feedback 與取消
Section titled “feedback 與取消”feedback 物件是演算法與介面之間的通道:setProgress() 更新進度條、pushInfo() 寫記錄、isCanceled() 檢查使用者是否按了取消。迴圈裡不檢查 isCanceled(),使用者按取消也會繼續跑到底。
列舉值與欄位型別的寫法
Section titled “列舉值與欄位型別的寫法”程式裡的 Qgis.ProcessingSourceType.VectorPolygon、Qgis.ProcessingNumberParameterType.Double、QgsFeatureSink.Flag.FastInsert 都是「有範圍的列舉值」。官方範本仍有 QgsProcessing.TypeVectorAnyGeometry 這類舊寫法,在 QGIS 3 可用,但 QGIS 4 的 PyQt6 只接受全名,遷移檢查也會標出舊寫法。欄位型別用 QMetaType.Type.Double 而不是舊的 QVariant.Double,同樣是為了 Qt6。依一支實際外掛原始碼的註解,Qgis.ProcessingSourceType 這組列舉值從 QGIS 3.36 起提供、QgsField 接受 QMetaType 從 QGIS 3.38 起,要支援更舊版本的寫法見 06 讀一支真實外掛。
為什麼不直接改輸入圖層
Section titled “為什麼不直接改輸入圖層”範例把結果寫到新的輸出,而不是刪除輸入圖層裡的圖徵。Processing 演算法的慣例是「輸入不動、產生新輸出」,這樣批次與模型裡的每一步都可以重跑、可以比對。真的要就地修改,應該寫成編輯工具或外掛,而不是 Processing 演算法。
@alg 裝飾器
Section titled “@alg 裝飾器”QGIS 也提供 @alg 裝飾器的寫法,用函式加裝飾器宣告輸入輸出,程式較短。限制是裝飾器寫法的演算法只會出現在使用者的「腳本」提供者裡,不能放進外掛自己的提供者。要包進外掛的工具,建議一開始就用類別寫法。
| 症狀 | 原因 | 解法 |
|---|---|---|
| 存檔後工具箱沒有出現 | 存到 scripts 以外的資料夾,或程式有語法錯誤 |
用編輯器預設位置存檔;開 記錄訊息 Log Messages 面板的 Processing 分頁看錯誤 |
| 模型裡下一步接不到輸出 | processAlgorithm() 回傳的字典缺少宣告過的輸出鍵 |
回傳 {self.OUTPUT: dest_id},鍵名與 initAlgorithm() 一致 |
| 按取消沒有反應 | 迴圈裡沒檢查 feedback.isCanceled() |
每筆或每 N 筆檢查一次並 break |
QGIS 4 載入時出現 AttributeError 與列舉值相關的錯誤 |
使用 QgsProcessing.TypeVectorPolygon 這類舊寫法 |
改用 Qgis.ProcessingSourceType.VectorPolygon 等全名 |
| 面積欄位全部是 0 或極小值 | 輸入是經緯度坐標 | 範例已在開頭檢查 isGeographic();先重新投影再跑 |
本單元目前沒有對應影片。
- 把門檻值改成
0,執行後比對輸入與輸出的圖徵數。- 檢查方式:兩者應相同(除非有空幾何),且輸出多了
area_m2欄位。
- 檢查方式:兩者應相同(除非有空幾何),且輸出多了
- 在
initAlgorithm()加一個布林參數「只輸出被刪除的碎面」,勾選時反過來輸出小於門檻的多邊形。- 檢查方式:勾選與不勾選各跑一次,兩次輸出的圖徵數相加等於輸入圖徵數。
- 在主控台用
processing.run('script:removeslivers', {'INPUT': …, 'MIN_AREA': 5, 'OUTPUT': 'memory:'})呼叫自己的腳本。- 檢查方式:回傳字典的
OUTPUT可以用QgsProject.instance().addMapLayer()加進專案。
- 檢查方式:回傳字典的
- QGIS 使用手冊:Writing new Processing algorithms as Python scripts:官方完整範例、必要方法、
@alg裝飾器(撰寫時對應 QGIS 3.44) - PyQGIS Developer Cookbook
- QGIS Python API 文件
- Plugin migration to be compatible with Qt5 and Qt6(QGIS wiki):列舉值全名化的範例