htg/lib.rs
1//! # HTG - SRTM Elevation Library
2//!
3//! High-performance, memory-efficient library for querying elevation data from
4//! SRTM (Shuttle Radar Topography Mission) `.hgt` files.
5//!
6//! ## Features
7//!
8//! - **Fast**: Memory-mapped I/O for instant data access
9//! - **Memory Efficient**: LRU cache limits memory usage
10//! - **Automatic Detection**: Determines tile resolution (SRTM1/SRTM3) from file size
11//! - **Offline**: Works with local `.hgt` files, no internet required
12//! - **Auto-Download** (optional): Download missing tiles automatically
13//!
14//! ## Quick Start
15//!
16//! The easiest way to use htg is through [`SrtmService`], which handles tile
17//! loading and caching automatically:
18//!
19//! ```ignore
20//! use htg::SrtmService;
21//!
22//! // Create service with up to 100 cached tiles
23//! let service = SrtmService::new("/path/to/hgt/files", 100);
24//!
25//! // Query elevation - tile loading is automatic
26//! let elevation = service.get_elevation(35.6762, 139.6503)?; // Tokyo
27//! println!("Elevation: {}m", elevation);
28//!
29//! // Check cache performance
30//! let stats = service.cache_stats();
31//! println!("Cache hit rate: {:.1}%", stats.hit_rate() * 100.0);
32//! ```
33//!
34//! ## Auto-Download Feature
35//!
36//! Enable the `download` feature to automatically download missing tiles:
37//!
38//! ```toml
39//! [dependencies]
40//! htg = { version = "0.1", features = ["download"] }
41//! ```
42//!
43//! ```ignore
44//! use htg::{SrtmServiceBuilder, download::DownloadConfig};
45//!
46//! let service = SrtmServiceBuilder::new("/data/srtm")
47//! .cache_size(100)
48//! .auto_download(DownloadConfig::with_url_template(
49//! "https://example.com/srtm/{filename}.hgt.gz", // compression auto-detected
50//! ))
51//! .build()?;
52//!
53//! // Will download N35E138.hgt if not present locally
54//! let elevation = service.get_elevation(35.5, 138.5)?;
55//! ```
56//!
57//! Supported compression formats (auto-detected from URL extension):
58//! - `.hgt.gz` - Gzip compression
59//! - `.hgt.zip` - ZIP archive
60//! - `.hgt` - No compression
61//!
62//! ## Low-Level API
63//!
64//! For more control, you can work with tiles directly:
65//!
66//! ```ignore
67//! use htg::{SrtmTile, filename};
68//!
69//! // Determine which file to load
70//! let filename = filename::lat_lon_to_filename(35.5, 138.7);
71//! assert_eq!(filename, "N35E138.hgt");
72//!
73//! // Load the tile and query elevation
74//! let tile = SrtmTile::from_file(&format!("/data/{}", filename))?;
75//! let elevation = tile.get_elevation(35.5, 138.7)?;
76//! ```
77//!
78//! ## SRTM Data Format
79//!
80//! SRTM files contain elevation data in a simple binary format:
81//!
82//! - **SRTM1**: 3601×3601 samples, 1 arc-second (~30m) resolution
83//! - **SRTM3**: 1201×1201 samples, 3 arc-second (~90m) resolution
84//!
85//! Each sample is a 16-bit big-endian signed integer representing elevation in meters.
86//! The special value -32768 indicates void (no data).
87//!
88//! ## Data Sources
89//!
90//! Download SRTM data from:
91//! - <https://dwtkns.com/srtm30m/>
92//! - <https://earthexplorer.usgs.gov/>
93
94#[cfg(feature = "download")]
95pub mod download;
96
97#[cfg(feature = "geojson")]
98pub mod geojson;
99
100pub mod error;
101pub mod filename;
102pub mod service;
103pub mod tile;
104
105// Re-export main types at crate root for convenience
106pub use error::{Result, SrtmError};
107pub use service::{CacheStats, SrtmService, SrtmServiceBuilder};
108pub use tile::{SrtmResolution, SrtmTile, VOID_VALUE};