跳到內容

把重複操作寫成腳本

Processing 腳本放進處理工具箱

M10進階約 50 分鐘

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

在主控台寫的幾行程式很方便,但只有自己會用:換一個圖層要改程式裡的名稱,同事也不知道要怎麼跑。數化完的多邊形常有一堆面積不到幾平方公尺的碎面,每次都要「算面積→選取→刪除」,這種固定流程最適合做成一支工具:

  • 出現在 處理工具箱 Processing Toolbox 裡,有輸入框、說明文字,跟內建演算法一樣用。
  • 可以按右鍵 以批次處理執行 Execute as Batch Process 一次處理幾十個檔案。
  • 可以拖進 圖形模型器 Graphical Modeler 跟其他演算法串在一起。

寫成 Processing 腳本,上面三件事 QGIS 會自動處理。

一個投影坐標系統(例如 EPSG:3826,單位公尺)的多邊形圖層。可以拿 M2 數化與屬性編輯 練習時畫的圖層,故意多畫幾個很小的多邊形當碎面。

  1. 在處理工具箱上方的 腳本 Scripts 按鈕(Python 圖示)選 建立新腳本 Create New Script,開啟 Processing 腳本編輯器。也可以選 從範本建立新腳本 Create New Script from Template,看官方範本的完整結構。

  2. 貼上以下程式:

    # 測試狀態:未在 QGIS 4 實機執行
    from qgis.PyQt.QtCore import QCoreApplication, QMetaType
    from 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 1
    kept = removed = 0
    for i, f in enumerate(source.getFeatures()):
    if feedback.isCanceled():
    break
    area = 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 += 1
    else:
    removed += 1
    feedback.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}
  3. 按編輯器的 儲存腳本 Save Script,存在預設的 scripts 資料夾(副檔名 .py)。存檔後,工具箱的 腳本 Scripts ▸ 書齋範例 底下會出現「刪除小碎面並加上面積欄位」。

  4. 雙擊執行,選輸入圖層、填門檻值、輸出可先選暫存圖層。看 記錄 Log 分頁的「保留 N 筆,刪除 M 筆」訊息。

  5. 在工具上按右鍵 以批次處理執行 Execute as Batch Process,一次加入多個圖層,確認批次也能跑。

  6. 開 處理 Processing ▸ 圖形模型器 Graphical Modeler,在演算法清單搜尋「碎面」,把它拖進模型,接在 修復幾何 Fix geometries 之後,組成「修復→去碎面」的兩步流程。

方法 作用 寫錯的後果
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 物件是演算法與介面之間的通道:setProgress() 更新進度條、pushInfo() 寫記錄、isCanceled() 檢查使用者是否按了取消。迴圈裡不檢查 isCanceled(),使用者按取消也會繼續跑到底。

程式裡的 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 讀一支真實外掛。

範例把結果寫到新的輸出,而不是刪除輸入圖層裡的圖徵。Processing 演算法的慣例是「輸入不動、產生新輸出」,這樣批次與模型裡的每一步都可以重跑、可以比對。真的要就地修改,應該寫成編輯工具或外掛,而不是 Processing 演算法。

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();先重新投影再跑

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

  1. 把門檻值改成 0,執行後比對輸入與輸出的圖徵數。
    • 檢查方式:兩者應相同(除非有空幾何),且輸出多了 area_m2 欄位。
  2. 在 initAlgorithm() 加一個布林參數「只輸出被刪除的碎面」,勾選時反過來輸出小於門檻的多邊形。
    • 檢查方式:勾選與不勾選各跑一次,兩次輸出的圖徵數相加等於輸入圖徵數。
  3. 在主控台用 processing.run('script:removeslivers', {'INPUT': …, 'MIN_AREA': 5, 'OUTPUT': 'memory:'}) 呼叫自己的腳本。
    • 檢查方式:回傳字典的 OUTPUT 可以用 QgsProject.instance().addMapLayer() 加進專案。