# SHWRP-2026-032 engineering research package

本目錄是《從自動航線到可稽核生長異常圖》版本1.0的可重現研究環境。它展示的是已實作並以合成資料驗證的軟體工程原型，不是已完成的農田實飛、作物診斷或農業成效試驗。

## DOI 與建議引用

- 報告編號：`SHWRP-2026-032`
- 版本：`1.0`
- DOI：[`10.5281/zenodo.21782959`](https://doi.org/10.5281/zenodo.21782959)
- 建議引用：周秉漢（2026）。〈從自動航線到可稽核生長異常圖：DJI Mavic 3M於嘉義鹿草候選稻田的多光譜巡檢工程原型、程式實作與現地驗證方案〉。《上好味研究工作論文系列》，SHWRP-2026-032，版本 1.0。https://doi.org/10.5281/zenodo.21782959

## 已完成與未完成

已完成：

- 小田區往復式航線規劃器與參數驗證。
- fail-closed飛前軟體閘門。
- 規劃用GeoJSON、JSON與不可執飛的KML/KMZ預覽。
- 四個已對齊反射率波段的品質檢查。
- NDVI、NDRE與GNDVI計算。
- robust相對低值分數、連通區分割與地面查核優先清單。
- 接受四個明確路徑與metadata receipt的通用分析CLI；raw DN、缺少band map、CRS、grid transform或校正資訊時fail closed。
- 固定亂數種子的合成資料、端到端示範、SHA-256清單及22項自動測試。

未完成：

- 未取得LC-01實際田區、地號、地主、耕作者或鹿草分場同意。
- 未取得任何飛航或研究合作許可。
- 未操作Mavic 3M實飛，未採集真實影像或作物資料。
- 未建立田間診斷、施肥、灌溉、用藥、產量或投資報酬結論。

## 最短重現方式

在本目錄執行：

```bash
python -m pip install -r requirements.txt
python -m pytest -q
python run_demo.py
```

成功時，測試應通過，示範命令會產生：

- `outputs/engineering-demo-manifest.json`
- `outputs/demo/mission/mission-summary.json`
- `outputs/demo/mission/planned-route.geojson`
- `outputs/demo/mission/route-preview-not-flight-executable.kmz`
- `outputs/demo/analysis/spectral-qc.json`
- `outputs/demo/analysis/analysis-results.json`
- `outputs/demo/analysis/priority-zones.csv`
- `outputs/demo/analysis/spectral-index-panel.png`

上述TIFF與結果全部是合成工程fixture。KMZ只有標準KML預覽，刻意不含DJI `waylines.wpml`，不能控制飛機。實際任務必須由合格操作人於DJI Pilot 2重新建立、預覽、查核並決定是否執行。

## 輸入契約

光譜分析器目前接受四張已完成反射率定標、正射處理與共註冊的二維TIFF：`green`、`red`、`red_edge`、`nir`。本版本不宣稱能直接把Mavic 3M原始照片轉成正射反射率產品；該步驟需使用經驗證的影像處理流程，並保留校正板、DLS、XMP/EXIF、軟體版本、座標系統與重建報告。

## 安全設計

- `planningOnly=true`且`executionAuthorized=false`是公開任務摘要的強制狀態。
- 飛前閘門只會輸出`NO_GO`或`ELIGIBLE_FOR_OPERATOR_FINAL_REVIEW`；通過也不是主管機關核准。
- 未填土地同意、操作人資格、機體註冊、24小時內空域查核、日間與目視、道路人群排除、天候及Pilot 2預覽時，一律fail closed。
- 公開AOI是故意位移的合成幾何，不是LC-01位置。

## 研究文件

- `paper.md`：工作論文全文。
- `study-protocol.md`：未來田間驗證協定。
- `site-selection.md`：候選場域與准入條件。
- `data-management-plan.md`：資料分級、譜系與公開邊界。
- `flight-safety-checklist.md`：飛前、飛行與飛後查核表。
- `engineering-acceptance-criteria.csv`：工程與田間階段成敗門檻。
- `field-observation-form.csv`：空白田間紀錄模板，不含觀察值。
- `source-registry.csv`、`source-log.csv`、`source-evidence.json`：來源與主張對照。
- `data-dictionary.csv`：公開欄位定義。

## 授權與第三方內容

作者有權授權的原創分析、設計、程式與圖表採CC BY 4.0。DJI文件、政府資訊、學術文獻及其他第三方內容不因被引用而改用本授權；本套件不重新散布它們的全文、圖片或原始資料。詳見`LICENSE.txt`與`RIGHTS-NOTICE.txt`。