Skip to main content

oxigeo_netcdf/
lib.rs

1//! OxiGeo NetCDF Driver - Pure Rust NetCDF-4 (HDF5) with Optional NetCDF-3
2//!
3//! This crate provides NetCDF file format support for OxiGeo, following the
4//! COOLJAPAN Pure Rust policy.
5//!
6//! # Pure Rust Policy Compliance
7//!
8//! Real NetCDF-4 files (which are HDF5 files carrying the NetCDF-4 conventions)
9//! are read and written with the Pure-Rust [`oxinetcdf`] crate atop
10//! [`oxih5`](https://crates.io/crates/oxih5). There is **no** `libnetcdf`, no
11//! `libhdf5`, and no FFI — the default build is 100% Pure Rust.
12//!
13//! - Reading honours the NetCDF-4 conventions: dimension scales, coordinate
14//!   variables, `DIMENSION_LIST` axis linkage, sub-groups (flattened into
15//!   `"<group>/<var>"` names, recursively), and user attributes (`units`,
16//!   `_FillValue`, `scale_factor`, `add_offset`, …) — surfaced via
17//!   [`Variable::attributes`]. `read_f32`/`read_f64`/`read_i32` are raw,
18//!   unprocessed reads; `_FillValue`/`scale_factor`/`add_offset` are applied
19//!   only through the explicit opt-in [`NetCdfReader::read_f64_cf`] /
20//!   [`NetCdfReader::read_f32_cf`] (CF §8.1 packed-data unpacking + §2.5.1
21//!   fill-value masking to `NaN`).
22//! - Writing produces real HDF5/NetCDF-4 files via the Pure-Rust backend.
23//! - Optional NetCDF-3 classic support is available behind the `netcdf3`
24//!   feature (the `netcdf3` crate, also Pure Rust).
25//!
26//! ## Feature Flags
27//!
28//! - `std` (default): standard-library support.
29//! - `netcdf3`: Pure Rust NetCDF-3 (classic / 64-bit offset) support via the
30//!   `netcdf3` crate. NetCDF-4 support is always available and needs no feature.
31//! - `cf_conventions`: CF (Climate and Forecast) conventions support
32//! - `async`: Async I/O support
33//!
34//! # NetCDF Format Support
35//!
36//! ## NetCDF-3 (Pure Rust, Default)
37//!
38//! Fully supported data types:
39//! - `i8`, `i16`, `i32` - Signed integers
40//! - `f32`, `f64` - Floating point numbers
41//! - `char` - Character data
42//!
43//! Features:
44//! - Fixed and unlimited dimensions
45//! - Multi-dimensional arrays
46//! - Variable and global attributes
47//! - Coordinate variables
48//!
49//! ## NetCDF-4 (Pure Rust, always available)
50//!
51//! Real NetCDF-4 / HDF5 files are read and written via the Pure-Rust
52//! [`oxinetcdf`] backend. Additional data types over NetCDF-3:
53//! - `u8`, `u16`, `u32`, `u64` - Unsigned integers
54//! - `i64`, `u64` - 64-bit integers
55//! - `string` - Variable-length strings
56//!
57//! Additional features:
58//! - HDF5-based (DEFLATE) compression
59//! - Groups and coordinate variables
60//! - Multiple unlimited dimensions
61//!
62//! # Example - Reading NetCDF-3 File (Pure Rust)
63//!
64//! ```ignore
65//! use oxigeo_netcdf::NetCdfReader;
66//!
67//! // Open a NetCDF-3 file
68//! let reader = NetCdfReader::open("data.nc")?;
69//!
70//! // Get metadata
71//! println!("{}", reader.metadata().summary());
72//!
73//! // List dimensions
74//! for dim in reader.dimensions().iter() {
75//!     println!("Dimension: {} (size: {})", dim.name(), dim.len());
76//! }
77//!
78//! // List variables
79//! for var in reader.variables().iter() {
80//!     println!("Variable: {} (type: {})", var.name(), var.data_type().name());
81//! }
82//!
83//! // Read variable data
84//! let temperature = reader.read_f32("temperature")?;
85//! println!("Temperature data: {:?}", temperature);
86//! ```
87//!
88//! # Example - Writing NetCDF-3 File (Pure Rust)
89//!
90//! ```ignore
91//! use oxigeo_netcdf::{NetCdfWriter, NetCdfVersion};
92//! use oxigeo_netcdf::dimension::Dimension;
93//! use oxigeo_netcdf::variable::{Variable, DataType};
94//! use oxigeo_netcdf::attribute::{Attribute, AttributeValue};
95//!
96//! // Create a new NetCDF-3 file
97//! let mut writer = NetCdfWriter::create("output.nc", NetCdfVersion::Classic)?;
98//!
99//! // Add dimensions
100//! writer.add_dimension(Dimension::new_unlimited("time", 0)?)?;
101//! writer.add_dimension(Dimension::new("lat", 180)?)?;
102//! writer.add_dimension(Dimension::new("lon", 360)?)?;
103//!
104//! // Add coordinate variables
105//! writer.add_variable(Variable::new_coordinate("time", DataType::F64)?)?;
106//! writer.add_variable(Variable::new_coordinate("lat", DataType::F32)?)?;
107//! writer.add_variable(Variable::new_coordinate("lon", DataType::F32)?)?;
108//!
109//! // Add data variable
110//! let temp_var = Variable::new(
111//!     "temperature",
112//!     DataType::F32,
113//!     vec!["time".to_string(), "lat".to_string(), "lon".to_string()],
114//! )?;
115//! writer.add_variable(temp_var)?;
116//!
117//! // Add variable attributes
118//! writer.add_variable_attribute(
119//!     "temperature",
120//!     Attribute::new("units", AttributeValue::text("celsius"))?,
121//! )?;
122//! writer.add_variable_attribute(
123//!     "temperature",
124//!     Attribute::new("long_name", AttributeValue::text("Air Temperature"))?,
125//! )?;
126//!
127//! // Add global attributes
128//! writer.add_global_attribute(
129//!     Attribute::new("Conventions", AttributeValue::text("CF-1.8"))?,
130//! )?;
131//! writer.add_global_attribute(
132//!     Attribute::new("title", AttributeValue::text("Temperature Data"))?,
133//! )?;
134//!
135//! // End define mode
136//! writer.end_define_mode()?;
137//!
138//! // Write data
139//! let time_data = vec![0.0, 1.0, 2.0];
140//! writer.write_f64("time", &time_data)?;
141//!
142//! let lat_data: Vec<f32> = (0..180).map(|i| -90.0 + i as f32).collect();
143//! writer.write_f32("lat", &lat_data)?;
144//!
145//! let lon_data: Vec<f32> = (0..360).map(|i| -180.0 + i as f32).collect();
146//! writer.write_f32("lon", &lon_data)?;
147//!
148//! // Write temperature data
149//! let temp_data = vec![20.0f32; 3 * 180 * 360];
150//! writer.write_f32("temperature", &temp_data)?;
151//!
152//! // Close file
153//! writer.close()?;
154//! ```
155//!
156//! # CF Conventions Support
157//!
158//! The driver recognizes and parses CF (Climate and Forecast) conventions metadata:
159//!
160//! ```ignore
161//! use oxigeo_netcdf::NetCdfReader;
162//!
163//! let reader = NetCdfReader::open("cf_data.nc")?;
164//!
165//! if let Some(cf) = reader.cf_metadata() {
166//!     if cf.is_cf_compliant() {
167//!         println!("CF Conventions: {}", cf.conventions.as_deref().unwrap_or(""));
168//!         println!("Title: {}", cf.title.as_deref().unwrap_or(""));
169//!         println!("Institution: {}", cf.institution.as_deref().unwrap_or(""));
170//!     }
171//! }
172//! ```
173//!
174//! # Pure Rust Notes
175//!
176//! - NetCDF-4 reading/writing is Pure Rust via [`oxinetcdf`] atop `oxih5`
177//!   (DEFLATE compression through `oxiarc-deflate`); no C libraries are used.
178//! - The Pure-Rust NetCDF-4 writer supports data variables, dimensions, and
179//!   string attributes. Constructs it cannot yet represent (e.g. explicit
180//!   coordinate-variable values or numeric attributes) return a typed error
181//!   rather than producing an incomplete file.
182//! - NetCDF-3 classic support is optional (`netcdf3` feature) and allows only
183//!   one unlimited dimension per the classic model.
184//!
185//! # Performance Considerations
186//!
187//! - For large datasets, consider using chunked reading/writing
188//! - CF metadata parsing is done on-demand
189//!
190//! # References
191//!
192//! - [NetCDF User Guide](https://www.unidata.ucar.edu/software/netcdf/docs/)
193//! - [CF Conventions](http://cfconventions.org/)
194//! - [oxinetcdf crate](https://crates.io/crates/oxinetcdf)
195
196#![cfg_attr(not(feature = "std"), no_std)]
197#![warn(clippy::all)]
198// Pedantic disabled to reduce noise - default clippy::all is sufficient
199// #![warn(clippy::pedantic)]
200#![deny(clippy::unwrap_used)]
201#![allow(clippy::module_name_repetitions)]
202#![allow(clippy::similar_names)]
203// Allow unexpected cfg for optional netcdf4 feature
204#![allow(unexpected_cfgs)]
205// Allow unused imports during development
206#![allow(unused_imports)]
207// Allow missing docs during API development
208#![allow(missing_docs)]
209// Allow dead code for future netcdf3/netcdf4 integration
210#![allow(dead_code)]
211// Allow manual div_ceil for dimension calculations
212#![allow(clippy::manual_div_ceil)]
213// Allow expect() for internal netcdf state invariants
214#![allow(clippy::expect_used)]
215// Allow collapsible match for netcdf error handling
216#![allow(clippy::collapsible_match)]
217// Allow struct field pub visibility in internal modules
218#![allow(clippy::redundant_field_names)]
219
220#[cfg(feature = "std")]
221extern crate std;
222
223pub mod attribute;
224#[cfg(feature = "cf_conventions")]
225pub mod cf_conventions;
226pub mod dimension;
227pub mod error;
228pub mod metadata;
229#[cfg(feature = "netcdf3")]
230pub(crate) mod nc3_compat;
231/// A **dead, unused, hand-rolled** HDF5/NetCDF-4 parser/writer, kept for
232/// backward source compatibility only.
233///
234/// This module is a completely separate implementation from the crate's real
235/// NetCDF-4 backend ([`reader::NetCdfReader`] / [`writer::NetCdfWriter`],
236/// backed by the Pure-Rust [`oxinetcdf`] crate atop `oxih5`) — nothing in
237/// `reader`/`writer` calls into it. Its `Nc4Reader::open` unconditionally
238/// returns [`error::NetCdfError::NetCdf4NotAvailable`] (root-group object
239/// header parsing was never finished), so it can never successfully read a
240/// file. **Do not use `Nc4Reader`/`Nc4Writer` for real work** — use
241/// [`reader::NetCdfReader`] / [`writer::NetCdfWriter`] instead, which are
242/// real, tested, and exercised by this crate's own round-trip tests.
243///
244/// These types are intentionally **not** re-exported at the crate root
245/// (unlike `reader`/`writer`'s types) so that a normal `use oxigeo_netcdf::*`
246/// import surface can't accidentally reach for the non-functional
247/// `Nc4Reader`/`Nc4Writer` instead of the real backend. Reach them explicitly
248/// via `oxigeo_netcdf::netcdf4::{Nc4Reader, Nc4Writer, ...}` if you must.
249pub mod netcdf4;
250pub mod reader;
251pub mod variable;
252pub mod writer;
253
254// Re-export commonly used types.
255//
256// `netcdf4`'s types (`Nc4Reader`/`Nc4Writer`/...) are deliberately NOT
257// re-exported here — see the `netcdf4` module doc for why.
258pub use attribute::{Attribute, AttributeValue, Attributes};
259pub use dimension::{Dimension, DimensionSize, Dimensions};
260pub use error::{NetCdfError, Result};
261pub use metadata::{CfMetadata, NetCdfMetadata, NetCdfVersion};
262pub use reader::NetCdfReader;
263pub use variable::{DataType, Variable, Variables};
264pub use writer::NetCdfWriter;
265
266/// Crate version
267pub const VERSION: &str = env!("CARGO_PKG_VERSION");
268
269/// Crate name
270pub const NAME: &str = env!("CARGO_PKG_NAME");
271
272/// Pure Rust compliance status
273///
274/// Returns true if running in Pure Rust mode (no C dependencies).
275/// Returns false if netcdf4 feature is enabled (requires C libraries).
276#[must_use]
277pub const fn is_pure_rust() -> bool {
278    !cfg!(feature = "netcdf4")
279}
280
281/// Check if NetCDF-3 support is available.
282#[must_use]
283pub const fn has_netcdf3() -> bool {
284    cfg!(feature = "netcdf3")
285}
286
287/// Check if NetCDF-4 support is available.
288///
289/// Always `true`: NetCDF-4 (HDF5) reading/writing is provided by the Pure-Rust
290/// [`oxinetcdf`] backend and needs no feature flag.
291#[must_use]
292pub const fn has_netcdf4() -> bool {
293    true
294}
295
296/// Get supported format versions.
297///
298/// NetCDF-4 variants are always supported (Pure-Rust `oxinetcdf` backend);
299/// NetCDF-3 variants require the optional `netcdf3` feature.
300#[must_use]
301#[allow(unused_mut)]
302pub fn supported_versions() -> Vec<NetCdfVersion> {
303    // NetCDF-4 is always available via the Pure-Rust backend.
304    let mut versions = vec![NetCdfVersion::NetCdf4, NetCdfVersion::NetCdf4Classic];
305
306    #[cfg(feature = "netcdf3")]
307    {
308        versions.push(NetCdfVersion::Classic);
309        versions.push(NetCdfVersion::Offset64Bit);
310    }
311
312    versions
313}
314
315/// Get driver information.
316#[must_use]
317pub fn info() -> String {
318    let pure_rust = if is_pure_rust() {
319        "Pure Rust"
320    } else {
321        "C Bindings"
322    };
323
324    let versions: Vec<&str> = supported_versions()
325        .iter()
326        .map(|v| v.format_name())
327        .collect();
328
329    format!(
330        "{} {} - {} - Supports: {}",
331        NAME,
332        VERSION,
333        pure_rust,
334        versions.join(", ")
335    )
336}
337
338#[cfg(test)]
339mod tests {
340    use super::*;
341
342    #[test]
343    fn test_version() {
344        assert!(!VERSION.is_empty());
345        assert_eq!(NAME, "oxigeo-netcdf");
346    }
347
348    #[test]
349    fn test_pure_rust_status() {
350        #[cfg(feature = "netcdf4")]
351        assert!(!is_pure_rust());
352
353        #[cfg(not(feature = "netcdf4"))]
354        assert!(is_pure_rust());
355    }
356
357    #[test]
358    fn test_feature_detection() {
359        #[cfg(feature = "netcdf3")]
360        assert!(has_netcdf3());
361
362        #[cfg(feature = "netcdf4")]
363        assert!(has_netcdf4());
364    }
365
366    #[test]
367    fn test_supported_versions() {
368        let versions = supported_versions();
369
370        // NetCDF-4 is always available via the Pure-Rust oxinetcdf backend.
371        assert!(!versions.is_empty());
372        assert!(versions.contains(&NetCdfVersion::NetCdf4));
373
374        #[cfg(feature = "netcdf3")]
375        assert!(versions.contains(&NetCdfVersion::Classic));
376    }
377
378    #[test]
379    fn test_info() {
380        let info = info();
381        assert!(info.contains(NAME));
382        assert!(info.contains(VERSION));
383    }
384}