223 lines
6.0 KiB
Markdown
223 lines
6.0 KiB
Markdown
# AI Earth App
|
||
|
||
一个基于 Streamlit 和 Leafmap 构建的交互式 COG (Cloud Optimized GeoTIFF) 地图查看器应用。支持在线加载、可视化和分析云优化的地理空间栅格数据。
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 核心功能
|
||
- 🗺️ **COG 数据加载**: 支持通过 URL 加载云优化的 GeoTIFF 文件
|
||
- 📊 **波段配置**: 灵活配置多波段索引和波段计算表达式（如 NDVI、NDWI 等）
|
||
- 🎨 **颜色映射**: 内置 60+ 种颜色映射方案，支持自定义颜色映射
|
||
- 🔍 **自动定位**: 自动获取 COG 边界信息并定位地图视图
|
||
- 📏 **数值范围调整**: 可自定义数据值的重缩放范围
|
||
- 🎛️ **图层控制**: 支持多图层叠加显示，可调整透明度
|
||
- 📍 **边界框显示**: 可选显示 COG 数据的边界框
|
||
|
||
### 技术特性
|
||
- ⚡ **高性能**: 基于 Titiler 服务进行瓦片化渲染，支持大数据量
|
||
- 🌐 **Web 标准**: 使用 Web Mercator 投影，兼容标准地图服务
|
||
- 🖥️ **响应式界面**: 宽屏布局，适配不同屏幕尺寸
|
||
- 🔄 **实时更新**: 修改配置后实时更新地图显示
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
- **Streamlit** (>=1.28.0): Web 应用框架，提供交互式界面
|
||
- **Leafmap** (>=0.25.0): 地理空间可视化库，基于 Folium
|
||
- **Folium** (>=0.14.0): 交互式地图库
|
||
- **Requests** (>=2.31.0): HTTP 请求库，用于与 Titiler API 通信
|
||
- **Titiler**: 外部服务，用于 COG 数据的瓦片化处理
|
||
|
||
## 📋 系统要求
|
||
|
||
- Python >= 3.11
|
||
- 网络连接（用于访问 COG 数据和 Titiler 服务）
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式一：使用 pip 安装
|
||
|
||
1. **克隆或下载项目**
|
||
```bash
|
||
cd aiearthapp
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
或者直接安装依赖：
|
||
```bash
|
||
pip install streamlit leafmap folium requests
|
||
```
|
||
|
||
3. **运行应用**
|
||
```bash
|
||
streamlit run main.py
|
||
```
|
||
|
||
应用将在浏览器中自动打开，默认地址为 `http://localhost:8501`
|
||
|
||
### 方式二：使用 Docker
|
||
|
||
1. **使用 Docker Compose（推荐）**
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
2. **或使用 Docker 命令**
|
||
```bash
|
||
docker build -t aiearthapp .
|
||
docker run -p 8501:8501 aiearthapp
|
||
```
|
||
|
||
访问 `http://localhost:8501` 查看应用
|
||
|
||
## 📖 使用说明
|
||
|
||
### 基本操作流程
|
||
|
||
1. **输入 COG URL**
|
||
- 在侧边栏的"数据源"部分输入 COG 文件的 URL 地址
|
||
- 支持 HTTP/HTTPS 协议的可访问 URL
|
||
- 示例：`http://minio.minio-dev:9000/staticfiles/s2_mosaic_cog.tif`
|
||
|
||
2. **配置波段和表达式**
|
||
- **波段索引 (indexes)**: 指定要使用的波段，用逗号分隔（如：`4,8`）
|
||
- **表达式 (expression)**: 输入波段计算表达式（如：`(b2-b1)/(b2+b1)` 表示 NDVI）
|
||
- 表达式中的 `b1`, `b2` 等对应索引中的第 1、2 个波段
|
||
|
||
3. **调整数值范围**
|
||
- 设置 **最小值 (rescale min)** 和 **最大值 (rescale max)**
|
||
- 用于将数据值映射到 0-255 范围进行显示
|
||
|
||
4. **选择颜色映射**
|
||
- 从下拉列表选择预设的颜色映射方案
|
||
- 或勾选"使用自定义颜色映射"输入自定义方案名称
|
||
|
||
5. **调整显示设置**
|
||
- 调整图层透明度（0.0 - 1.0）
|
||
- 设置图层名称（用于图层控制面板）
|
||
|
||
6. **获取 COG 信息**
|
||
- 点击"🔄 获取 COG 信息"按钮手动获取数据信息
|
||
- 或勾选"自动定位到 COG 范围"实现自动获取和定位
|
||
|
||
### 常用表达式示例
|
||
|
||
- **NDVI (归一化植被指数)**: `(b2-b1)/(b2+b1)`
|
||
- **NDWI (归一化水体指数)**: `(b1-b2)/(b1+b2)`
|
||
- **简单比值**: `b2/b1`
|
||
- **差值**: `b2-b1`
|
||
- **多波段组合**: `(b1+b2+b3)/3` (平均值)
|
||
|
||
### 界面交互
|
||
|
||
- **地图操作**:
|
||
- 拖拽移动地图
|
||
- 鼠标滚轮缩放
|
||
- 使用图层控制面板切换底图和 COG 图层
|
||
|
||
- **侧边栏功能**:
|
||
- 展开/折叠各个配置区域
|
||
- 查看 COG 详细信息（边界、尺寸、波段数等）
|
||
- 查看使用说明
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### COG URL 格式
|
||
|
||
COG URL 必须是可公开访问的 HTTP/HTTPS 地址，指向有效的 Cloud Optimized GeoTIFF 文件。
|
||
|
||
### Titiler 服务
|
||
|
||
应用默认使用 `https://titiler.dev.maimaiag.com` 作为 Titiler 服务地址。如需修改，请编辑 `main.py` 中的相关 URL。
|
||
|
||
### 颜色映射选项
|
||
|
||
应用支持 Titiler 兼容的所有颜色映射方案，包括：
|
||
- 科学可视化：`viridis`, `plasma`, `inferno`, `magma`, `cividis`
|
||
- 光谱映射：`spectral`, `rdylgn`, `rdylbu`, `turbo`, `jet`
|
||
- 地形映射：`terrain`, `gist_earth`
|
||
- 以及其他 50+ 种方案
|
||
|
||
## 🐳 Docker 部署
|
||
|
||
### 使用 Docker Compose
|
||
|
||
项目包含 `docker-compose.yml` 文件，可直接使用：
|
||
|
||
```bash
|
||
# 启动服务
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
```
|
||
|
||
### 自定义配置
|
||
|
||
可以通过环境变量配置 Streamlit：
|
||
|
||
```yaml
|
||
environment:
|
||
- STREAMLIT_SERVER_PORT=8501
|
||
- STREAMLIT_SERVER_ADDRESS=0.0.0.0
|
||
```
|
||
|
||
## 🔧 故障排查
|
||
|
||
### 常见问题
|
||
|
||
1. **无法获取 COG 信息**
|
||
- 检查 COG URL 是否正确且可访问
|
||
- 确认网络连接正常
|
||
- 检查 Titiler 服务是否可用
|
||
|
||
2. **地图不显示 COG 图层**
|
||
- 确认已获取 COG 边界信息
|
||
- 检查波段索引和表达式是否正确
|
||
- 查看浏览器控制台是否有错误信息
|
||
|
||
3. **颜色显示异常**
|
||
- 调整数值范围（rescale min/max）
|
||
- 尝试不同的颜色映射方案
|
||
- 检查表达式计算结果是否在合理范围内
|
||
|
||
4. **Docker 容器无法启动**
|
||
- 检查端口 8501 是否被占用
|
||
- 查看容器日志：`docker-compose logs`
|
||
- 确认 Docker 和 Docker Compose 版本兼容
|
||
|
||
## 📝 开发说明
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
aiearthapp/
|
||
├── main.py # 主应用文件
|
||
├── pyproject.toml # 项目配置和依赖
|
||
├── Dockerfile # Docker 镜像构建文件
|
||
├── docker-compose.yml # Docker Compose 配置
|
||
└── README.md # 项目文档
|
||
```
|
||
|
||
### 依赖管理
|
||
|
||
项目使用 `pyproject.toml` 管理依赖，支持使用 `uv` 或 `pip` 安装。
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证。
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📧 联系方式
|
||
|
||
如有问题或建议，请通过 Issue 反馈。
|