eccodes

此 crate 包含（主要是）对 ecCodes 库的安全高级绑定。绑定被认为是安全的，主要是因为所有 crate 结构在将原始指针传递给 ecCodes 之前将拥有内存中的数据。

目前只支持读取 GRIB 文件。

由于 ecCodes 库 API 的特性，这些绑定相对较厚，以便使此 crate 更安全、更方便使用。

此 crate 正式支持的主要平台是 Linux，与 ecCodes 库相同。但可以在 MacOS 上安装 ecCodes，并且此 crate 成功编译并通过了所有测试。

如果您想更快地看到更多功能的发布，请毫不犹豫地贡献并查看 Github 仓库。

ecCodes 是一个开源库，用于读取和写入 GRIB 和 BUFR 文件，由 欧洲中期天气预报中心 开发。

使用方法

ecCodes 安装

此 crate 使用默认选项使用 eccodes-sys 链接 ecCodes。有关如何链接库的更多详细信息，请查看 eccodes-sys 网站。

在您的计算机上安装 ecCodes 的推荐方法是使用您的包管理器。例如，在 Ubuntu 上，您可以使用 apt-get

sudo apt-get install libeccodes-dev

或 MacOS 上的 brew

brew install eccodes

或者，您可以从源代码手动安装库到合适的目录，按照 这些说明 进行。

然后，将 ecCodes 安装目录中的 lib/pkgconfig 目录添加到 PKG_CONFIG_PATH 环境变量。如果 ecCodes 已编译为共享库，您还需要指定 LD_LIBRARY_PATH。例如

export PKG_CONFIG_PATH=<your_eccodes_path>/lib/pkgconfig
export LD_LIBRARY_PATH=<your_eccodes_path>/lib

处理 GRIB 文件

要访问 GRIB 文件，您需要使用提供的构造函数之一创建 CodesHandle。

GRIB 文件由表示特定时间和级别的数据字段的报文组成。报文由 KeyedMessage 结构表示。

CodesHandle 实现了 FallibleStreamingIterator，允许您遍历文件中的消息。迭代器返回 &KeyedMessage，直到下一次迭代都是有效的。KeyedMessage 实现了多个方法来按需访问数据，其中大多数可以直接在 &KeyedMessage 上调用。您还可以使用 try_clone() 来克隆消息并延长其生命周期。

KeyedMessage 定义的并由其包含的数据由 Key 表示。您可以直接使用 read_key() 读取它们，使用 KeysIterator 遍历它们，或者使用 CodesNearest 获取给定坐标的四个最近网格点的值。

您还可以使用 write_key() 修改消息，并使用 write_to_file() 将其写入新文件。

示例

// We are reading the mean sea level pressure for 4 gridpoints
// nearest to Reykjavik (64.13N, -21.89E) for 1st June 2021 00:00 UTC
// from ERA5 Climate Reanalysis

use eccodes::{ProductKind, CodesHandle, KeyType};
use eccodes::FallibleStreamingIterator;

// Open the GRIB file and create the CodesHandle
let file_path = Path::new("./data/iceland.grib");
let product_kind = ProductKind::GRIB;
let mut handle = CodesHandle::new_from_file(file_path, product_kind)?;

// Use iterator to find a message with shortName "msl" and typeOfLevel "surface"
// We can use while let or for_each() to iterate over the messages
while let Some(msg) = handle.next()? {
    if msg.read_key("shortName")?.value == KeyType::Str("msl".to_string())
        && msg.read_key("typeOfLevel")?.value == KeyType::Str("surface".to_string()) {
       
        // Create CodesNearest for given message
        let nearest_gridpoints = msg.codes_nearest()?
            // Find the nearest gridpoints to Reykjavik
            .find_nearest(64.13, -21.89)?;
        // Print value and distance of the nearest gridpoint
        println!("value: {}, distance: {}",
            nearest_gridpoints[3].value,
            nearest_gridpoints[3].distance);
    }
}

编写 GRIB 文件

该包提供了设置 KeyedMessage 键和编写 GRIB 文件的基本支持。创建新自定义消息最简单（也是最安全）的方法是从其他 GRIB 文件中复制现有文件，修改键并将其写入新文件。

您可以在文档中找到设置键并将消息写入文件的详细示例。

错误和恐慌

该包旨在尽可能返回错误，即使错误是由实现错误引起的。由于 ecCodes 经常用于具有长期和广泛任务的科学应用中，这使用户能够以最适合他们的方式处理错误，而不会造成崩溃。

所有错误描述都提供在 errors 模块中。不能引发恐慌的析构函数通过 log 包报告错误。

本包中的所有函数都没有明确引发恐慌。然而，用户应注意，依赖项可能在某些边缘情况下引发恐慌。

安全性

该包旨在尽可能安全，为此已经投入了大量精力进行安全测试。此外，在解引用之前，始终检查指针是否为空。

尽管如此，主要开发人员和贡献者都不具备不安全 Rust 的专业知识，因此可能会有错误遗漏。我们也不对 ecCodes 库中的错误负责。

如果您发现错误或有所建议，请随时在 Github 上讨论。

特性

• message_ndarray - 启用将 KeyedMessage 转换为 ndarray::Array 的支持。此特性默认启用。目前仅在简单的经纬度网格上进行测试。

• experimental_index - 启用为 GRIB 文件创建和使用索引文件的支持。此特性是实验性的，默认禁用。如果您想使用它，请参阅 codes_index 文档中的信息。

• docs - 构建 crate 而不链接 ecCodes，这在构建 docs.rs 上的文档时特别有用。有关更多详细信息，请参阅 eccodes-sys 的文档。

要在 docs.rs 上构建将此 crate 作为依赖项的自己的 crate 而不链接 ecCodes，请将以下行添加到您的 Cargo.toml：

[package.metadata.docs.rs]
features = ["eccodes/docs"]

许可证

ecCodes 库和这些绑定均采用 Apache License Version 2.0 许可。