netcdf-reader 0.2.0

Pure-Rust NetCDF-3 classic and NetCDF-4 (HDF5-backed) file reader
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

//! Filter and convert HDF5 attributes to NetCDF-4 attributes.
//!
//! NetCDF-4 uses several internal HDF5 attributes that should not be exposed
//! to users:
//! - `_NCProperties`: file provenance metadata
//! - `_Netcdf4Dimid`: dimension ID assignment
//! - `_Netcdf4Coordinates`: coordinate variable tracking
//! - `DIMENSION_LIST`: dimension-to-variable references
//! - `REFERENCE_LIST`: variable-to-dimension back-references
//! - `CLASS`: dimension scale marker
//! - `NAME`: dimension scale name

use hdf5_reader::group::Group;
use hdf5_reader::messages::datatype::Datatype;

use crate::error::Result;
use crate::types::{NcAttrValue, NcAttribute};

/// Internal attribute names that should be hidden from the NetCDF user API.
const INTERNAL_ATTRIBUTES: &[&str] = &[
    "_NCProperties",
    "_Netcdf4Dimid",
    "_Netcdf4Coordinates",
    "_nc3_strict",
    "DIMENSION_LIST",
    "REFERENCE_LIST",
    "CLASS",
    "NAME",
];

/// Returns true if the given attribute name is an internal NetCDF-4/HDF5 attribute
/// that should not be exposed to users.
pub fn is_internal_attribute(name: &str) -> bool {
    INTERNAL_ATTRIBUTES.contains(&name)
}

/// Extract user-visible attributes from an HDF5 group, filtering out
/// internal NetCDF-4 attributes.
pub fn extract_group_attributes(group: &Group<'_>) -> Result<Vec<NcAttribute>> {
    let hdf5_attrs = match group.attributes() {
        Ok(a) => a,
        Err(_) => return Ok(Vec::new()),
    };

    let mut nc_attrs = Vec::new();
    for attr in &hdf5_attrs {
        if is_internal_attribute(&attr.name) {
            continue;
        }
        if let Some(nc_attr) = convert_attribute(attr) {
            nc_attrs.push(nc_attr);
        }
    }
    Ok(nc_attrs)
}

/// Extract user-visible attributes from an HDF5 dataset, filtering out
/// internal attributes.
pub fn extract_variable_attributes(dataset: &hdf5_reader::Dataset<'_>) -> Result<Vec<NcAttribute>> {
    let hdf5_attrs = dataset.attributes();
    let mut nc_attrs = Vec::new();
    for attr in &hdf5_attrs {
        if is_internal_attribute(&attr.name) {
            continue;
        }
        if let Some(nc_attr) = convert_attribute(attr) {
            nc_attrs.push(nc_attr);
        }
    }
    Ok(nc_attrs)
}

/// Convert an HDF5 attribute to a NetCDF attribute.
fn convert_attribute(attr: &hdf5_reader::Attribute) -> Option<NcAttribute> {
    let value = convert_attribute_value(attr)?;
    Some(NcAttribute {
        name: attr.name.clone(),
        value,
    })
}

/// Convert an HDF5 attribute's value to an NcAttrValue.
fn convert_attribute_value(attr: &hdf5_reader::Attribute) -> Option<NcAttrValue> {
    match &attr.datatype {
        Datatype::FixedPoint { size, signed, .. } => match (size, signed) {
            (1, true) => attr.read_1d::<i8>().ok().map(NcAttrValue::Bytes),
            (1, false) => attr.read_1d::<u8>().ok().map(NcAttrValue::UBytes),
            (2, true) => attr.read_1d::<i16>().ok().map(NcAttrValue::Shorts),
            (2, false) => attr.read_1d::<u16>().ok().map(NcAttrValue::UShorts),
            (4, true) => attr.read_1d::<i32>().ok().map(NcAttrValue::Ints),
            (4, false) => attr.read_1d::<u32>().ok().map(NcAttrValue::UInts),
            (8, true) => attr.read_1d::<i64>().ok().map(NcAttrValue::Int64s),
            (8, false) => attr.read_1d::<u64>().ok().map(NcAttrValue::UInt64s),
            _ => None,
        },
        Datatype::FloatingPoint { size, .. } => match size {
            4 => attr.read_1d::<f32>().ok().map(NcAttrValue::Floats),
            8 => attr.read_1d::<f64>().ok().map(NcAttrValue::Doubles),
            _ => None,
        },
        Datatype::String { .. } => {
            // Try reading as a single string first, then as array
            if attr.num_elements() == 1 {
                attr.read_string().ok().map(NcAttrValue::Chars)
            } else {
                attr.read_strings().ok().map(NcAttrValue::Strings)
            }
        }
        Datatype::VarLen { base }
            if attr.num_elements() == 1
                && matches!(
                    base.as_ref(),
                    Datatype::FixedPoint {
                        size: 1,
                        signed: false,
                        ..
                    }
                ) =>
        {
            attr.read_string().ok().map(NcAttrValue::Chars)
        }
        _ => None,
    }
}