Expand description
OxiGeo NetCDF Driver - Pure Rust NetCDF-4 (HDF5) with Optional NetCDF-3
This crate provides NetCDF file format support for OxiGeo, following the COOLJAPAN Pure Rust policy.
§Pure Rust Policy Compliance
Real NetCDF-4 files (which are HDF5 files carrying the NetCDF-4 conventions)
are read and written with the Pure-Rust oxinetcdf crate atop
oxih5. There is no libnetcdf, no
libhdf5, and no FFI — the default build is 100% Pure Rust.
- Reading honours the NetCDF-4 conventions: dimension scales, coordinate
variables,
DIMENSION_LISTaxis linkage, sub-groups (flattened into"<group>/<var>"names, recursively), and user attributes (units,_FillValue,scale_factor,add_offset, …) — surfaced viaVariable::attributes.read_f32/read_f64/read_i32are raw, unprocessed reads;_FillValue/scale_factor/add_offsetare applied only through the explicit opt-inNetCdfReader::read_f64_cf/NetCdfReader::read_f32_cf(CF §8.1 packed-data unpacking + §2.5.1 fill-value masking toNaN). - Writing produces real HDF5/NetCDF-4 files via the Pure-Rust backend.
- Optional NetCDF-3 classic support is available behind the
netcdf3feature (thenetcdf3crate, also Pure Rust).
§Feature Flags
std(default): standard-library support.netcdf3: Pure Rust NetCDF-3 (classic / 64-bit offset) support via thenetcdf3crate. NetCDF-4 support is always available and needs no feature.cf_conventions: CF (Climate and Forecast) conventions supportasync: Async I/O support
§NetCDF Format Support
§NetCDF-3 (Pure Rust, Default)
Fully supported data types:
i8,i16,i32- Signed integersf32,f64- Floating point numberschar- Character data
Features:
- Fixed and unlimited dimensions
- Multi-dimensional arrays
- Variable and global attributes
- Coordinate variables
§NetCDF-4 (Pure Rust, always available)
Real NetCDF-4 / HDF5 files are read and written via the Pure-Rust
oxinetcdf backend. Additional data types over NetCDF-3:
u8,u16,u32,u64- Unsigned integersi64,u64- 64-bit integersstring- Variable-length strings
Additional features:
- HDF5-based (DEFLATE) compression
- Groups and coordinate variables
- Multiple unlimited dimensions
§Example - Reading NetCDF-3 File (Pure Rust)
ⓘ
use oxigeo_netcdf::NetCdfReader;
// Open a NetCDF-3 file
let reader = NetCdfReader::open("data.nc")?;
// Get metadata
println!("{}", reader.metadata().summary());
// List dimensions
for dim in reader.dimensions().iter() {
println!("Dimension: {} (size: {})", dim.name(), dim.len());
}
// List variables
for var in reader.variables().iter() {
println!("Variable: {} (type: {})", var.name(), var.data_type().name());
}
// Read variable data
let temperature = reader.read_f32("temperature")?;
println!("Temperature data: {:?}", temperature);§Example - Writing NetCDF-3 File (Pure Rust)
ⓘ
use oxigeo_netcdf::{NetCdfWriter, NetCdfVersion};
use oxigeo_netcdf::dimension::Dimension;
use oxigeo_netcdf::variable::{Variable, DataType};
use oxigeo_netcdf::attribute::{Attribute, AttributeValue};
// Create a new NetCDF-3 file
let mut writer = NetCdfWriter::create("output.nc", NetCdfVersion::Classic)?;
// Add dimensions
writer.add_dimension(Dimension::new_unlimited("time", 0)?)?;
writer.add_dimension(Dimension::new("lat", 180)?)?;
writer.add_dimension(Dimension::new("lon", 360)?)?;
// Add coordinate variables
writer.add_variable(Variable::new_coordinate("time", DataType::F64)?)?;
writer.add_variable(Variable::new_coordinate("lat", DataType::F32)?)?;
writer.add_variable(Variable::new_coordinate("lon", DataType::F32)?)?;
// Add data variable
let temp_var = Variable::new(
"temperature",
DataType::F32,
vec!["time".to_string(), "lat".to_string(), "lon".to_string()],
)?;
writer.add_variable(temp_var)?;
// Add variable attributes
writer.add_variable_attribute(
"temperature",
Attribute::new("units", AttributeValue::text("celsius"))?,
)?;
writer.add_variable_attribute(
"temperature",
Attribute::new("long_name", AttributeValue::text("Air Temperature"))?,
)?;
// Add global attributes
writer.add_global_attribute(
Attribute::new("Conventions", AttributeValue::text("CF-1.8"))?,
)?;
writer.add_global_attribute(
Attribute::new("title", AttributeValue::text("Temperature Data"))?,
)?;
// End define mode
writer.end_define_mode()?;
// Write data
let time_data = vec![0.0, 1.0, 2.0];
writer.write_f64("time", &time_data)?;
let lat_data: Vec<f32> = (0..180).map(|i| -90.0 + i as f32).collect();
writer.write_f32("lat", &lat_data)?;
let lon_data: Vec<f32> = (0..360).map(|i| -180.0 + i as f32).collect();
writer.write_f32("lon", &lon_data)?;
// Write temperature data
let temp_data = vec![20.0f32; 3 * 180 * 360];
writer.write_f32("temperature", &temp_data)?;
// Close file
writer.close()?;§CF Conventions Support
The driver recognizes and parses CF (Climate and Forecast) conventions metadata:
ⓘ
use oxigeo_netcdf::NetCdfReader;
let reader = NetCdfReader::open("cf_data.nc")?;
if let Some(cf) = reader.cf_metadata() {
if cf.is_cf_compliant() {
println!("CF Conventions: {}", cf.conventions.as_deref().unwrap_or(""));
println!("Title: {}", cf.title.as_deref().unwrap_or(""));
println!("Institution: {}", cf.institution.as_deref().unwrap_or(""));
}
}§Pure Rust Notes
- NetCDF-4 reading/writing is Pure Rust via
oxinetcdfatopoxih5(DEFLATE compression throughoxiarc-deflate); no C libraries are used. - The Pure-Rust NetCDF-4 writer supports data variables, dimensions, and string attributes. Constructs it cannot yet represent (e.g. explicit coordinate-variable values or numeric attributes) return a typed error rather than producing an incomplete file.
- NetCDF-3 classic support is optional (
netcdf3feature) and allows only one unlimited dimension per the classic model.
§Performance Considerations
- For large datasets, consider using chunked reading/writing
- CF metadata parsing is done on-demand
§References
Re-exports§
pub use attribute::Attribute;pub use attribute::AttributeValue;pub use attribute::Attributes;pub use dimension::Dimension;pub use dimension::DimensionSize;pub use dimension::Dimensions;pub use error::NetCdfError;pub use error::Result;pub use metadata::CfMetadata;pub use metadata::NetCdfMetadata;pub use metadata::NetCdfVersion;pub use reader::NetCdfReader;pub use variable::DataType;pub use variable::Variable;pub use variable::Variables;pub use writer::NetCdfWriter;
Modules§
- attribute
- NetCDF attribute types and utilities.
- cf_
conventions - CF Conventions 1.8 Compliance Module
- dimension
- NetCDF dimension types and utilities.
- error
- Error types for NetCDF operations.
- metadata
- NetCDF file metadata structures.
- netcdf4
- A dead, unused, hand-rolled HDF5/NetCDF-4 parser/writer, kept for backward source compatibility only.
- reader
- NetCDF file reader implementation.
- variable
- NetCDF variable types and utilities.
- writer
- NetCDF file writer implementation.
Constants§
Functions§
- has_
netcdf3 - Check if NetCDF-3 support is available.
- has_
netcdf4 - Check if NetCDF-4 support is available.
- info
- Get driver information.
- is_
pure_ rust - Pure Rust compliance status
- supported_
versions - Get supported format versions.