通用绘图模块使用指南

概述

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

主要功能

1. CSV到Shapefile转换

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. 矢量到栅格转换

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. 栅格地图绘制

基础用法

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
)

高级功能 - 分辨率调整和空间插值

# 高分辨率输出（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. 直方图绘制

hist_path = mapper.create_histogram(
    file_path="data.tif",
    save_path="histogram.jpg",
    figsize=(10, 6),
    xlabel='数值',
    ylabel='频率',
    title='数值分布',
    dpi=300
)

5. 完整工作流

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种预定义的色彩方案：

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 类已经更新为使用通用绘图模块，保持了原有的接口不变：

from Cd_Prediction_Integrated_System.analysis.visualization import Visualizer

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

Water目录

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

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中使用

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}

在服务中使用

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"
        )

注意事项

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

错误处理

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

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}")

mapping_utils_guide.md 5.9 KB Historik Rå