# 通用绘图模块使用指南

## 概述

`app.utils.mapping_utils` 是一个统一的绘图工具模块，整合了CSV转GeoTIFF、栅格地图绘制和直方图生成等功能。该模块提供了标准化的接口，供项目中的所有组件调用。

## 主要功能

### 1. CSV到Shapefile转换
```python
from app.utils.mapping_utils import MappingUtils

mapper = MappingUtils()
shapefile_path = mapper.csv_to_shapefile(
    csv_file="data.csv",
    shapefile_output="output.shp",
    lon_col=0,  # 经度列索引或列名
    lat_col=1,  # 纬度列索引或列名
    value_col=2  # 数值列索引或列名
)
```

### 2. 矢量到栅格转换
```python
raster_path, stats = mapper.vector_to_raster(
    input_shapefile="points.shp",
    template_tif="template.tif",
    output_tif="output.tif",
    field="value_field",
    resolution_factor=1.0,  # 分辨率倍数
    boundary_shp="boundary.shp",  # 可选边界文件
    interpolation_method='nearest'  # 插值方法
)
```

### 3. 栅格地图绘制

#### 基础用法
```python
map_path = mapper.create_raster_map(
    shp_path="boundary.shp",
    tif_path="data.tif",
    output_path="map",  # 不包含扩展名
    colormap='green_yellow_red_purple',  # 色彩方案
    title="预测结果地图",
    output_size=12,  # 图片尺寸
    dpi=300
)
```

#### 高级功能 - 分辨率调整和空间插值
```python
# 高分辨率输出（2倍分辨率）
map_path = mapper.create_raster_map(
    shp_path="boundary.shp",
    tif_path="data.tif",
    output_path="high_res_map",
    resolution_factor=2.0,           # 提高分辨率
    enable_interpolation=True,       # 启用插值
    interpolation_method='linear',   # 使用线性插值
    title="高分辨率地图"
)

# 低分辨率快速预览（0.5倍分辨率）
map_path = mapper.create_raster_map(
    shp_path="boundary.shp",
    tif_path="data.tif",
    output_path="preview_map",
    resolution_factor=0.5,           # 降低分辨率
    enable_interpolation=False,      # 不使用插值
    title="预览地图"
)
```

**新增参数说明：**
- `resolution_factor`: 分辨率因子（默认1.0）
  - `> 1.0`: 提高分辨率
  - `< 1.0`: 降低分辨率
- `enable_interpolation`: 是否启用空间插值（默认False）
- `interpolation_method`: 插值方法（默认'nearest'）
  - `'nearest'`: 最近邻插值（速度最快）
  - `'linear'`: 线性插值（平衡效果和速度）
  - `'cubic'`: 三次插值（效果最好但速度较慢）

### 4. 直方图绘制
```python
hist_path = mapper.create_histogram(
    file_path="data.tif",
    save_path="histogram.jpg",
    figsize=(10, 6),
    xlabel='数值',
    ylabel='频率',
    title='数值分布',
    dpi=300
)
```

### 5. 完整工作流
```python
from app.utils.mapping_utils import csv_to_raster_workflow

results = csv_to_raster_workflow(
    csv_file="data.csv",
    template_tif="template.tif",
    output_dir="output/",
    boundary_shp="boundary.shp",
    resolution_factor=1.0
)
# 返回：{'shapefile': '...', 'raster': '...', 'statistics': {...}}
```

## 预定义色彩方案

模块提供了6种预定义的色彩方案：

```python
from app.utils.mapping_utils import COLORMAPS, get_available_colormaps

# 获取所有可用的色彩方案
colormaps = get_available_colormaps()

# 可用方案：
# - 'yellow_orange_brown': 黄-橙-棕
# - 'blue_series': 蓝色系  
# - 'yellow_green': 淡黄-草绿
# - 'green_brown': 绿色-棕色
# - 'yellow_pink_purple': 黄-粉-紫
# - 'green_yellow_red_purple': 绿-黄-红-紫
```

## 与现有代码的兼容性

### Cd_Prediction_Integrated_System

现有的 `Visualizer` 类已经更新为使用通用绘图模块，保持了原有的接口不变：

```python
from Cd_Prediction_Integrated_System.analysis.visualization import Visualizer

visualizer = Visualizer()
# 原有接口依然可用
map_path = visualizer.create_raster_map(...)
hist_path = visualizer.create_histogram(...)
```

### Water目录

Water目录中的绘图函数已经更新为调用通用模块：

```python
from Water.Python_codes.Figure_raster_mapping import mapping_raster, plot_tif_histogram

# 原有接口依然可用
map_path = mapping_raster(shp_path, tif_path, colormap, title, output_path, size)
hist_path = plot_tif_histogram(file_path, figsize, xlabel, ylabel, title, save_path)
```

## 在其他模块中使用

### 在API中使用
```python
from app.utils.mapping_utils import MappingUtils

def create_prediction_map(data_file, output_dir):
    mapper = MappingUtils()
    
    # 创建地图
    map_path = mapper.create_raster_map(
        tif_path=data_file,
        output_path=f"{output_dir}/prediction_map",
        title="预测结果"
    )
    
    # 创建直方图
    hist_path = mapper.create_histogram(
        file_path=data_file,
        save_path=f"{output_dir}/prediction_histogram.jpg",
        title="预测值分布"
    )
    
    return {"map": map_path, "histogram": hist_path}
```

### 在服务中使用
```python
from app.utils.mapping_utils import MappingUtils

class VisualizationService:
    def __init__(self):
        self.mapper = MappingUtils()
    
    def generate_maps(self, raster_file, boundary_file=None):
        return self.mapper.create_raster_map(
            shp_path=boundary_file,
            tif_path=raster_file,
            output_path="output/map"
        )
```

## 注意事项

1. **文件路径**: 确保输入文件存在且可读
2. **坐标系**: 矢量和栅格数据的坐标系会自动处理
3. **输出目录**: 输出目录会自动创建
4. **内存使用**: 大型栅格文件可能占用较多内存
5. **依赖库**: 需要安装 geopandas, rasterio, matplotlib, seaborn 等依赖

## 错误处理

所有函数都包含了完整的错误处理和日志记录：

```python
try:
    result = mapper.create_raster_map(...)
except FileNotFoundError as e:
    print(f"文件不存在: {e}")
except ValueError as e:
    print(f"数据错误: {e}")
except Exception as e:
    print(f"处理失败: {e}")
```