oxigeo_hdf5/lib.rs
1//! OxiGeo HDF5 Driver - Real Pure-Rust HDF5 (no libhdf5 FFI)
2//!
3//! This crate provides HDF5 file format support for OxiGeo, following the
4//! COOLJAPAN Pure Rust policy. Reading and writing are backed by the real
5//! Pure-Rust [`oxih5`](https://crates.io/crates/oxih5) crate, so the driver
6//! parses and produces genuine `.h5` files (including NetCDF-4, which is HDF5
7//! under the hood) — real superblocks, object headers, datatypes, dataspaces,
8//! attributes, and dataset values.
9//!
10//! # Pure Rust Policy Compliance
11//!
12//! `oxih5` is used with its default (Pure Rust, `oxiarc-deflate`) feature set —
13//! no C/C++/Fortran (`libhdf5`) dependency is pulled in.
14//!
15//! ## Reading (real HDF5 via oxih5)
16//!
17//! [`Hdf5Reader::open`] opens a genuine HDF5 file, walks its group/dataset tree,
18//! and exposes real attributes, real datatypes, real shapes, and real dataset
19//! values. When `oxih5` genuinely cannot decode a construct (e.g. a v2/v3
20//! superblock, or a datatype with no oxigeo representation) the reader fails
21//! loud or omits the object — it never fabricates zero-filled data.
22//!
23//! **Supported datatypes:** i8, u8, i16, u16, i32, u32, i64, u64, f32, f64,
24//! fixed- and variable-length strings, plus best-effort mapping of arrays,
25//! enums, compounds, references, and vlen types.
26//!
27//! ## Writing (real HDF5 via oxih5)
28//!
29//! [`Hdf5Writer`] accumulates groups, datasets, and attributes and, on
30//! [`Hdf5Writer::finalize`], emits a real HDF5 file through `oxih5`'s writer.
31//! Root-level chunked datasets (`DatasetProperties::with_chunks`) are written
32//! as real chunked (unlimited-first-dimension) HDF5 layouts. Constructs beyond
33//! `oxih5`'s writer surface (nested groups, sub-group attributes, chunked
34//! datasets inside sub-groups, **any** compression filter — `oxih5` has no
35//! compression support at all, non-string root attributes) return a typed
36//! error rather than silently degrading.
37//!
38//! ## Feature Flags
39//!
40//! - `std` (default): Standard library support
41//! - `pure_rust` (default): Pure Rust minimal HDF5 implementation
42//! - `hdf5_sys`: Full HDF5 support via C bindings (NOT Pure Rust)
43//! - `compression`: Compression support (GZIP in Pure Rust, all filters with hdf5_sys)
44//! - `async`: Async I/O support
45//!
46//! # HDF5 Format Overview
47//!
48//! HDF5 (Hierarchical Data Format version 5) is a file format designed for
49//! storing and organizing large amounts of data. It's widely used in scientific
50//! computing, particularly for:
51//!
52//! - Climate and weather data (NetCDF-4 is built on HDF5)
53//! - Satellite imagery (HDF-EOS)
54//! - Astronomy datasets
55//! - Medical imaging
56//! - Machine learning model storage
57//!
58//! ## Key Concepts
59//!
60//! - **File**: Container for all HDF5 data
61//! - **Group**: Directory-like container for organizing objects
62//! - **Dataset**: Multi-dimensional array of homogeneous data
63//! - **Attribute**: Small metadata attached to groups or datasets
64//! - **Datatype**: Description of data element type
65//! - **Dataspace**: Description of dataset dimensions
66//!
67//! # Example - Writing HDF5 File (Pure Rust)
68//!
69//! ```ignore
70//! use oxigeo_hdf5::{Hdf5Writer, Hdf5Version};
71//! use oxigeo_hdf5::datatype::Datatype;
72//! use oxigeo_hdf5::dataset::DatasetProperties;
73//! use oxigeo_hdf5::attribute::Attribute;
74//!
75//! // Create HDF5 file
76//! let mut writer = Hdf5Writer::create("output.h5", Hdf5Version::V10)?;
77//!
78//! // Create group
79//! writer.create_group("/measurements")?;
80//!
81//! // Add group attribute
82//! writer.add_group_attribute(
83//! "/measurements",
84//! Attribute::string("description", "Temperature measurements")
85//! )?;
86//!
87//! // Create dataset
88//! writer.create_dataset(
89//! "/measurements/temperature",
90//! Datatype::Float32,
91//! vec![100, 200], // 100x200 array
92//! DatasetProperties::new()
93//! )?;
94//!
95//! // Write data
96//! let data: Vec<f32> = vec![20.5; 20000]; // 100 * 200 elements
97//! writer.write_f32("/measurements/temperature", &data)?;
98//!
99//! // Add dataset attribute
100//! writer.add_dataset_attribute(
101//! "/measurements/temperature",
102//! Attribute::string("units", "celsius")
103//! )?;
104//!
105//! // Finalize file
106//! writer.finalize()?;
107//! # Ok::<(), oxigeo_hdf5::error::Hdf5Error>(())
108//! ```
109//!
110//! # Example - Reading HDF5 File (Pure Rust)
111//!
112//! ```ignore
113//! use oxigeo_hdf5::Hdf5Reader;
114//!
115//! // Open HDF5 file
116//! let mut reader = Hdf5Reader::open("output.h5")?;
117//!
118//! // Get root group
119//! let root = reader.root()?;
120//! println!("Root group: {}", root.name());
121//!
122//! // List groups
123//! for group_path in reader.list_groups() {
124//! println!("Group: {}", group_path);
125//! }
126//!
127//! // List datasets
128//! for dataset_path in reader.list_datasets() {
129//! let dataset = reader.dataset(dataset_path)?;
130//! println!("Dataset: {} (shape: {:?}, type: {})",
131//! dataset.name(),
132//! dataset.dims(),
133//! dataset.datatype()
134//! );
135//! }
136//!
137//! // Read dataset
138//! let temperature = reader.read_f32("/measurements/temperature")?;
139//! println!("Temperature data: {} elements", temperature.len());
140//! # Ok::<(), oxigeo_hdf5::error::Hdf5Error>(())
141//! ```
142//!
143//! # Example - Chunked Dataset (real HDF5 chunked layout, no compression)
144//!
145//! `oxih5`'s writer has no compression support at all, so requesting
146//! `with_gzip`/`with_compression` (anything but `CompressionFilter::None`)
147//! makes [`Hdf5Writer::finalize`] fail loud with
148//! `Hdf5Error::FeatureNotAvailable` rather than silently writing an
149//! uncompressed file. Chunking alone (`with_chunks`, no compression) is
150//! written as a real chunked HDF5 layout, but only as a single whole-array
151//! chunk — `chunk_dims` must equal the dataset's full `dims` (a smaller,
152//! partitioned chunk shape is rejected rather than silently dropping data
153//! outside the first chunk on read).
154//!
155//! ```ignore
156//! use oxigeo_hdf5::{Hdf5Writer, Hdf5Version};
157//! use oxigeo_hdf5::datatype::Datatype;
158//! use oxigeo_hdf5::dataset::DatasetProperties;
159//!
160//! let mut writer = Hdf5Writer::create("chunked.h5", Hdf5Version::V10)?;
161//!
162//! // Create a chunked (uncompressed) dataset — chunk_dims == dims.
163//! let properties = DatasetProperties::new()
164//! .with_chunks(vec![1000, 2000]);
165//!
166//! writer.create_dataset(
167//! "/data",
168//! Datatype::Float64,
169//! vec![1000, 2000],
170//! properties
171//! )?;
172//!
173//! // Write data
174//! let data: Vec<f64> = vec![0.0; 2_000_000];
175//! writer.write_f64("/data", &data)?;
176//!
177//! writer.finalize()?;
178//! # Ok::<(), oxigeo_hdf5::error::Hdf5Error>(())
179//! ```
180//!
181//! # Integration with OxiGeo
182//!
183//! This driver integrates with the OxiGeo core types and can be used to read
184//! and write geospatial data in HDF5 format, particularly for:
185//!
186//! - HDF-EOS (Earth Observing System) satellite data
187//! - NetCDF-4 files (which use HDF5 as backend)
188//! - Climate model outputs
189//! - Remote sensing imagery
190//!
191//! # References
192//!
193//! - [HDF5 Specification](https://portal.hdfgroup.org/display/HDF5/File+Format+Specification)
194//! - [HDF5 User Guide](https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guide)
195//! - [hdf5file](https://github.com/sile/hdf5file) - Pure Rust HDF5 implementation
196//! - [oxifive](https://github.com/dragly/oxifive) - Pure Rust HDF5 reader
197//! - [hdf5-rust](https://github.com/aldanor/hdf5-rust) - HDF5 C bindings for Rust
198//!
199//! # See Also
200//!
201//! - [`oxigeo-netcdf`](../oxigeo_netcdf/index.html) - NetCDF driver (NetCDF-4 uses HDF5)
202//! - [`oxigeo-geotiff`](../oxigeo_geotiff/index.html) - GeoTIFF driver
203//! - [`oxigeo-zarr`](../oxigeo_zarr/index.html) - Zarr driver (alternative to HDF5)
204
205#![warn(missing_docs)]
206#![deny(unsafe_code)]
207
208// Module declarations
209pub mod attribute;
210pub mod cache;
211pub mod chunking;
212mod convert;
213pub mod dataset;
214pub mod datatype;
215pub mod error;
216pub mod external;
217pub mod filters;
218pub mod group;
219mod object_header;
220pub mod reader;
221pub mod superblock_v2;
222pub mod swmr;
223pub mod vds;
224pub mod writer;
225
226// Re-exports
227pub use attribute::{Attribute, AttributeValue, Attributes};
228pub use cache::{
229 CacheConfig, CacheStatistics, CachedChunk, ChunkCache, EvictionPolicy, SharedChunkCache,
230};
231pub use chunking::{
232 AccessPattern, ChunkAllocStrategy, ChunkGrid, ChunkIndex, ChunkIndexStructure, ChunkMetadata,
233 calculate_optimal_chunk_size, recommend_chunk_size,
234};
235pub use dataset::{CompressionFilter, Dataset, DatasetProperties, LayoutType};
236pub use datatype::{
237 CompoundMember, Datatype, DatatypeClass, EnumMember, Hdf5ByteOrder, StringPadding,
238 TypeConverter,
239};
240pub use error::{Hdf5Error, Result};
241pub use external::{
242 ExternalDataset, ExternalFile, ExternalFileManager, ExternalLink, ExternalStorage,
243};
244pub use filters::{Filter, FilterId, FilterPipeline, parse_filter_pipeline_message};
245pub use group::{Group, ObjectRef, ObjectType, PathUtils};
246pub use reader::{Hdf5Reader, Hdf5ReaderBuilder, Superblock, SuperblockVersion};
247pub use swmr::{
248 FileLock, MetadataVersion, SwmrConfig, SwmrMode, SwmrReader, SwmrStatistics, SwmrWriter,
249};
250pub use vds::{
251 Hyperslab, SourceDataset, VdsBuilder, VdsMapping, VdsPattern, VirtualDataset,
252 create_vds_from_pattern,
253};
254pub use writer::{Hdf5Version, Hdf5Writer, Hdf5WriterBuilder};
255
256/// Library version
257pub const VERSION: &str = env!("CARGO_PKG_VERSION");
258
259/// Library name
260pub const NAME: &str = env!("CARGO_PKG_NAME");
261
262/// Get library information
263pub fn version_info() -> String {
264 format!("{} v{}", NAME, VERSION)
265}
266
267#[cfg(test)]
268mod tests {
269 use super::*;
270
271 #[test]
272 fn test_version_info() {
273 let info = version_info();
274 assert!(info.contains("oxigeo-hdf5"));
275 assert!(info.contains(VERSION));
276 }
277
278 #[test]
279 fn test_constants() {
280 assert_eq!(NAME, "oxigeo-hdf5");
281 assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
282 }
283}