# 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 反馈。