tiff-nc 0.8.1

A util for converting netcdf datasets and TIFF images to and from each other

TIFF-NC 转换工具

本工具提供了将 NetCDF 文件与多波段 TIFF 文件相互转换的功能，适用于气象、地理等领域的数据处理。 地理数据及必须包含latitude、longitude两个维度。

安装

pip install tiff-nc

功能概述

1. NetCDF 转 TIFF (nc_to_tiffs)
   将 NetCDF 文件转换为多波段 TIFF 文件，支持按时间维度切片并输出多个 TIFF 文件。

2. TIFF 转 NetCDF (tiffs_to_nc)
   将多波段 TIFF 文件合并为一个 NetCDF 文件，支持按时间维度重新组织数据。

3. 计算函数 (calculate_by_dimension)
   对数据集进行计算，支持自定义函数。

4. 计算函数 (calculate_by_time)
   对数据集进行计算，支持自定义函数和时间粒度。

---

函数说明

1. nc_to_tiffs

将 NetCDF 文件转换为多波段 TIFF 文件。

参数

• nc_file (str): 输入的 NetCDF 文件路径。
• tiffs_dir (str): 输出 TIFF 文件的保存目录。
• chunks (int | dict, 可选): 分块大小，默认为 512。
• var_name (str | list[str]): 变量名或变量名列表，每个变量对应一个波段，默认为 "variable"。
• time_dim (str, 可选): 时间维度名称，默认为 "valid_time"。
• shapefile (str | None, 可选): 边界文件路径，默认为 None。
• crs (str, 可选): 坐标参考系统，默认为 "EPSG:4326"。
• time_format (str, 可选): 时间格式，默认为 "%Y%m%d"。
• workers (int, 可选): 进程数，默认为 4。

示例

nc_to_tiffs(
    nc_file="input.nc",
    tiffs_dir="output_dir",
    chunks={"valid_time": -1, "latitude": 512, "longitude": 512},
    var_name=["variable1", "variable2"],
    time_dim="valid_time",
    shapefile="boundary.shp",
    crs="EPSG:4326",
)

注意

• 该函数将输入的 NetCDF 文件转换为多波段 TIFF 文件，并支持按时间维度进行切片和输出多个 TIFF 文件。
• 该函数支持按时间维度进行切片和输出多个 TIFF 文件，并支持边界裁剪和坐标转换。
• 该函数支持边界裁剪和坐标转换，以适应不同场景的需求。
• 该函数支持多进程并行处理，以加速处理速度。
• chunks dict 的键值对表示每个维度的名称和分块大小。eg: {"valid_time": -1, "latitude": 512, "longitude": 512} 如果不指定分块大小，则设置为 -1，表示该维度不进行分块。

2. tiffs_to_nc

将多波段 TIFF 文件合并为一个 NetCDF 文件。

参数

• tiffs_dir (str): 输入 TIFF 文件的目录路径。
• nc_file (str): 输出的 NetCDF 文件路径。
• var_name (str | list[str]): 变量名或变量名列表，每个变量对应一个波段。
• time_dim (str, 可选): 时间维度名称，默认为 "valid_time"。
• chunks (dict, 可选): 分块大小，默认为 None。
• time_format (str, 可选): 时间格式，默认为 "%Y%m%d"。
• nodata (int, 可选): 缺失值，默认为 -9999。
• workers (int, 可选): 工作进程数，默认为 4。
• attrs (dict[str, str], 可选): 全局属性，默认为 {}。
• vars_attrs (dict[str, dict[str, str]], 可选): 变量属性，默认为 {}。例如：{"variable1": {"units": "m", "long_name": "Height"}, "variable2": {"units": "K", "long_name": "Temperature"}}。

示例

tiffs_to_nc(
    tiffs_dir="input_dir",
    nc_file="output.nc",
    var_name=["variable1", "variable2"],
    time_dim="valid_time",
    chunks={"valid_time": -1, "latitude": 512, "longitude": 512},
    time_format="%Y%m%d",
    workers=4,
    nodata= -9999,
    attrs={"title": "Example Dataset", "institution": "Example Institution"},
    vars_attrs={
        "variable1": {"units": "m", "long_name": "Height"},
        "variable2": {"units": "K", "long_name": "Temperature"}
    }
)

注意

• 该函数将输入的多波段 TIFF 文件合并为一个 NetCDF 文件，并支持按时间维度进行重新组织数据。
• 该函数支持按时间维度进行重新组织数据，并支持多进程并行处理，以加速处理速度。
• chunks dict 的键值对表示每个维度的名称和分块大小。eg: {"valid_time": -1, "latitude": 512, "longitude": 512} 如果不指定分块大小，则设置为 -1，表示该维度不进行分块。

3、 calculate_by_dimension

沿指定维度对数据集进行计算，支持自定义函数。

参数

• func (Callable): 需包含numpy.ndarray参数的计算函数（支持numba加速）
• ds (xr.Dataset): 输入数据集
• dim (str|list[str]): 维度名称，默认为 "valid_time"
• kwargs (dict): 传递给func的额外参数
• chunks (dict): 分块配置（键为维度名，值为分块大小）
• var_name (str): 数据变量名，默认为 "variable"

示例

# 计算时间维度的平均值
def mean_func(ndarray):
    return ndarray.mean(axis=0)

result = calculate_by_dimension(
    func=mean_func,
    ds=ds,
    dim="valid_time",
    var_name="precipitation"
)

注意

• 时间维度必须存在于输入数据集中
• func必须包含numpy.ndarray类型的参数
• 支持通过time_selection参数实现时间维度的聚合计算
• 分块配置中若维度不存在或分块大小超过维度长度将抛出异常

4. calculate_by_time

按时间维度对数据集进行计算，支持自定义时间粒度。

参数

• func (Callable): 需包含numpy.ndarray参数的计算函数（支持numba加速）
• ds (xr.Dataset): 输入数据集
• time_dim (str, 可选): 时间维度名称，默认为 "valid_time"
• kwargs (Mapping[str,Any] | None): 传递给func的额外参数，默认为None
• chunks (dict[str,int] | None): 分块配置（键为维度名，值为分块大小），默认为None
• var_name (str): 数据变量名，默认为 "variable"
• time_selection (Literal['YE', 'ME', 'QS-DEC', 'QS-JAN']): 时间粒度选择：
  • YE: 按年聚合
  • ME: 按月聚合
  • QS-DEC: 以12月为年末的季度
  • QS-JAN: 以1月为年末的季度，默认为YE

示例

# 计算年度最大值
def max_func(ndarray):
    return ndarray.max(axis=0)

result = calculate_by_time(
    func=max_func,
    ds=ds,
    time_dim="valid_time",
    var_name="temperature",
    time_selection="YE"
)

注意

• 时间维度必须存在于输入数据集中
• func必须包含numpy.ndarray类型的参数
• 支持通过time_selection参数实现时间维度的聚合计算
• 分块配置中若维度不存在或分块大小超过维度长度将抛出异常