跳到內容

拆一支台灣坡地外掛的原始碼

看外掛怎麼分層

M10專業約 60 分鐘

草稿|尚未在 QGIS 4 實機驗證

前面幾個單元的範例都只有幾十行。真正在用的外掛動輒幾千行,第一次打開原始碼常不知道從哪裡讀起:哪個檔案是入口?計算寫在哪裡?為什麼同一個功能既有面板又有 Processing 工具?為什麼有一個檔案專門處理版本相容?

讀一支結構清楚的真實外掛,是學外掛架構最快的方式。本單元挑的是官方外掛庫上的 SWC Grid Slope(坵塊法坡度分析),它實作台灣《水土保持技術規範》的坵塊法坡度分析,題材與 M5 地質與坡地 直接相關(外掛的操作與坵塊法原理見 M5 該外掛的單元),而且同時支援 QGIS 3.22 到 4.99。本單元只看程式架構。

項目 內容
外掛 SWC Grid Slope(坵塊法坡度分析),本單元閱讀的版本為 1.4.1
作者 黃敏郎(Min-Lang Huang),外掛庫維護者帳號 yoshihuang
授權 GNU GPL 第 2 版或任何更新版本(依外掛內 LICENSE 檔)
外掛庫頁面 plugins.qgis.org/plugins/swc_grid_slope
原始碼庫 github.com/yoshihuang/swc_grid_slope
metadata 版本範圍 qgisMinimumVersion=3.22、qgisMaximumVersion=4.99

取得方式:在外掛庫頁面下載該版本的 zip,或到原始碼庫瀏覽。下載的 zip 放到一個新的空資料夾解壓再讀,只閱讀、不要用系統的 Python 直接執行裡面的檔案;要實際使用就從 QGIS 的外掛管理員安裝。

外掛 README 註明它是獨立開發的工具,不是主管機關(農業部農村發展及水土保持署)的官方產品,計算成果仍應由專業技師依規範檢核。

  1. 先看檔案清單,猜每個檔案的角色。1.4.1 版的 Python 檔與大致行數:

    檔案 行數 推測角色
    __init__.py 7 入口,classFactory()
    plugin.py 57 外掛類別:選單、工具列、面板、註冊 Processing
    dock.py 1014 右側面板介面
    maptools.py 380 地圖上畫框、平移、旋轉的互動工具
    core.py 1004 坡度計算核心
    processing_provider.py 158 Processing 提供者與演算法
    layout.py、styles.py、save.py 455、283、259 出圖版面、圖層樣式、存成 GeoPackage 專案
    compat.py 108 QGIS 3/4 版本相容
  2. 讀 metadata.txt。注意 hasProcessingProvider=yes、category=Vector、changelog 的寫法:每個版本一行,寫清楚改了什麼。1.2.4 版的 changelog 特別記錄了「為了通過 plugins.qgis.org 的安全與 Qt6 掃描」所做的修改,對照 05 發布到官方外掛庫 讀很有參考價值。

  3. 讀入口 __init__.py,跟 03 外掛骨架 的寫法相同,import 放在函式裡:

    # 節錄自 SWC Grid Slope 1.4.1 __init__.py(GPL-2.0-or-later)
    def classFactory(iface): # noqa: N802
    from .plugin import SwcGridSlopePlugin
    return SwcGridSlopePlugin(iface)
  4. 讀 plugin.py。重點有三:QAction 用 try/except 兩段 import;initGui() 先呼叫 initProcessing() 把演算法註冊進處理工具箱;面板(dock)在使用者第一次按按鈕時才建立。

    # 節錄自 SWC Grid Slope 1.4.1 plugin.py(GPL-2.0-or-later)
    try: # Qt6 / QGIS 4: QAction lives in QtGui
    from qgis.PyQt.QtGui import QAction
    except ImportError: # Qt5
    from qgis.PyQt.QtWidgets import QAction

    unload() 依序關閉面板、移除選單與工具列、從 Processing 註冊表移除提供者,正好是 initGui() 的反向操作。

  5. 讀 core.py 的開頭。檔頭說明寫著「不依賴任何 GUI 元件,可供 Processing 演算法共用」,坡度公式寫成一個小函式:

    # 節錄自 SWC Grid Slope 1.4.1 core.py(GPL-2.0-or-later)
    def slope_percent(n, dh, cell, pi=PI_314):
    """S(%) = n·π·Δh / (8L) × 100"""
    if cell <= 0:
    return 0.0
    return n * pi * dh / (8.0 * cell) * 100.0

    這裡的 n 是坵塊四邊與等高線的交點總數、dh 是等高線間距、cell 是坵塊邊長 L(10 或 25 公尺),PI_314 是常數 3.14。外掛讓使用者選 π 用 3.14 或 math.pi,README 說明預設 3.14 是為了與規範表列一致。

  6. 讀 processing_provider.py。它定義兩個類別:GridSlopeAlgorithm(繼承 QgsProcessingAlgorithm)與 GridSlopeProvider(繼承 QgsProcessingProvider)。演算法的 processAlgorithm() 讀參數、檢查坐標系統,然後呼叫 core.run_analysis(),計算本身完全交給 core.py。對照 02 Processing 腳本 的結構看,會發現方法名稱與流程一模一樣。

  7. 最後讀 compat.py,看它怎麼讓同一份原始碼在 QGIS 3.22 到 4 都能跑(見下方「原理」)。

