Skip to main content

Crate cogrs

Crate cogrs 

Source
Expand description

§cogrs

Pure Rust COG (Cloud Optimized GeoTIFF) reader library.

Published on crates.io as cogrs-eg: Earth Genome’s fork of evanjt/cogrs. The library is still imported as cogrs:

[dependencies]
cogrs-eg = "0.2"

§Features

§Quick Start

use cogrs::{CogReader, PointQuery, TileExtractor};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let reader = CogReader::open_async("path/to/file.tif").await?;

    // Point query (async: the containing tile is fetched without blocking a thread)
    let result = reader.sample_lonlat_async(-122.4, 37.8).await?;

    // XYZ tile extraction (async)
    let tile = TileExtractor::new(&reader)
        .xyz(10, 163, 395)
        .extract()
        .await?;

    Ok(())
}

§Sources

Remote I/O (S3, HTTP(S)) is natively asynchronous. From async code (axum/tokio handlers, etc.) open with CogReader::open_async and extract with TileExtractor: waiting on the network never occupies a thread, and a tile that needs several source tiles fetches them concurrently (adjacent byte ranges are merged into one request, identical in-flight tiles are shared between concurrent requests). Only decoding and resampling use tokio’s blocking pool. Works on multi_thread and current_thread runtimes.

use cogrs::CogReader;
// Local file
let reader = CogReader::open_async("path/to/file.tif").await?;

// HTTP
let reader = CogReader::open_async("https://example.com/file.tif").await?;

// S3 (uses AWS_* environment variables for credentials)
let reader = CogReader::open_async("s3://bucket/path/to/file.tif").await?;

S3 configuration: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (plus AWS_SESSION_TOKEN for temporary credentials), AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN (EKS IRSA), AWS_CONTAINER_CREDENTIALS_FULL_URI + AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE (EKS Pod Identity) or AWS_CONTAINER_CREDENTIALS_RELATIVE_URI (ECS) for credentials, falling back to the EC2 instance metadata service; AWS_SKIP_SIGNATURE=true for anonymous access to public buckets, AWS_ENDPOINT_URL / AWS_ALLOW_HTTP for MinIO and other S3-compatible stores. The region is taken from AWS_REGION, then AWS_DEFAULT_REGION; if neither is set it is detected from the bucket (once per bucket per process) unless a custom endpoint is configured.

BigTIFF. COGs larger than 4 GiB are stored as BigTIFF (TIFF version 43: 8-byte offsets, 20-byte IFD entries, LONG8 tile offsets); CogReader reads them exactly like classic TIFF COGs, local or remote, sync or async, through the same header and tile caches. A BigTIFF’s tile arrays are twice as large, so opening one reads about 1.4x the header bytes of the same COG as a classic TIFF (and, once the arrays outgrow the 16 KiB open request, up to one more request); the header cache makes that a one-time cost. The local-file TiffChunkedRasterSource and LzwRasterSource parse classic TIFF only and return an error naming BigTIFF.

Opening a remote COG is one ranged request (header, IFDs, size and ETag together), and every COG in the same bucket or host shares one HTTP client. Pass an OverviewQualityHint (see open_async_with_hint) to skip sampling tiles from the coarsest overview at open, and IoOptions (see open_async_with_options) to tune the concurrency limits, range coalescing, retries and timeouts:

use cogrs::{CogReader, IoOptions, OverviewQualityHint};
let options = IoOptions { max_concurrent_requests: 8, ..IoOptions::default() };
let reader = CogReader::open_async_with_options(
    "s3://bucket/path/to/file.tif",
    OverviewQualityHint::AllUsable,
    &options,
)
.await?;
// `CogReader` is cheap to clone (metadata is shared), so keep one per source and clone it
// into handlers.
let for_handler = reader.clone();

Plain threads (no async runtime) can use the synchronous API: CogReader::open, read_tile, sample_lonlat, … Remote sources work there too; the request runs on a private I/O runtime while the calling thread blocks. On an async worker thread those calls block that worker, so use the *_async methods (or reader.spawn_blocking(..) for other sync work).

