cogrs/lib.rs
1#![doc = include_str!("../README.md")]
2//!
3//! ## Architecture
4//!
5//! The library is organized into several modules:
6//!
7//! - [`cog_reader`]: Core COG metadata parsing and tile reading
8//! - [`point_query`]: Geographic coordinate sampling via [`PointQuery`] trait (sync) and
9//! `CogReader::sample_*_async`
10//! - [`xyz_tile`]: XYZ tile extraction with [`TileExtractor`] builder
11//! - [`geometry`]: Coordinate types ([`Point`], [`BoundingBox`]) and projections
12//! - [`async_io`]: [`AsyncRangeReader`], the core I/O abstraction, range coalescing
13//! ([`fetch_ranges`]), [`IoOptions`], and sync/async adapters
14//! - [`remote`]: S3 and HTTP(S) reader built on `object_store` ([`ObjectStoreRangeReader`])
15//! - [`range_reader`]: synchronous [`RangeReader`] for local files, memory and plain threads
16//! - [`source`]: COG discovery from directories and S3 buckets
17//! - [`tile_cache`]: Global LRU cache for decompressed tiles
18//! - [`s3`]: S3 configuration, region resolution and S3 reader front-ends
19//! - [`raster`]: Raster data abstraction trait
20//! - [`geotiff_writer`]: Write reprojected rasters to GeoTIFF files
21//! - [`webp`]: Lossless RGBA WebP encoding of extracted tiles ([`TileData::to_webp`])
22
23// ============================================================================
24// Public modules
25// ============================================================================
26
27pub mod async_io;
28pub mod casting;
29pub mod cog_reader;
30pub mod geometry;
31pub mod geotiff_writer;
32pub mod header_cache;
33pub mod lzw_fallback;
34pub mod point_query;
35mod point_query_async;
36mod predictor;
37pub mod range_reader;
38pub mod raster;
39pub mod s3;
40pub mod source;
41pub mod tiff_chunked;
42pub mod remote;
43pub mod tiff_utils;
44pub mod tile_cache;
45mod tile_fetch;
46pub mod xyz_tile;
47pub mod webp;
48
49#[cfg(test)]
50mod test_support;
51#[cfg(test)]
52mod golden_tests;
53#[cfg(test)]
54mod extract_tests;
55#[cfg(test)]
56mod gdal_comparison_tests;
57#[cfg(test)]
58mod bigtiff_tests;
59
60// ============================================================================
61// Core COG Types
62// ============================================================================
63
64pub use cog_reader::{
65 CogReader,
66 CogReaderBuilder,
67 CogMetadata,
68 CogDataType,
69 Compression,
70 GeoTransform,
71 OverviewMetadata,
72 OverviewQualityHint,
73};
74
75// ============================================================================
76// Header cache
77// ============================================================================
78
79pub use header_cache::{CacheConfig, CacheMode, CacheStats, CogCache, HeaderCacheStats};
80pub use tile_cache::TileCacheStats;
81
82// ============================================================================
83// Point Queries
84// ============================================================================
85
86pub use point_query::{
87 PointQuery,
88 PointQueryResult,
89 sample_point,
90 sample_point_crs,
91};
92
93// ============================================================================
94// XYZ Tile Extraction
95// ============================================================================
96// Primary API: TileExtractor::new(&reader).xyz(...).extract().await
97
98pub use xyz_tile::{
99 TileData,
100 TileExtractor,
101 BoundingBox,
102 CoordTransformer,
103 ResamplingMethod,
104 DEFAULT_TRANSFORM_ERROR,
105};
106
107pub use webp::WebpOptions;
108
109// ============================================================================
110// Raster Reprojection
111// ============================================================================
112// Primary API: Reprojector::new(&reader).to_crs(...).extract().await
113
114pub use xyz_tile::{
115 Reprojector,
116 ReprojectedRaster,
117 StreamingReprojector,
118 StreamingOutputInfo,
119 RasterChunk,
120};
121
122// ============================================================================
123// Geometry & Projections
124// ============================================================================
125
126pub use geometry::Point;
127pub use geometry::projection::{
128 project_point,
129 lon_lat_to_mercator,
130 mercator_to_lon_lat,
131 try_lon_lat_to_mercator,
132 try_mercator_to_lon_lat,
133 get_proj_string,
134 is_geographic_crs,
135};
136
137// ============================================================================
138// Range Readers (I/O Abstraction)
139// ============================================================================
140
141pub use range_reader::{
142 RangeReader,
143 LocalRangeReader,
144 HttpRangeReader,
145 MemoryRangeReader,
146 create_range_reader,
147};
148
149pub use async_io::{
150 AsyncRangeReader,
151 AsyncToSync,
152 IoOptions,
153 RangeFetchError,
154 SourceChanged,
155 SyncToAsync,
156 fetch_ranges,
157 is_source_changed,
158};
159pub use remote::{
160 IoStats, ObjectStoreRangeReader, SourceNotFound, Validation, create_async_range_reader, create_async_range_reader_with,
161 io_stats,
162};
163
164// ============================================================================
165// S3 Support
166// ============================================================================
167
168pub use s3::{
169 S3Config,
170 S3RangeReaderAsync,
171 S3RangeReaderSync,
172};
173
174// ============================================================================
175// Source Discovery
176// ============================================================================
177
178pub use source::{
179 CogSource,
180 CogEntry,
181 CogLocation,
182 LocalCogSource,
183 LocalScanOptions,
184 LocalSourceStats,
185 S3CogSource,
186 S3ScanOptions,
187 S3SourceStats,
188};
189
190// ============================================================================
191// Caching
192// ============================================================================
193
194pub use tile_cache::TileCache;
195
196// ============================================================================
197// Raster Abstraction
198// ============================================================================
199
200pub use raster::RasterSource;
201
202// ============================================================================
203// GeoTIFF Writing
204// ============================================================================
205
206pub use geotiff_writer::{
207 GeoTiffCompression,
208 GeoTiffWriteError,
209 GeoTiffWriter,
210};