Skip to main content

Crate oxigeo_netcdf

Crate oxigeo_netcdf 

Source
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_LIST axis linkage, sub-groups (flattened into "<group>/<var>" names, recursively), and user attributes (units, _FillValue, scale_factor, add_offset, …) — surfaced via Variable::attributes. read_f32/read_f64/read_i32 are raw, unprocessed reads; _FillValue/scale_factor/add_offset are applied only through the explicit opt-in NetCdfReader::read_f64_cf / NetCdfReader::read_f32_cf (CF §8.1 packed-data unpacking + §2.5.1 fill-value masking to NaN).
  • Writing produces real HDF5/NetCDF-4 files via the Pure-Rust backend.
  • Optional NetCDF-3 classic support is available behind the netcdf3 feature (the netcdf3 crate, also Pure Rust).

§Feature Flags

  • std (default): standard-library support.
  • netcdf3: Pure Rust NetCDF-3 (classic / 64-bit offset) support via the netcdf3 crate. NetCDF-4 support is always available and needs no feature.
  • cf_conventions: CF (Climate and Forecast) conventions support
  • async: Async I/O support

§NetCDF Format Support

§NetCDF-3 (Pure Rust, Default)

Fully supported data types:

  • i8, i16, i32 - Signed integers
  • f32, f64 - Floating point numbers
  • char - 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 integers
  • i64, u64 - 64-bit integers
  • string - 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 oxinetcdf atop oxih5 (DEFLATE compression through oxiarc-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 (netcdf3 feature) 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§

NAME
Crate name
VERSION
Crate version

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.