§Point Queries

Async code uses sample_lonlat_async / sample_crs_async / sample_points_lonlat_async; the synchronous PointQuery trait below is for plain threads.

use cogrs::{CogReader, PointQuery};
let reader = CogReader::open("elevation.tif")?;

// Sample at lon/lat
let result = reader.sample_lonlat(-122.4, 37.8)?;
for (band, value) in &result.values {
    println!("Band {band}: {value}");
}

// Sample in specific CRS (e.g., UTM zone 10N)
let result = reader.sample_crs(32610, 551000.0, 4185000.0)?;

§Tile Extraction

use cogrs::{CogReader, TileExtractor, ResamplingMethod};
let reader = CogReader::open_async("imagery.tif").await?;

// Simple extraction (256x256)
let tile = TileExtractor::new(&reader)
    .xyz(10, 163, 395)
    .extract()
    .await?;

// With options
let tile = TileExtractor::new(&reader)
    .xyz(10, 163, 395)
    .output_size(512, 512)
    .resampling(ResamplingMethod::Bilinear)
    .bands(&[0, 1, 2])
    .extract()
    .await?;

§Resampling

ResamplingMethodKernelgdalwarp equivalent
Nearest (default)pixel containing the output pixel centre-r near (bit-identical)
Bilineartent, 2x2 taps-r bilinear
CubicCatmull-Rom (Keys, a = -0.5), 4x4 taps-r cubic
BicubicMitchell-Netravali (B = C = 1/3), 4x4 tapsnone (softer than Cubic)

When an output pixel covers more than about one source pixel, the bilinear and both cubic kernels are stretched by that ratio (anti-aliasing), as gdalwarp does.

§Caching

A tile server opens the same image for every request, so two caches sit behind CogReader::open* / TileExtractor:

  • Header cache (CogCache, remote sources only): the parsed header of each source, its overview metadata, what the server reported about the object (size, ETag, last-modified) and the computed overview-quality hint. Opening a cached source sends no request, and the sampling that OverviewQualityHint::ComputeAtRuntime does runs once per source, not once per open. Concurrent first opens of one source share a single request. Local files are not cached (parsing them is cheap).
  • Decoded tile cache (process-wide, byte-bounded LRU): decompressed source tiles, keyed by the source and its version (ETag, or size and modification time for local files), so a replaced object can never be served from tiles decoded from its predecessor.
SettingDefault
CacheConfig::capacity_bytes64 MiBheader entries weigh about 1.5 KiB + 16 B per tile: ~12 KB for a 10980 x 10980 COG with 512 px tiles, 0.8 to 3.3 MB for 100k x 100k
CacheConfig::ttl1 hourentries whose reads can be validated (below)
CacheConfig::ttl_unvalidated60 secondsentries from servers that give no usable validator
CacheConfig::negative_ttl5 secondshow long a 404 is remembered (0 = off); 401/403, server errors and timeouts never are
CacheConfig::validationValidation::IfMatchsee below
tile cache capacity512 MiBtile_cache::set_capacity, or COGRS_TILE_CACHE_MB

When the object is overwritten. Cached headers are only valid for the version they were read from. With the default Validation::IfMatch, every range request after the open carries the object’s ETag as If-Match (or If-Unmodified-Since when the server has a Last-Modified but no strong ETag; weak ETags are never sent). A replaced object answers 412, and the operation recovers on its own: the stale header entry and the old version’s decoded tiles are dropped, the object is opened again (once, shared by all concurrent callers), and the extraction or point query runs again against the new header, once. The conditions travel with the requests that are sent anyway; they cost no round trip. S3 honours them (verified against the real bucket by an ignored test), and so do HTTP servers that implement RFC 9110 If-Match.

What it cannot detect: a server that ignores If-Match, or gives neither ETag nor Last-Modified, can only be caught when the entry’s time to live runs out (ttl_unvalidated, 60 s, for the latter). For objects that are never overwritten (date-versioned keys), Validation::Immutable sends no conditions and never expires entries; Validation::Ttl sends no conditions and expires entries after ttl. Low-level read_tile* calls report SourceChanged instead of retrying (a tile index only means something for the header it came from); a reader you keep for a long time stays pinned to the version it opened, like an open file handle, and every operation on it then costs one 412 plus a cached reopen: reopen the source (open_async) when you know it changed, or call reader.reopen_after_change().

