@nirs4all/formats-wasm 0.2.12 → 0.2.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/THIRD_PARTY_NOTICES.md +49 -0
  2. package/nirs4all_formats_wasm_bg.wasm +0 -0
  3. package/package.json +4 -2
  4. package/reader-backports/hdf5-reader/Cargo.toml +119 -0
  5. package/reader-backports/hdf5-reader/LICENSE-APACHE +164 -0
  6. package/reader-backports/hdf5-reader/LICENSE-MIT +21 -0
  7. package/reader-backports/hdf5-reader/PROVENANCE.json +80 -0
  8. package/reader-backports/hdf5-reader/README.md +308 -0
  9. package/reader-backports/hdf5-reader/UPSTREAM-Cargo.toml +44 -0
  10. package/reader-backports/hdf5-reader/UPSTREAM-VCS.json +6 -0
  11. package/reader-backports/hdf5-reader/src/attribute_api.rs +847 -0
  12. package/reader-backports/hdf5-reader/src/btree_v1.rs +726 -0
  13. package/reader-backports/hdf5-reader/src/btree_v2.rs +2068 -0
  14. package/reader-backports/hdf5-reader/src/cache.rs +354 -0
  15. package/reader-backports/hdf5-reader/src/checksum.rs +56 -0
  16. package/reader-backports/hdf5-reader/src/chunk_index.rs +423 -0
  17. package/reader-backports/hdf5-reader/src/dataset.rs +4733 -0
  18. package/reader-backports/hdf5-reader/src/datatype_api.rs +497 -0
  19. package/reader-backports/hdf5-reader/src/error.rs +167 -0
  20. package/reader-backports/hdf5-reader/src/extensible_array.rs +1886 -0
  21. package/reader-backports/hdf5-reader/src/filters/deflate.rs +93 -0
  22. package/reader-backports/hdf5-reader/src/filters/fletcher32.rs +52 -0
  23. package/reader-backports/hdf5-reader/src/filters/lz4.rs +178 -0
  24. package/reader-backports/hdf5-reader/src/filters/mod.rs +326 -0
  25. package/reader-backports/hdf5-reader/src/filters/nbit.rs +586 -0
  26. package/reader-backports/hdf5-reader/src/filters/scaleoffset.rs +827 -0
  27. package/reader-backports/hdf5-reader/src/filters/shuffle.rs +99 -0
  28. package/reader-backports/hdf5-reader/src/fixed_array.rs +763 -0
  29. package/reader-backports/hdf5-reader/src/fractal_heap.rs +2029 -0
  30. package/reader-backports/hdf5-reader/src/global_heap.rs +284 -0
  31. package/reader-backports/hdf5-reader/src/group.rs +795 -0
  32. package/reader-backports/hdf5-reader/src/io.rs +413 -0
  33. package/reader-backports/hdf5-reader/src/lib.rs +916 -0
  34. package/reader-backports/hdf5-reader/src/local_heap.rs +261 -0
  35. package/reader-backports/hdf5-reader/src/messages/attribute.rs +304 -0
  36. package/reader-backports/hdf5-reader/src/messages/attribute_info.rs +96 -0
  37. package/reader-backports/hdf5-reader/src/messages/btree_k.rs +36 -0
  38. package/reader-backports/hdf5-reader/src/messages/continuation.rs +46 -0
  39. package/reader-backports/hdf5-reader/src/messages/dataspace.rs +259 -0
  40. package/reader-backports/hdf5-reader/src/messages/datatype.rs +938 -0
  41. package/reader-backports/hdf5-reader/src/messages/external_files.rs +50 -0
  42. package/reader-backports/hdf5-reader/src/messages/fill_value.rs +233 -0
  43. package/reader-backports/hdf5-reader/src/messages/filter_pipeline.rs +147 -0
  44. package/reader-backports/hdf5-reader/src/messages/group_info.rs +103 -0
  45. package/reader-backports/hdf5-reader/src/messages/layout.rs +476 -0
  46. package/reader-backports/hdf5-reader/src/messages/link.rs +170 -0
  47. package/reader-backports/hdf5-reader/src/messages/link_info.rs +127 -0
  48. package/reader-backports/hdf5-reader/src/messages/mod.rs +374 -0
  49. package/reader-backports/hdf5-reader/src/messages/modification_time.rs +83 -0
  50. package/reader-backports/hdf5-reader/src/messages/shared.rs +164 -0
  51. package/reader-backports/hdf5-reader/src/messages/shared_table.rs +67 -0
  52. package/reader-backports/hdf5-reader/src/messages/symbol_table_msg.rs +51 -0
  53. package/reader-backports/hdf5-reader/src/object_header.rs +1749 -0
  54. package/reader-backports/hdf5-reader/src/reference.rs +90 -0
  55. package/reader-backports/hdf5-reader/src/shared_message_table.rs +425 -0
  56. package/reader-backports/hdf5-reader/src/storage.rs +538 -0
  57. package/reader-backports/hdf5-reader/src/superblock.rs +285 -0
  58. package/reader-backports/hdf5-reader/src/symbol_table.rs +277 -0
  59. package/reader-backports/netcdf-reader/Cargo.toml +141 -0
  60. package/reader-backports/netcdf-reader/LICENSE-APACHE +164 -0
  61. package/reader-backports/netcdf-reader/LICENSE-MIT +21 -0
  62. package/reader-backports/netcdf-reader/PROVENANCE.json +55 -0
  63. package/reader-backports/netcdf-reader/README.md +308 -0
  64. package/reader-backports/netcdf-reader/UPSTREAM-Cargo.toml +48 -0
  65. package/reader-backports/netcdf-reader/UPSTREAM-VCS.json +6 -0
  66. package/reader-backports/netcdf-reader/src/cf/axes.rs +419 -0
  67. package/reader-backports/netcdf-reader/src/cf/bounds.rs +108 -0
  68. package/reader-backports/netcdf-reader/src/cf/crs.rs +269 -0
  69. package/reader-backports/netcdf-reader/src/cf/mod.rs +30 -0
  70. package/reader-backports/netcdf-reader/src/cf/time.rs +1122 -0
  71. package/reader-backports/netcdf-reader/src/classic/data.rs +1465 -0
  72. package/reader-backports/netcdf-reader/src/classic/header.rs +1097 -0
  73. package/reader-backports/netcdf-reader/src/classic/mod.rs +240 -0
  74. package/reader-backports/netcdf-reader/src/classic/storage.rs +211 -0
  75. package/reader-backports/netcdf-reader/src/classic/types.rs +93 -0
  76. package/reader-backports/netcdf-reader/src/classic/variable.rs +1162 -0
  77. package/reader-backports/netcdf-reader/src/error.rs +59 -0
  78. package/reader-backports/netcdf-reader/src/lib.rs +1531 -0
  79. package/reader-backports/netcdf-reader/src/masked.rs +173 -0
  80. package/reader-backports/netcdf-reader/src/nc4/attributes.rs +203 -0
  81. package/reader-backports/netcdf-reader/src/nc4/dimensions.rs +139 -0
  82. package/reader-backports/netcdf-reader/src/nc4/groups.rs +308 -0
  83. package/reader-backports/netcdf-reader/src/nc4/mod.rs +572 -0
  84. package/reader-backports/netcdf-reader/src/nc4/types.rs +309 -0
  85. package/reader-backports/netcdf-reader/src/nc4/variables.rs +420 -0
  86. package/reader-backports/netcdf-reader/src/types.rs +18 -0
  87. package/reader-backports/netcdf-reader/src/unpack.rs +113 -0
  88. package/reader-backports/netcdf-reader/src/user_defined.rs +569 -0
