geoahsi 1.2.0

GeoAHSI — EMIT 高光谱矿物识别引擎（USGS MICA 算法）

GeoAHSI 核心库

GeoAHSI — EMIT 高光谱矿物识别引擎（基于 USGS MICA 算法）：EMIT 高光谱影像 → 逐像元矿物判别 → GeoTIFF 输出。

安装

# 从 PyPI 安装（推荐）
pip install geoahsi                  # 基础：分类 + GeoTIFF 输出
pip install 'geoahsi[viz]'           # + PDF 可视化（classify_spectrum / match_reference）
conda install -c conda-forge gdal    # GDAL（write_tiff 需要，conda 安装）

# 从源码安装
cd D:/123
pip install .                        # 普通安装
pip install -e .                     # 开发模式（改代码即时生效）
pip install -e ".[dev]"              # 含开发依赖（pytest/matplotlib/build/twine）

# 构建分发包
pip install build
python -m build
# → dist/geoahsi-1.2.0-py3-none-any.whl  (可直接 pip install)
# → dist/geoahsi-1.2.0.tar.gz

安装后可直接用 geoahsi 命令行工具：

geoahsi -i D:/test/EMIT_xxx.nc -o D:/test/output
geoahsi -i D:/test/EMIT_xxx.nc -o D:/test/output --raw   # 额外输出 mus_center + fd

结构

123/
├── geoahsi/                   # 核心库（零 GUI 依赖）
│   ├── emit_reader.py      # 影像读取（EmitReader）
│   ├── classifier.py       # 光谱分析核心（MicaClassifier + 全部算法 + 并行 worker）
│   ├── renderer.py         # 结果封装（ResultRenderer + HSI + GeoTIFF + DEFAULT_MUS_TABLE）
│   ├── mica_engine.py      # MicaEngine facade（组合三者，保留公共 API）
│   ├── __init__.py
│   └── data/               # 全部内置资源
│       ├── splib06b        # USGS 光谱库（21MB）
│       ├── rf.json         # 矿物规则库（77 矿物 + 混合配方 + 波长映射）
│       └── color_table.json # 矿物 RGB 颜色表（77 矿物）
├── requirements.txt
├── test_lib.py             # 端到端自测
└── visualize_*.py          # top-10 特征 PDF 生成

全部资源内置 geoahsi/data/：splib06b / rf.json / color_table.json / DEFAULT_MUS_TABLE 常量。 MicaEngine() 和 MicaClassifier.from_paths() / ResultRenderer.from_paths() 零参数即可构造，库仅依赖输入 EMIT NetCDF 影像。

三组件通过 ClassificationResult 数据契约衔接：

EmitReader.load ─► (spectrum, lon, lat, w, bp)        # 坏波段已剔除
    │
    ▼
MicaClassifier.classify(spectrum, w, bp) ─► ClassificationResult(fit, depth, num, mus_center, ...)
    │
    ▼
ResultRenderer.render ─► (orth_rgb, color_enhanced, mus_image)
    │
    ▼
ResultRenderer.write_tiff ─► 3 × GeoTIFF

外部资源

资源	用途	状态
USGS splib06b	光谱库	已内置 geoahsi/data/splib06b
rf.json	矿物规则库	已内置 geoahsi/data/rf.json
矿物颜色表	矿物→RGB	已内置 geoahsi/data/color_table.json
白云母色表	mus_image 着色	已内置 DEFAULT_MUS_TABLE 常量
EMIT L2A NetCDF	输入影像	外部（必传）

安装

pip install -r requirements.txt
# GDAL 通过 conda：
conda install -c conda-forge gdal

用法

方式一：facade（最简，自动加载资源）

from geoahsi import MicaEngine

engine = MicaEngine()   # 零参数，全部资源内置

spectrum, lon, lat, w, bp = engine.load_emit("./EMIT_xxx.nc")   # 坏波段已剔除
orth_rgb, color_enhanced, mus_image = engine.spectrum_analysis(
    spectrum, w, bp, n_workers=8
)
engine.write_tiff("./EMIT_xxx", lon, lat, orth_rgb, color_enhanced, mus_image)

方式二：直接用三组件（核心库，自包含 from_paths）

from geoahsi.emit_reader import EmitReader
from geoahsi.classifier import MicaClassifier
from geoahsi.renderer import ResultRenderer

# 三组件各自零参数构造（全内置）
clf = MicaClassifier.from_paths()
rnd = ResultRenderer.from_paths()

# 读影像
spectrum, lon, lat, w, bp = EmitReader.load("./EMIT_xxx.nc")