use cogrs::{CacheConfig, CacheMode, CogCache, CogReader, Validation};
// The global cache is used automatically; `COGRS_HEADER_CACHE=off` disables it, and
// `COGRS_HEADER_CACHE_MB` sizes it.
let reader = CogReader::open_async("s3://bucket/dated/2026-09-01/tci.tif").await?;

// Your own cache (sized, immutable keys), passed explicitly; or `CogCache::disabled()`
let cache = CogCache::new(CacheConfig { validation: Validation::Immutable, ..CacheConfig::default() });
let reader = CogReader::builder("s3://bucket/dated/2026-09-01/tci.tif").cache(&cache).open_async().await?;
// `CacheMode::Bypass` / `CacheMode::Refresh` per open
let fresh = CogReader::builder("s3://bucket/live.tif").cache_mode(CacheMode::Refresh).open_async().await?;

// You overwrote the object and want the next open to see it: drop it
CogCache::global().invalidate("s3://bucket/live.tif");

// Metrics: header hits/misses/evictions/expirations/coalesced opens/412 evictions/negative hits,
// decoded-tile hits/misses/evictions, and network requests and bytes
let stats = CogCache::global().stats();
println!("{} header hits, {} tile hits", stats.headers.hits, stats.tiles.hits);
println!("{:?}", cogrs::io_stats());

stats() costs a couple of atomic loads and one short lock; the counters are atomics, so reading them or counting a hit adds nothing to the hot path beyond the locks the caches already take.

Presigned and SAS URLs. The query string is not part of a source’s identity: two presigned URLs for one object share one header entry and the same decoded tiles, and each reader sends its own query string with its requests. That is what makes caching useful with per-request signed URLs, but it also means a cached header or tile can be served to a caller whose URL has expired or was never valid; access control stays with whoever hands out the URLs (S3 sources include the access key in the cache key, so credentials are not shared). The decoded tile cache has always worked this way. Use CacheMode::Bypass or a separate CogCache where that is not acceptable.

§WebP Output

Extracted tiles encode to lossless RGBA8 WebP (pure Rust). Pixels equal to the COG’s nodata value (in all bands) or NaN become transparent; 1-band tiles are expanded to gray, 3-band to RGB, 4-band keeps its alpha. Values are rounded and clamped to 0..=255; use WebpOptions::rescale for 16-bit/float data. Areas of a tile outside the COG extent are filled with the COG’s nodata value (or NaN if it declares none), so edge tiles come out transparent there.

use cogrs::{CogReader, TileExtractor, WebpOptions};
let reader = CogReader::open_async("imagery.tif").await?;
let tile = TileExtractor::new(&reader).xyz(10, 163, 395).extract().await?;

let webp: Vec<u8> = tile.to_webp()?;

// 16-bit source: map 0..3000 linearly onto 0..255, override nodata
let opts = WebpOptions { rescale: Some((0.0, 3000.0)), nodata: Some(0.0) };
let webp = tile.to_webp_with(&opts)?;

§Coordinate Transforms

use cogrs::{CoordTransformer, project_point};

// One-off transform
let (x, y) = project_point(4326, 3857, -122.4, 37.8)?;

// Reusable transformer
let transformer = CoordTransformer::new(4326, 32610)?;
let (utm_x, utm_y) = transformer.transform(-122.4, 37.8)?;

§Compression

Supported formats are detected automatically:

  • DEFLATE
  • LZW (8/16-bit, predictors 1-3)
  • ZSTD
  • JPEG
  • WebP

§License

MIT, see LICENSE. Originally written by Evan Thomas (evanjt/cogrs).

§Architecture

The library is organized into several modules:

Re-exports§