分層:介面、計算、Processing 各管各的
Section titled “分層:介面、計算、Processing 各管各的”
plugin.py ──建立──▶ dock.py(面板)──呼叫──┐
│ maptools.py(畫框) │
│ ▼
└──註冊──▶ processing_provider.py ──呼叫──▶ core.py(純計算)
│
layout.py/styles.py/save.py ◀── 計算結果

這支外掛把「怎麼算」集中在 core.py,面板與 Processing 演算法都只是呼叫它的兩個入口。好處是:

  • 面板上按「計算」與在工具箱、批次、模型裡執行,用的是同一份計算程式,結果一致。changelog 1.3.0 也特別說明自動搜尋與正式計算使用相同的交點計數方式。
  • 計算核心不碰介面,要寫測試或改公式只需要看一個檔案。
  • 面板延後建立(使用者按按鈕才建),QGIS 啟動時不必載入上千行的介面程式。

自己的外掛只要功能超過一個按鈕,就值得照這個方式拆:介面一層、計算一層、Processing 包一層。

用 Processing 提供者,而不只是腳本
Section titled “用 Processing 提供者,而不只是腳本”

02 單元 的腳本放在使用者自己的 scripts 資料夾,換一台電腦就沒有。外掛透過 QgsProcessingProvider 註冊演算法,安裝外掛的人就自動在工具箱看到「坵塊法坡度分析」分組,也能用在批次與模型。metadata.txt 的 hasProcessingProvider=yes 就是告訴外掛庫與 QGIS 這支外掛有提供 Processing 演算法。

外掛要支援 QGIS 3.22,可是 Qgis.ProcessingSourceType.VectorPolygon 這類全名列舉值在很舊的版本不存在;同時又要通過官方外掛庫的 Qt6 掃描,原始碼裡不能出現舊的未全名化寫法。compat.py 的解法是「先找新名稱,找不到再用字串查舊名稱」:

# 節錄自 SWC Grid Slope 1.4.1 processing_provider.py(GPL-2.0-or-later)
_ST_TypeVectorPolygon = _modern_or_legacy(
Qgis, "ProcessingSourceType.VectorPolygon", QgsProcessing, "TypeVectorPolygon")

_modern_or_legacy() 用 getattr 依名稱逐段查找,舊名稱只以字串出現,所以掃描工具不會把它當成舊寫法。欄位型別也一樣,QGIS 3.38 以上用 QMetaType.Type,更舊的版本退回 QVariant。changelog 1.2.4 記錄了這次修改的目的:通過 plugins.qgis.org 的安全掃描(例如不再使用 try/except/pass,改為寫入 QGIS 訊息記錄)與 Qt6 掃描。

只需要支援 QGIS 3.40 以上與 QGIS 4 的新外掛,可以直接寫全名列舉值,不必做這層;要往前支援很舊的版本,才需要這種相容模組。

processAlgorithm() 一開始就檢查:範圍圖層是經緯度坐標就丟出例外,提示改用公尺制投影坐標(例如 EPSG:3826);沒有圖徵、沒有等高線、方格範圍沒有完全包含計畫範圍,都直接中止並說明原因。坡度計算對坐標單位極度敏感,與其算出錯的數字,不如在第一步就擋下來。這是寫給別人用的工具最值得學的習慣。

症狀 原因 解法
讀到一半迷路,不知道某個函式從哪裡被呼叫 從最大的檔案(介面)開始讀 照「metadata → __init__ → plugin.py → 核心 → 介面」的順序;用編輯器的「尋找所有參考」追呼叫關係
引用他人程式碼後被要求下架或修改 引用大段程式、未標授權與出處,或把 GPL 程式碼放進不相容授權的專案 只節錄說明所需的片段,標明作者、版本、授權;改作並散布時,整個作品要遵守 GPL
直接執行下載檔案裡的 .py 出錯或產生意外結果 外掛程式需要 QGIS 環境,且來源未經自己檢查 下載檔只閱讀;要使用就從外掛管理員安裝
照抄相容層後程式變得很難讀 新外掛其實不需要支援很舊的 QGIS 先決定最低支援版本;3.40 以上可直接寫全名列舉值

huangyoshi 頻道有這支外掛的操作示範(本站 M5 也列為延伸影片),可以對照閱讀:先看外掛實際怎麼操作,再回來看程式怎麼實作。

SWC Grid Slope v1.4.1作者 huangyoshi與本單元閱讀的版本相同,看操作流程對照 dock.py 與 core.py
  1. 在原始碼庫找出 GridSlopeAlgorithm.initAlgorithm() 宣告了哪些輸入與輸出參數。
    • 檢查方式:列出的參數數目與名稱,和在 QGIS 處理工具箱打開該演算法時看到的輸入框一一對應。
  2. 用 slope_percent() 的公式手算:交點數 n = 12、Δh = 1 公尺、L = 25 公尺、π = 3.14,S 是多少?
    • 檢查方式:答案應為 18.84%,與外掛 README 的範例一致。
  3. 畫出你自己外掛(或打算寫的外掛)的分層圖:哪些是介面、哪些是計算、哪些要包成 Processing 演算法。
    • 檢查方式:計算層的函式不 import 任何 QtWidgets 或 iface。