# 分类 → ClassificationResult（无颜色/图像）
result = clf.classify(spectrum, w, bp, n_workers=8)

# 渲染 + 输出
orth, color, mus = rnd.render(result)
rnd.write_tiff("./EMIT_xxx", lon, lat, orth, color, mus)

单像元 Top-N 识别

engine = MicaEngine()   # 零参数，全内置
spectrum, lon, lat, w, bp = engine.load_emit("./EMIT_xxx.nc")
pixel = spectrum[row, col, :]                       # 已是有效波段，无需再切片
top = engine.classify_spectrum(pixel, w, bp, top_n=10)
# [{"name": "muscovite_medAl", "fit": 0.98, "fd": 0.13}, ...]
# 传 pdf_path=... 可额外输出 Top-N 特征连续统去除多页 PDF

单像元 vs 单条参考光谱匹配

按 rf.json 中指定矿物的专家规则匹配单条像元光谱，可选生成匹配过程可视化 PDF （逐特征连续统去除 + 每道关卡 PASS/REJECT 判定，仿 pixel_features.pdf）。

engine = MicaEngine()
spectrum, lon, lat, w, bp = engine.load_emit("./EMIT_xxx.nc")
pixel = spectrum[row, col, :]

r = engine.match_reference(
    pixel, w, bp,
    mineral_key="calcite.8+montmorilloniteNa.2_mix_intimate",   # rf.json 中的 key
    pdf_path="./match.pdf",   # 可选；不传则只返回结果不出图
)
# {"name": "...", "fit": 0.9457, "fd": 0.0659, "accept": True}
# fit 为 NaN 表示被某道专家规则关卡否决（accept=False）

mineral_key 可用 list(engine.rf.keys()) 查看全部 77 个候选（纯端元如 calcite / muscovite_medAl，混合如 calcite.8+montmorilloniteNa.2_mix_intimate）。

主要 API

组件	方法	说明
EmitReader.load(path)	静态	读 EMIT NetCDF + 坏波段剔除 → spectrum, lon, lat, w, bp
MicaClassifier.from_paths(rf, splib)	类方法	加载资源构造分类器
MicaClassifier.classify(spectrum, w, bp, ...)		整景分类 → ClassificationResult
MicaClassifier.classify_spectrum(spectrum, w, bp, top_n)		单光谱 Top-N
MicaClassifier.get_resample(w, bp)		参考光谱重采样
ResultRenderer.from_paths(txt, tif)	类方法	加载颜色表构造渲染器
ResultRenderer.render(result)		ClassificationResult → 3 张 RGB 图
ResultRenderer.write_tiff(path, lon, lat, ...)	静态	写 3 张 GeoTIFF
ResultRenderer.plot_features_pdf(...)	静态	Top-N 特征连续统去除多页 PDF
ResultRenderer.plot_rule_match_pdf(...)	静态	单矿物匹配过程可视化 PDF
MicaEngine(...)	facade	组合三者的便捷入口
MicaEngine.load_emit(path)	静态	委托 EmitReader.load
MicaEngine.spectrum_analysis(spectrum, w, bp, ...)		整景分类 + 渲染
MicaEngine.classify_spectrum(spectrum, w, bp, top_n, pdf_path)		单像元 Top-N（+可选 PDF）
MicaEngine.match_reference(spectrum, w, bp, mineral_key, pdf_path)		单像元 vs 单条参考光谱匹配（+可选过程 PDF）
MicaEngine.write_tiff(path, lon, lat, ...)		写 3 张 GeoTIFF

参数

• n_workers：矿物级并行进程数。<=1 串行；None 默认 min(cpu_count, 8)。
• spectrum_analysis 支持 progress_callback / log_callback / cancel_flag 回调。
• match_reference 的 mineral_key 必须为 rf.json 中已有的 key，否则抛 KeyError（提示可用示例）。
• classify_spectrum / match_reference 的 pdf_path 需 matplotlib（pip install 'geoahsi[viz]'）。

性能

实测（1280×1242 EMIT 影像，24 核机器）：

• 串行 ~175s，并行 nw=8 ~80s。
• 输出与 mica_app.py 原版逐比特一致（闭式 2×2 最小二乘 + det==0 奇异守卫）。

算法

• 连续统去除 + 闭式 2×2 最小二乘拟合（R² + 吸收深度）。
• 三层过滤：连续统约束 → 诊断特征 + 非特征排除 → 加权约束。
• 可选深度比值约束（rf.json 的 max_depth_ratio_feat1_over_feat0，6 个白云母纯端元）。
• 白云母 2.2μm 吸收中心抛物线拟合 → 10 档着色。