pub use cog_reader::CogReader;
pub use cog_reader::CogReaderBuilder;
pub use cog_reader::CogMetadata;
pub use cog_reader::CogDataType;
pub use cog_reader::Compression;
pub use cog_reader::GeoTransform;
pub use cog_reader::OverviewMetadata;
pub use cog_reader::OverviewQualityHint;
pub use header_cache::CacheConfig;
pub use header_cache::CacheMode;
pub use header_cache::CacheStats;
pub use header_cache::CogCache;
pub use header_cache::HeaderCacheStats;
pub use tile_cache::TileCacheStats;
pub use point_query::PointQuery;
pub use point_query::PointQueryResult;
pub use point_query::sample_point;
pub use point_query::sample_point_crs;
pub use xyz_tile::TileData;
pub use xyz_tile::TileExtractor;
pub use xyz_tile::BoundingBox;
pub use xyz_tile::CoordTransformer;
pub use xyz_tile::ResamplingMethod;
pub use xyz_tile::DEFAULT_TRANSFORM_ERROR;
pub use webp::WebpOptions;
pub use xyz_tile::Reprojector;
pub use xyz_tile::ReprojectedRaster;
pub use xyz_tile::StreamingReprojector;
pub use xyz_tile::StreamingOutputInfo;
pub use xyz_tile::RasterChunk;
pub use geometry::Point;
pub use geometry::projection::project_point;
pub use geometry::projection::lon_lat_to_mercator;
pub use geometry::projection::mercator_to_lon_lat;
pub use geometry::projection::try_lon_lat_to_mercator;
pub use geometry::projection::try_mercator_to_lon_lat;
pub use geometry::projection::get_proj_string;
pub use geometry::projection::is_geographic_crs;
pub use range_reader::RangeReader;
pub use range_reader::LocalRangeReader;
pub use range_reader::HttpRangeReader;
pub use range_reader::MemoryRangeReader;
pub use range_reader::create_range_reader;
pub use async_io::AsyncRangeReader;
pub use async_io::AsyncToSync;
pub use async_io::IoOptions;
pub use async_io::RangeFetchError;
pub use async_io::SourceChanged;
pub use async_io::SyncToAsync;
pub use async_io::fetch_ranges;
pub use async_io::is_source_changed;
pub use remote::IoStats;
pub use remote::ObjectStoreRangeReader;
pub use remote::SourceNotFound;
pub use remote::Validation;
pub use remote::create_async_range_reader;
pub use remote::create_async_range_reader_with;
pub use remote::io_stats;
pub use s3::S3Config;
pub use s3::S3RangeReaderAsync;
pub use s3::S3RangeReaderSync;
pub use source::CogSource;
pub use source::CogEntry;
pub use source::CogLocation;
pub use source::LocalCogSource;
pub use source::LocalScanOptions;
pub use source::LocalSourceStats;
pub use source::S3CogSource;
pub use source::S3ScanOptions;
pub use source::S3SourceStats;
pub use tile_cache::TileCache;
pub use raster::RasterSource;
pub use geotiff_writer::GeoTiffCompression;
pub use geotiff_writer::GeoTiffWriteError;
pub use geotiff_writer::GeoTiffWriter;

Modules§

async_io
Asynchronous byte-range I/O.
casting
Safe numeric casting utilities for geospatial image processing.
cog_reader
Pure Rust COG (Cloud Optimized GeoTIFF) reader
geometry
geotiff_writer
GeoTIFF writer for reprojected rasters
header_cache
Process-wide cache of parsed COG headers for remote sources.
lzw_fallback
Fallback LZW TIFF reader that streams tiles on demand.
point_query
Point query functionality for sampling COG values at geographic coordinates.
range_reader
Range-based reader interface for COG files
raster
remote
Remote (S3 / HTTP(S)) async range reader built on object_store.
s3
S3 Range Reader implementation using object_store
source
COG source discovery and abstraction.
tiff_chunked
tiff_utils
tile_cache
Process-wide cache of decoded (decompressed, f32) source tiles.
webp
Lossless WebP encoding of extracted tiles.
xyz_tile
XYZ tile extraction from COG files