nexrad_data/lib.rs
1//! Data access for NEXRAD weather radar files.
2//!
3//! This crate provides tools for working with NEXRAD Archive II volume files and
4//! accessing data from cloud providers like AWS.
5//!
6//! # Overview
7//!
8//! - [`volume`] - Parse and decode local Archive II volume files
9//! - `aws` - Download data from AWS (archive and real-time, requires `aws` feature)
10//!
11//! # Working with Local Files
12//!
13//! ```ignore
14//! use nexrad_data::volume::File;
15//!
16//! let data = std::fs::read("KTLX20130520_201643_V06.ar2v")?;
17//! let volume = File::new(data);
18//!
19//! // Access the volume header
20//! if let Some(header) = volume.header() {
21//! println!("Volume date: {:?}", header.date());
22//! }
23//!
24//! // Process LDM records
25//! for record in volume.records()? {
26//! let decompressed = record.decompress()?;
27//! let messages = decompressed.messages()?;
28//! // Process radar messages...
29//! }
30//! ```
31//!
32//! # Downloading from AWS
33//!
34//! The `aws` feature (enabled by default) provides access to NOAA's NEXRAD data on AWS:
35//!
36//! - **Archive data**: Historical volumes from the NEXRAD Level II archive
37//! - **Real-time data**: Live radar data with minimal latency
38//!
39//! ```ignore
40//! use nexrad_data::aws::archive;
41//! use chrono::NaiveDate;
42//!
43//! // List available files for a date and site
44//! let date = NaiveDate::from_ymd_opt(2023, 5, 20).unwrap();
45//! let files = archive::list_files("KTLX", date).await?;
46//!
47//! // Download a specific file
48//! let data = archive::download_file(&files[0]).await?;
49//! ```
50//!
51//! # Features
52//!
53//! - `aws` - Enable AWS S3 data access (requires async runtime)
54//! - `nexrad-model` - Enable conversion to high-level `Scan` model
55//!
56//! # Crate Boundaries
57//!
58//! This crate provides **data access and I/O operations** with the following
59//! responsibilities and constraints:
60//!
61//! ## Responsibilities
62//!
63//! - ✓ Read and parse Archive II volume files
64//! - ✓ Handle file I/O operations
65//! - ✓ Decompress bzip2-compressed LDM records
66//! - ✓ AWS S3 integration for archive and real-time data (when `aws` feature enabled)
67//! - ✓ Use `nexrad-decode` for message parsing
68//! - ✓ Use `nexrad-model` for high-level type conversion (when feature enabled)
69//! - ✓ Orchestrate the data pipeline from raw bytes to structured models
70//!
71//! ## Constraints
72//!
73//! - ✗ **No rendering or visualization**
74//! - ✗ **No CLI or user interaction**
75//!
76//! This crate serves as the **I/O boundary layer** for the NEXRAD library suite. It
77//! handles all file and network operations, decompression, and coordinates between
78//! the low-level binary parsing (`nexrad-decode`) and high-level data models
79//! (`nexrad-model`).
80
81#![forbid(unsafe_code)]
82#![deny(clippy::unwrap_used)]
83#![deny(clippy::expect_used)]
84#![warn(clippy::correctness)]
85#![deny(missing_docs)]
86
87#[cfg(feature = "aws")]
88/// AWS S3 integration for downloading NEXRAD data from the cloud.
89pub mod aws;
90
91/// Local Archive II volume file handling.
92pub mod volume;
93
94/// Result and error types for data operations.
95pub mod result;