@@ -0,0 +1,572 @@
1
+ //! NetCDF-4 (HDF5-backed) format support.
2
+ //!
3
+ //! This module maps the HDF5 data model to the NetCDF data model:
4
+ //! - HDF5 groups become NetCDF groups
5
+ //! - HDF5 datasets become NetCDF variables
6
+ //! - HDF5 attributes become NetCDF attributes
7
+ //! - Dimensions are reconstructed from `DIMENSION_LIST` and `_Netcdf4Dimid` attributes
8
+ //!
9
+ //! Requires the `netcdf4` feature (enabled by default).
10
+
11
+ pub mod attributes;
12
+ pub mod dimensions;
13
+ pub mod groups;
14
+ pub mod types;
15
+ pub mod variables;
16
+
17
+ use std::path::Path;
18
+ use std::sync::OnceLock;
19
+
20
+ use hdf5_reader::datatype_api::H5Type;
21
+ use hdf5_reader::storage::DynStorage;
22
+ use hdf5_reader::Hdf5File;
23
+ use ndarray::ArrayD;
24
+ #[cfg(feature = "rayon")]
25
+ use rayon::ThreadPool;
26
+
27
+ use crate::error::{Error, Result};
28
+ use crate::types::{checked_shape_elements, checked_usize_from_u64, NcGroup, NcType};
29
+
30
+ /// Dispatch on `NcType` to read data and promote to `f64`.
31
+ ///
32
+ /// `$dtype` must be an expression of type `&NcType`.
33
+ /// `$read_expr` is a macro-like callback: for each numeric type `$T`,
34
+ /// the macro evaluates `$read_expr` with `$T` substituted in.
35
+ ///
36
+ /// Usage:
37
+ /// ```ignore
38
+ /// dispatch_read_as_f64!(&var.dtype, |$T| dataset.read_array::<$T>())
39
+ /// ```
40
+ macro_rules! dispatch_read_as_f64 {
41
+ ($dtype:expr, |$T:ident| $read_expr:expr) => {{
42
+ use crate::types::NcType;
43
+ match $dtype {
44
+ NcType::Byte => {
45
+ type $T = i8;
46
+ let arr = $read_expr?;
47
+ Ok(arr.mapv(|v| v as f64))
48
+ }
49
+ NcType::Short => {
50
+ type $T = i16;
51
+ let arr = $read_expr?;
52
+ Ok(arr.mapv(|v| v as f64))
53
+ }
54
+ NcType::Int => {
55
+ type $T = i32;
56
+ let arr = $read_expr?;
57
+ Ok(arr.mapv(|v| v as f64))
58
+ }
59
+ NcType::Float => {
60
+ type $T = f32;
61
+ let arr = $read_expr?;
62
+ Ok(arr.mapv(|v| v as f64))
63
+ }
64
+ NcType::Double => {
65
+ type $T = f64;
66
+ Ok($read_expr?)
67
+ }
68
+ NcType::UByte => {
69
+ type $T = u8;
70
+ let arr = $read_expr?;
71
+ Ok(arr.mapv(|v| v as f64))
72
+ }
73
+ NcType::UShort => {
74
+ type $T = u16;
75
+ let arr = $read_expr?;
76
+ Ok(arr.mapv(|v| v as f64))
77
+ }
78
+ NcType::UInt => {
79
+ type $T = u32;
80
+ let arr = $read_expr?;
81
+ Ok(arr.mapv(|v| v as f64))
82
+ }
83
+ NcType::Int64 => {
84
+ type $T = i64;
85
+ let arr = $read_expr?;
86
+ Ok(arr.mapv(|v| v as f64))
87
+ }
88
+ NcType::UInt64 => {
89
+ type $T = u64;
90
+ let arr = $read_expr?;
91
+ Ok(arr.mapv(|v| v as f64))
92
+ }
93
+ NcType::Char => Err(Error::TypeMismatch {
94
+ expected: "numeric type".to_string(),
95
+ actual: "Char".to_string(),
96
+ }),
97
+ NcType::String => Err(Error::TypeMismatch {
98
+ expected: "numeric type".to_string(),
99
+ actual: "String".to_string(),
100
+ }),
101
+ other => Err(Error::TypeMismatch {
102
+ expected: "numeric type".to_string(),
103
+ actual: format!("{:?}", other),
104
+ }),
105
+ }
106
+ }};
107
+ }
108
+
109
+ /// True when an HDF5 file carries none of NetCDF-4's markers: no `_NCProperties` root
110
+ /// attribute and no dimension-scale dataset in the root group.
111
+ fn is_plain_hdf5(hdf5: &Hdf5File) -> bool {
112
+ let Ok(root) = hdf5.root_group() else {
113
+ return false;
114
+ };
115
+ if root.attribute("_NCProperties").is_ok() {
116
+ return false;
117
+ }
118
+ let Ok(datasets) = root.datasets() else {
119
+ return false;
120
+ };
121
+ !datasets.iter().any(|ds| {
122
+ ds.attribute("CLASS")
123
+ .ok()
124
+ .and_then(|a| a.read_string().ok())
125
+ .is_some_and(|c| c == "DIMENSION_SCALE")
126
+ })
127
+ }
128
+
129
+ /// An opened NetCDF-4 file (backed by HDF5).
130
+ pub struct Nc4File {
131
+ hdf5: Hdf5File,
132
+ metadata_mode: crate::NcMetadataMode,
133
+ root_metadata: OnceLock<NcGroup>,
134
+ metadata_tree: OnceLock<NcGroup>,
135
+ }
136
+
137
+ impl Nc4File {
138
+ pub(crate) fn from_hdf5(hdf5: Hdf5File, metadata_mode: crate::NcMetadataMode) -> Result<Self> {
139
+ // A plain HDF5 file (not written through NetCDF-4) has no `_NCProperties` attribute and
140
+ // no dimension scales. netCDF-C reads such files with phony dimensions; strict NetCDF-4
141
+ // validation would reject every dataset for lacking `DIMENSION_LIST`, so they are read
142
+ // in lossy mode (dimensions named by size). NetCDF-4 files keep the requested mode.
143
+ let metadata_mode =
144
+ if metadata_mode == crate::NcMetadataMode::Strict && is_plain_hdf5(&hdf5) {
145
+ crate::NcMetadataMode::Lossy
146
+ } else {
147
+ metadata_mode
148
+ };
149
+ Ok(Nc4File {
150
+ hdf5,
151
+ metadata_mode,
152
+ root_metadata: OnceLock::new(),
153
+ metadata_tree: OnceLock::new(),
154
+ })
155
+ }
156
+
157
+ /// Open a NetCDF-4 file from disk.
158
+ pub fn open(path: &Path) -> Result<Self> {
159
+ Self::open_with_options(path, crate::NcOpenOptions::default())
160
+ }
161
+
162
+ /// Open a NetCDF-4 file from disk with custom options.
163
+ pub fn open_with_options(path: &Path, options: crate::NcOpenOptions) -> Result<Self> {
164
+ let metadata_mode = options.metadata_mode;
165
+ let hdf5 = Hdf5File::open_with_options(
166
+ path,
167
+ hdf5_reader::OpenOptions {
168
+ chunk_cache_bytes: options.chunk_cache_bytes,
169
+ chunk_cache_slots: options.chunk_cache_slots,
170
+ filter_registry: options.filter_registry,
171
+ external_file_resolver: options.external_file_resolver,
172
+ external_link_resolver: options.external_link_resolver,
173
+ },
174
+ )?;
175
+ Nc4File::from_hdf5(hdf5, metadata_mode)
176
+ }
177
+
178
+ /// Open a NetCDF-4 file from in-memory bytes.
179
+ pub fn from_bytes(data: &[u8]) -> Result<Self> {
180
+ Self::from_bytes_with_options(data, crate::NcOpenOptions::default())
181
+ }
182
+
183
+ /// Open a NetCDF-4 file from in-memory bytes with custom options.
184
+ pub fn from_bytes_with_options(data: &[u8], options: crate::NcOpenOptions) -> Result<Self> {
185
+ let metadata_mode = options.metadata_mode;
186
+ let hdf5 = Hdf5File::from_bytes_with_options(
187
+ data,
188
+ hdf5_reader::OpenOptions {
189
+ chunk_cache_bytes: options.chunk_cache_bytes,
190
+ chunk_cache_slots: options.chunk_cache_slots,
191
+ filter_registry: options.filter_registry,
192
+ external_file_resolver: options.external_file_resolver,
193
+ external_link_resolver: options.external_link_resolver,
194
+ },
195
+ )?;
196
+ Nc4File::from_hdf5(hdf5, metadata_mode)
197
+ }
198
+
199
+ /// Open a NetCDF-4 file from a custom random-access storage backend.
200
+ pub fn from_storage(storage: DynStorage) -> Result<Self> {
201
+ Self::from_storage_with_options(storage, crate::NcOpenOptions::default())
202
+ }
203
+
204
+ /// Open a NetCDF-4 file from a custom random-access storage backend with custom options.
205
+ pub fn from_storage_with_options(
206
+ storage: DynStorage,
207
+ options: crate::NcOpenOptions,
208
+ ) -> Result<Self> {
209
+ let metadata_mode = options.metadata_mode;
210
+ let hdf5 = Hdf5File::from_storage_with_options(
211
+ storage,
212
+ hdf5_reader::OpenOptions {
213
+ chunk_cache_bytes: options.chunk_cache_bytes,
214
+ chunk_cache_slots: options.chunk_cache_slots,
215
+ filter_registry: options.filter_registry,
216
+ external_file_resolver: options.external_file_resolver,
217
+ external_link_resolver: options.external_link_resolver,
218
+ },
219
+ )?;
220
+ Nc4File::from_hdf5(hdf5, metadata_mode)
221
+ }
222
+
223
+ /// The root group.
224
+ pub fn root_group(&self) -> Result<&NcGroup> {
225
+ if let Some(group) = self.metadata_tree.get() {
226
+ return Ok(group);
227
+ }
228
+ let metadata_tree = groups::build_root_group(&self.hdf5, self.metadata_mode)?;
229
+ let _ = self.metadata_tree.set(metadata_tree);
230
+ Ok(self
231
+ .metadata_tree
232
+ .get()
233
+ .expect("metadata tree must be initialized after successful build"))
234
+ }
235
+
236
+ /// Check if this file uses the classic data model (`_nc3_strict`).
237
+ ///
238
+ /// This checks the raw HDF5 root group attributes (before the internal
239
+ /// attribute filter removes `_nc3_strict`).
240
+ pub fn is_classic_model(&self) -> bool {
241
+ self.hdf5
242
+ .root_group()
243
+ .ok()
244
+ .and_then(|g| g.attribute("_nc3_strict").ok())
245
+ .is_some()
246
+ }
247
+
248
+ pub fn dimensions(&self) -> Result<&[crate::types::NcDimension]> {
249
+ Ok(&self.root_metadata()?.dimensions)
250
+ }
251
+
252
+ pub fn variables(&self) -> Result<&[crate::types::NcVariable]> {
253
+ Ok(&self.root_metadata()?.variables)
254
+ }
255
+
256
+ pub fn global_attributes(&self) -> Result<&[crate::types::NcAttribute]> {
257
+ Ok(&self.root_metadata()?.attributes)
258
+ }
259
+
260
+ pub fn group(&self, path: &str) -> Result<&NcGroup> {
261
+ let normalized = normalize_group_path(path)?;
262
+ let root = self.root_group()?;
263
+ if normalized.is_empty() {
264
+ return Ok(root);
265
+ }
266
+ root.group(normalized)
267
+ .ok_or_else(|| Error::GroupNotFound(path.to_string()))
268
+ }
269
+
270
+ pub fn variable(&self, path: &str) -> Result<&crate::types::NcVariable> {
271
+ self.root_group()?
272
+ .variable(path)
273
+ .ok_or_else(|| Error::VariableNotFound(path.to_string()))
274
+ }
275
+
276
+ pub fn dimension(&self, path: &str) -> Result<&crate::types::NcDimension> {
277
+ self.root_group()?
278
+ .dimension(path)
279
+ .ok_or_else(|| Error::DimensionNotFound(path.to_string()))
280
+ }
281
+
282
+ pub fn global_attribute(&self, path: &str) -> Result<&crate::types::NcAttribute> {
283
+ self.root_group()?
284
+ .attribute(path)
285
+ .ok_or_else(|| Error::AttributeNotFound(path.to_string()))
286
+ }
287
+
288
+ /// Read a variable's data as a typed array.
289
+ ///
290
+ /// Looks up the variable by path relative to the root group, then opens the
291
+ /// matching HDF5 dataset and reads the data.
292
+ pub fn read_variable<T: H5Type>(&self, path: &str) -> Result<ArrayD<T>> {
293
+ let normalized = normalize_dataset_path(path)?;
294
+ let dataset = self.hdf5.dataset(normalized)?;
295
+ Ok(dataset.read_array::<T>()?)
296
+ }
297
+
298
+ /// Read a variable into a caller-provided typed buffer.
299
+ pub fn read_variable_into<T: H5Type>(&self, path: &str, dst: &mut [T]) -> Result<()> {
300
+ let normalized = normalize_dataset_path(path)?;
301
+ let dataset = self.hdf5.dataset(normalized)?;
302
+ Ok(dataset.read_into::<T>(dst)?)
303
+ }
304
+
305
+ /// Read a variable as logical raw bytes in HDF5 datatype byte order.
306
+ pub fn read_variable_raw_bytes(&self, path: &str) -> Result<Vec<u8>> {
307
+ let normalized = normalize_dataset_path(path)?;
308
+ let dataset = self.hdf5.dataset(normalized)?;
309
+ Ok(dataset.read_raw_bytes()?)
310
+ }
311
+
312
+ /// Read logical raw bytes into a caller-provided buffer.
313
+ pub fn read_variable_raw_bytes_into(&self, path: &str, dst: &mut [u8]) -> Result<()> {
314
+ let normalized = normalize_dataset_path(path)?;
315
+ let dataset = self.hdf5.dataset(normalized)?;
316
+ Ok(dataset.read_raw_bytes_into(dst)?)
317
+ }
318
+
319
+ /// Read a variable as logical raw bytes with numeric fields in native endian.
320
+ pub fn read_variable_native_bytes(&self, path: &str) -> Result<Vec<u8>> {
321
+ let normalized = normalize_dataset_path(path)?;
322
+ let dataset = self.hdf5.dataset(normalized)?;
323
+ Ok(dataset.read_native_bytes()?)
324
+ }
325
+
326
+ /// Read native-endian logical raw bytes into a caller-provided buffer.
327
+ pub fn read_variable_native_bytes_into(&self, path: &str, dst: &mut [u8]) -> Result<()> {
328
+ let normalized = normalize_dataset_path(path)?;
329
+ let dataset = self.hdf5.dataset(normalized)?;
330
+ Ok(dataset.read_native_bytes_into(dst)?)
331
+ }
332
+
333
+ /// Iterate decoded HDF5 chunks for a chunked variable.
334
+ pub fn iter_variable_chunks(&self, path: &str) -> Result<hdf5_reader::DatasetChunkIterator> {
335
+ let normalized = normalize_dataset_path(path)?;
336
+ let dataset = self.hdf5.dataset(normalized)?;
337
+ Ok(dataset.iter_chunks()?)
338
+ }
339
+
340
+ /// Return current chunk-cache statistics.
341
+ pub fn chunk_cache_stats(&self) -> hdf5_reader::ChunkCacheStats {
342
+ self.hdf5.chunk_cache_stats()
343
+ }
344
+
345
+ /// Read a string variable as a single string.
346
+ pub fn read_variable_as_string(&self, path: &str) -> Result<String> {
347
+ let mut strings = self.read_variable_as_strings(path)?;
348
+ match strings.len() {
349
+ 1 => Ok(strings.swap_remove(0)),
350
+ 0 => Err(Error::InvalidData(format!(
351
+ "variable '{}' contains no string elements",
352
+ path
353
+ ))),
354
+ count => Err(Error::InvalidData(format!(
355
+ "variable '{}' contains {count} string elements; use read_variable_as_strings()",
356
+ path
357
+ ))),
358
+ }
359
+ }
360
+
361
+ /// Read a string variable as a flat vector of strings.
362
+ pub fn read_variable_as_strings(&self, path: &str) -> Result<Vec<String>> {
363
+ let normalized = normalize_dataset_path(path)?;
364
+ let dataset = self.hdf5.dataset(normalized)?;
365
+ let dtype = dataset_nc_type(&dataset)?;
366
+ match dtype {
367
+ NcType::String => Ok(dataset.read_strings()?),
368
+ NcType::Char => {
369
+ let variable = self.variable(path)?;
370
+ let raw = dataset.read_raw_bytes()?;
371
+ decode_char_variable_strings(variable, &raw)
372
+ }
373
+ _ => Err(Error::TypeMismatch {
374
+ expected: "String or Char".to_string(),
375
+ actual: format!("{dtype:?}"),
376
+ }),
377
+ }
378
+ }
379
+
380
+ /// Read a variable containing NetCDF-4 user-defined values.
381
+ pub fn read_variable_user_defined(
382
+ &self,
383
+ path: &str,
384
+ ) -> Result<ArrayD<crate::user_defined::NcValue>> {
385
+ let normalized = normalize_dataset_path(path)?;
386
+ let dataset = self.hdf5.dataset(normalized)?;
387
+ crate::user_defined::read_dataset_values(&dataset)
388
+ }
389
+
390
+ /// Read a NetCDF-4 user-defined variable through a custom decoder.
391
+ pub fn read_variable_user_defined_with<T, F>(&self, path: &str, decoder: F) -> Result<ArrayD<T>>
392
+ where
393
+ F: FnMut(crate::user_defined::NcValueView<'_>) -> Result<T>,
394
+ {
395
+ let normalized = normalize_dataset_path(path)?;
396
+ let dataset = self.hdf5.dataset(normalized)?;
397
+ crate::user_defined::read_dataset_with_decoder(&dataset, decoder)
398
+ }
399
+
400
+ #[cfg(feature = "rayon")]
401
+ pub fn read_variable_parallel<T: H5Type>(&self, path: &str) -> Result<ArrayD<T>> {
402
+ let normalized = normalize_dataset_path(path)?;
403
+ let dataset = self.hdf5.dataset(normalized)?;
404
+ Ok(dataset.read_array_parallel::<T>()?)
405
+ }
406
+
407
+ #[cfg(feature = "rayon")]
408
+ pub fn read_variable_in_pool<T: H5Type>(
409
+ &self,
410
+ path: &str,
411
+ pool: &ThreadPool,
412
+ ) -> Result<ArrayD<T>> {
413
+ let normalized = normalize_dataset_path(path)?;
414
+ let dataset = self.hdf5.dataset(normalized)?;
415
+ Ok(dataset.read_array_in_pool::<T>(pool)?)
416
+ }
417
+ }
418
+
419
+ fn decode_char_variable_strings(
420
+ variable: &crate::types::NcVariable,
421
+ bytes: &[u8],
422
+ ) -> Result<Vec<String>> {
423
+ let shape = variable.shape();
424
+ if shape.len() <= 1 {
425
+ return Ok(vec![decode_char_string(bytes)]);
426
+ }
427
+
428
+ let string_len = checked_usize_from_u64(
429
+ *shape
430
+ .last()
431
+ .ok_or_else(|| Error::InvalidData("char variable missing string axis".into()))?,
432
+ "char string length",
433
+ )?;
434
+ let string_count_u64 = checked_shape_elements(&shape[..shape.len() - 1], "char string count")?;
435
+ let string_count = checked_usize_from_u64(string_count_u64, "char string count")?;
436
+ let expected_bytes = string_count.checked_mul(string_len).ok_or_else(|| {
437
+ Error::InvalidData("char string byte count exceeds platform usize".to_string())
438
+ })?;
439
+
440
+ if bytes.len() < expected_bytes {
441
+ return Err(Error::InvalidData(format!(
442
+ "char variable '{}' data too short: need {} bytes, have {}",
443
+ variable.name,
444
+ expected_bytes,
445
+ bytes.len()
446
+ )));
447
+ }
448
+
449
+ if string_len == 0 {
450
+ return Ok(vec![String::new(); string_count]);
451
+ }
452
+
453
+ Ok(bytes[..expected_bytes]
454
+ .chunks_exact(string_len)
455
+ .map(decode_char_string)
456
+ .collect())
457
+ }
458
+
459
+ fn decode_char_string(bytes: &[u8]) -> String {
460
+ String::from_utf8_lossy(bytes)
461
+ .trim_end_matches('\0')
462
+ .to_string()
463
+ }
464
+
465
+ impl Nc4File {
466
+ fn root_metadata(&self) -> Result<&NcGroup> {
467
+ if let Some(group) = self.root_metadata.get() {
468
+ return Ok(group);
469
+ }
470
+ let root_metadata = groups::build_root_group_metadata(&self.hdf5, self.metadata_mode)?;
471
+ let _ = self.root_metadata.set(root_metadata);
472
+ Ok(self
473
+ .root_metadata
474
+ .get()
475
+ .expect("root metadata must be initialized after successful build"))
476
+ }
477
+ }
478
+
479
+ impl Nc4File {
480
+ /// Read a variable with automatic type promotion to f64.
481
+ ///
482
+ /// Reads in the native HDF5 type and promotes to f64 via `mapv`.
483
+ pub fn read_variable_as_f64(&self, path: &str) -> Result<ArrayD<f64>> {
484
+ let normalized = normalize_dataset_path(path)?;
485
+ let dataset = self.hdf5.dataset(normalized)?;
486
+ let dtype = dataset_nc_type(&dataset)?;
487
+ dispatch_read_as_f64!(&dtype, |T| dataset.read_array::<T>())
488
+ }
489
+
490
+ /// Read a slice of a variable with automatic type promotion to f64.
491
+ pub fn read_variable_slice_as_f64(
492
+ &self,
493
+ path: &str,
494
+ selection: &crate::types::NcSliceInfo,
495
+ ) -> Result<ArrayD<f64>> {
496
+ let normalized = normalize_dataset_path(path)?;
497
+ let dataset = self.hdf5.dataset(normalized)?;
498
+ let hdf5_sel = to_hdf5_slice_info(selection);
499
+ let dtype = dataset_nc_type(&dataset)?;
500
+ dispatch_read_as_f64!(&dtype, |T| dataset.read_slice::<T>(&hdf5_sel))
501
+ }
502
+
503
+ /// Read a typed slice of a variable (NC4 delegation).
504
+ pub fn read_variable_slice<T: H5Type>(
505
+ &self,
506
+ path: &str,
507
+ selection: &crate::types::NcSliceInfo,
508
+ ) -> Result<ArrayD<T>> {
509
+ let normalized = normalize_dataset_path(path)?;
510
+ let dataset = self.hdf5.dataset(normalized)?;
511
+ let hdf5_sel = to_hdf5_slice_info(selection);
512
+ Ok(dataset.read_slice::<T>(&hdf5_sel)?)
513
+ }
514
+
515
+ /// Read a typed slice of a variable using chunk-level parallelism.
516
+ ///
517
+ /// Chunked datasets decompress overlapping chunks in parallel via Rayon.
518
+ /// Non-chunked layouts fall back to `read_variable_slice`.
519
+ #[cfg(feature = "rayon")]
520
+ pub fn read_variable_slice_parallel<T: H5Type>(
521
+ &self,
522
+ path: &str,
523
+ selection: &crate::types::NcSliceInfo,
524
+ ) -> Result<ArrayD<T>> {
525
+ let normalized = normalize_dataset_path(path)?;
526
+ let dataset = self.hdf5.dataset(normalized)?;
527
+ let hdf5_sel = to_hdf5_slice_info(selection);
528
+ Ok(dataset.read_slice_parallel::<T>(&hdf5_sel)?)
529
+ }
530
+ }
531
+
532
+ fn to_hdf5_slice_info(selection: &crate::types::NcSliceInfo) -> hdf5_reader::SliceInfo {
533
+ hdf5_reader::SliceInfo {
534
+ selections: selection
535
+ .selections
536
+ .iter()
537
+ .map(|s| match s {
538
+ crate::types::NcSliceInfoElem::Index(idx) => {
539
+ hdf5_reader::SliceInfoElem::Index(*idx)
540
+ }
541
+ crate::types::NcSliceInfoElem::Slice { start, end, step } => {
542
+ hdf5_reader::SliceInfoElem::Slice {
543
+ start: *start,
544
+ end: *end,
545
+ step: *step,
546
+ }
547
+ }
548
+ })
549
+ .collect(),
550
+ }
551
+ }
552
+
553
+ fn normalize_dataset_path(path: &str) -> Result<&str> {
554
+ let trimmed = path.trim_matches('/');
555
+ if trimmed.is_empty() {
556
+ return Err(Error::VariableNotFound(path.to_string()));
557
+ }
558
+ Ok(trimmed)
559
+ }
560
+
561
+ fn normalize_group_path(path: &str) -> Result<&str> {
562
+ Ok(path.trim_matches('/'))
563
+ }
564
+
565
+ fn dataset_nc_type(dataset: &hdf5_reader::Dataset) -> Result<NcType> {
566
+ self::types::hdf5_to_nc_type(dataset.dtype()).map_err(|err| {
567
+ Error::InvalidData(format!(
568
+ "dataset '{}' cannot be mapped to a NetCDF-4 type: {err}",
569
+ dataset.name()
570
+ ))
571
+ })
572
+ }