HSI/CLI_README.md

高光谱分析工具包 - 统一命令行接口

📖 概述

本工具包提供统一的命令行接口 (main.py)，支持动态导入和调用所有功能模块，无需手动管理复杂的参数和依赖关系。

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 查看帮助

# 查看所有可用命令
python main.py --help

# 查看特定任务的帮助
python main.py dim-reduction --help
python main.py classification --help

3. 查看可用任务

python main.py list

📋 可用任务

🔬 数据预处理

• preprocessing: 数据预处理（标准化、异常值处理等）

📊 降维分析

• dim-reduction: 高光谱数据降维（PCA、ICA、LDA等）

🎯 图像分割

• segmentation: 阈值分割（Otsu、ISODATA等）

⚡ 边缘检测

• edge-detection: 图像边缘检测（Canny、Sobel等）

🔍 异常检测

• anomaly-detection: 异常像素检测（协方差、单类SVM等）

🏷️ 分类分析

• classification: 监督分类（SVM、随机森林等）

📈 聚类分析

• clustering: 无监督聚类（K-Means、GMM等）

🎯 特征选择

• feature-selection: 特征选择算法（SPA、CARS等）

🌿 光谱指数

• spectral-index: 光谱指数计算（NDVI、EVI等）

📐 形状特征

• shape-features: 形状特征分析

🎨 颜色分析

• color-analysis: 色差计算分析

🔧 图像滤波

• filtering: 空间/形态学滤波

📈 回归分析

• regression: 回归模型分析

💡 使用示例

降维分析

# PCA降维到3个组件
python main.py dim-reduction --input data.hdr --method pca --n-components 3 --output-dir results

# 批量降维分析
python main.py dim-reduction --input data.hdr --method pca --batch --output-dir results/batch

图像分割

# Otsu自动阈值分割
python main.py segmentation --input data.hdr --method otsu --band-index 100 --output-dir results

# 固定阈值分割
python main.py segmentation --input data.hdr --method fixed --threshold 0.5 --band-index 50 --output-dir results

分类分析

# SVM分类（需要ROI文件）
python main.py classification --input data.hdr --roi-file roi.xml --method svm --output-dir results

# 随机森林分类
python main.py classification --input data.hdr --roi-file roi.xml --method rf --output-dir results

光谱指数计算

# 计算指定指数
python main.py spectral-index --input data.hdr --indices NDVI EVI ARVI --png --output-dir results

# 计算所有指数
python main.py spectral-index --input data.hdr --batch --png --output-dir results/indices

异常检测

# 协方差异常检测
python main.py anomaly-detection --input data.hdr --method covariance --contamination 0.1 --output-dir results

聚类分析

# K-Means聚类
python main.py clustering --input data.hdr --method kmeans --n-clusters 5 --output-dir results

# 高斯混合模型聚类
python main.py clustering --input data.hdr --method gmm --n-clusters 3 --output-dir results

特征选择

# SPA算法选择特征
python main.py feature-selection --input data.csv --label-column target --method spa --n-features 20 --output-dir results

数据预处理

# 标准化处理
python main.py preprocessing --input data.csv --method standard --handle-outliers --output-dir results

形状特征分析

# 分析分割结果的形状特征
python main.py shape-features --input segmented.dat --input-type dat --band-index 0 --min-area 50 --output-dir results

📁 输出文件

每个任务执行后会生成以下文件：

• <task>_<prefix>.dat/.hdr: 主要结果文件（ENVI格式）
• <task>_summary.json: 任务执行摘要
• execution_log.json: 执行日志
• <task>_report.html: HTML格式的详细报告
• 可视化文件: PNG格式的图表和图像

⚙️ 通用参数

所有任务都支持以下通用参数：

• --input, -i: 输入文件路径（必需）
• --output-dir, -o: 输出目录（默认: ./results）
• --output-prefix: 输出文件前缀（默认: result）

🔧 高级选项

调试模式

# 启用详细错误信息
python main.py <task> [参数...] --debug

批量处理

许多任务支持批量处理模式：

# 批量降维
python main.py dim-reduction --input data.hdr --batch

# 批量分割
python main.py segmentation --input data.hdr --batch

# 批量边缘检测
python main.py edge-detection --input data.hdr --batch

自定义参数

# 自定义降维组件数
python main.py dim-reduction --input data.hdr --n-components 10

# 自定义聚类数
python main.py clustering --input data.hdr --n-clusters 8

# 自定义特征数量
python main.py feature-selection --input data.csv --n-features 50

📊 结果查看

命令行摘要

执行完成后会显示彩色的执行摘要，包括：

• 任务名称和执行时间
• 输入参数
• 结果统计信息
• 输出文件列表

HTML报告

打开生成的 <task>_report.html 文件查看详细的执行报告，包含：

• 执行参数
• 结果统计
• 可视化图表
• 文件信息

JSON摘要

<task>_summary.json 包含结构化的结果摘要，可用于进一步处理。

🚨 故障排除

常见问题

1. 文件不存在错误

   • 检查输入文件路径是否正确
   • 确保文件有适当的读取权限

2. 内存不足错误

   • 对于大型高光谱数据，考虑增加系统内存
   • 或使用降维预处理减少数据大小

3. 依赖包错误

   • 确保已安装所有必需的依赖包
   • 运行 pip install -r requirements.txt

4. 参数错误

   • 使用 --help 查看正确的参数格式
   • 检查参数值是否在有效范围内

获取帮助

# 通用帮助
python main.py --help

# 任务特定帮助
python main.py <task-name> --help

# 查看示例
python examples.py

🏗️ 架构说明

模块化设计

• main.py: 主入口，参数解析和任务分发
• registry.py: 模块注册表，管理所有任务信息
• validators.py: 输入验证和错误检查
• output_handler.py: 统一输出处理和报告生成

动态导入

系统使用 Python 的 importlib 实现动态模块导入，确保：

• 只在需要时加载相关模块
• 减少启动时间和内存占用
• 支持模块的独立开发和维护

参数验证

内置多层参数验证：

• 文件存在性和格式检查
• 参数范围和类型验证
• 数据维度和大小验证
• 任务特定逻辑验证

📝 开发说明

添加新任务

1. 在相应模块中实现功能
2. 在 registry.py 中添加任务注册信息
3. 创建对应的参数构建器类
4. 更新文档和示例

扩展验证

在 validators.py 中添加新的验证逻辑，确保输入数据的正确性。

自定义输出

在 output_handler.py 中添加新的输出格式或报告类型。

🤝 贡献

欢迎提交问题报告和功能建议！请确保：

• 提供详细的问题描述
• 包含错误信息和环境信息
• 建议新功能时说明使用场景