Skip to main content

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};