Geoskill: Forest Health Monitor

Monitor forest canopy vitality decline, drought stress, pest damage, or wind throw from multi-temporal spectral indices. Distinguishes short-term fluctuations from persistent decline using historical baselines, persistence state machines, and climate attribution. Use when assessing forest health, detecting anomalies, or planning field sampling.

Prerequisites / 先准备 X 文件

⚠️ 必读 — 本 skill 不属于即用型，需要先准备特定文件才能跑。

本 skill 需要 bbox + 年份。所有 NDVI/EVI/NDMI/NBR 时序数据自动从 MPC 下载。

👉 完整教程见仓库根目录 PREREQUISITES.md 1.3 节。

先准备 X 文件：--synthetic 一行跑通，验证工作流后再传真实 AOI。

快速试跑命令：

bash

python forest_health_monitor.py --synthetic --output-dir ./test

Forest Health Monitor

Detects forest health anomalies from spectral indices (NDVI, EVI, NDMI, NBR) and distinguishes short-term fluctuations from sustained deterioration using historical baselines, a persistence state machine, and climate attribution.

Trigger

Use when the user wants to:

• Detect forest canopy vitality decline from satellite imagery
• Distinguish drought stress, pest damage, or wind throw from seasonal variation
• Identify persistent decline zones vs. short-term fluctuations
• Correlate forest anomalies with climate variables (SPI/SPEI)
• Generate stratified sampling plans for field verification
• Assess forest health by stand type (evergreen, deciduous, mixed)

CLI Usage

bash

# Basic health monitoring with bounding box
python scripts/forest_health_monitor.py \
  --bbox 116.0,39.0,117.0,40.0 \
  --forest-type evergreen \
  --year 2024

# With AOI file and custom indices
python scripts/forest_health_monitor.py \
  --aoi-file forest_aoi.geojson \
  --forest-type-file stand_types.geojson \
  --start-date 2022-01-01 \
  --end-date 2024-12-31 \
  --indices ndvi,evi,ndmi,nbr \
  --persistence 3 \
  --climate-attribution spi

# Full parameter set
python scripts/forest_health_monitor.py \
  --aoi-file aoi.geojson \
  --forest-type mixed \
  --baseline-years 5 \
  --indices ndvi,ndmi,nbr \
  --persistence 2 \
  --climate-attribution spei \
  --output-dir ./fhm-output \
  --overwrite

# Synthetic demo (no AOI/rasters needed)
python scripts/forest_health_monitor.py --synthetic --output-dir ./fhm-output

Parameters

Parameter	Default	Description
--aoi-file	—	AOI boundary (GeoJSON/Shapefile)
--bbox	—	Bounding box: xmin,ymin,xmax,ymax
--place	—	Named place (requires geocoding)
--forest-type	mixed	Forest type: evergreen, deciduous, mixed
--forest-type-file	—	Forest type polygons GeoJSON
--year	current	Monitoring year
--start-date	—	Start date (YYYY-MM-DD)
--end-date	—	End date (YYYY-MM-DD)
--baseline-years	5	Years for historical baseline
--indices	ndvi,evi,ndmi,nbr	Comma-separated spectral indices
--persistence	2	Persistence threshold (months)
--climate-attribution	spi	Climate variable: spi, spei, temperature, precipitation
--severity-schema	built-in	Custom severity schema JSON
--output-dir	fhm-output	Output directory
--overwrite	false	Allow overwriting existing output
--synthetic	false	Run with synthetic demo data (auto-generates NDVI/EVI rasters + AOI)

Output

File	Description
forest_health.tif	Multi-temporal severity classification raster
persistent_decline.geojson	Zones with persistent decline
climate_links.csv	Climate attribution per zone
timeseries.parquet	Full health time series per zone
sampling_plan.geojson	Stratified sampling point recommendations
request.json	Input request record
dataset-manifest.json	Data source manifest
output-manifest.json	Output file manifest
qa.json	Quality assurance report
run.log	Execution log

Health Severity Levels

Level	Code	Color	Criteria
Healthy	0	00FF00	All indices within 1 std of baseline
Mild Stress	1	FFFF00	1+ indices below 1.5 std, or alert state
Moderate Decline	2	FF9900	2+ indices below 1.5 std, decline state
Severe Decline	3	FF0000	2+ indices below 2.0 std, persistent decline
Mortality	4	990000	Extreme decline, absorbing state

Health State Machine

State	Description	Transition
stable	Normal condition	→ alert on anomaly
alert	Initial anomaly detected	→ decline if persistent
decline	Sustained deterioration	→ recovery if improving
recovery	Improving trend	→ stable if sustained
mortality	Extreme decline (absorbing)	→ recovery only with strong evidence

Key Design Principles

1. Stratified baselines: Each forest type (evergreen/deciduous/mixed) has its own phenological baseline. No universal threshold across all forests.
2. Multi-index consensus: At least 2 indices must agree before flagging high-confidence anomalies.
3. Three independent dimensions: Anomaly (deviation), Persistence (state machine), Attribution (climate correlation) are reported separately.
4. Phenology-aware: Deciduous winter NDVI drop is not flagged as disease because the baseline accounts for seasonal amplitude.

Exit Codes

Code	Meaning
0	Success
2	Argument error
3	Dependency missing
6	Data validation failure
7	Processing failure

Limitations

• Species and age-class differences affect baseline accuracy
• Pest/disease attribution typically requires field data
• Long-term sensor differences require cross-normalization
• Output is remote sensing analysis support, not regulatory determination

数据下载

本 skill 可自动从 Microsoft Planetary Computer 下载数据 (无需 API key):

bash

python forest_health_monitor.py --bbox 116,39,117,40 --date-range 2024-06-01,2024-06-30 --output-dir <tmp>

• --bbox W,S,E,N: WGS-84 边界框 (西, 南, 东, 北)
• --date-range START,END: 日期范围 (YYYY-MM-DD,YYYY-MM-DD)
• --aoi-file <path.geojson>: 替代 --bbox 的 GeoJSON 多边形
• --cache-dir <path>: 缓存目录 (默认 ~/.geoskill_cache)

当用户只给 --bbox + --date-range (没有 --image) 时，skill 自动下载数据。 当用户给 --image 时，走原文件路径 (向后兼容)。