coglite

Read windows, pixels and overviews from Cloud-Optimized GeoTIFFs over HTTP(S) or local files, with numpy as the only dependency. No GDAL, no rasterio, no PROJ, no compiled extensions.

coglite is meant for places where installing GDAL is painful or impossible: AWS Lambda / Cloud Functions, slim Docker images, Pyodide / JupyterLite, CI jobs and small tools that only need to pull a few tiles out of a large raster.

import coglite

url = "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/36/Q/WD/2020/7/S2A_36QWD_20200701_0_L2A/B04.tif"
with coglite.open(url) as cog:
    print(cog.profile)            # width, height, dtype, compression, block size, overviews ...
    print(cog.crs_epsg, cog.bounds)
    arr = cog.read(window=(4096, 4096, 1024, 1024))      # (bands, rows, cols) numpy array
    thumb = cog.read_bbox(cog.bounds, max_size=512)      # picks the best overview
    print(thumb.level, thumb.data.shape, thumb.transform)
    print(cog.point(550000, 1850000))                    # values at a map coordinate
    print(cog.reader.stats)                              # requests / bytes actually fetched

Opening that 10980 x 10980 Sentinel-2 band costs one 16 KiB request; the 1024 x 1024 window above is one more request of 1.3 MB.

Installation

pip install coglite                 # numpy only
pip install "coglite[imagecodecs]"  # + JPEG, WebP, ZSTD and LERC decoding

Python 3.9 or newer.

What is supported

Pixel values are verified to be identical to GDAL's (read through rasterio) for every combination above, including overviews and masks; see tests/test_gdal_crossval.py.

API

coglite.open(source, **options) -> COG

source may be a path, an http(s):// or file:// URL, bytes, or a RangeReader. HTTP options: headers, timeout (s, default 30), retries (default 3), max_workers (default 4), merge_gap (bytes, default 64 KiB), cache_bytes (default 32 MiB). prefetch (default 16 KiB) is the size of the first header request.

COG

Coordinate systems: know the limits

coglite has no PROJ. crs= arguments accept only the raster's own EPSG code or the EPSG:4326 / EPSG:3857 pair (converted with the closed-form spherical Mercator formulas). Anything else raises CRSError; reproject your bbox first, e.g. with pyproj. tile() performs no reprojection, so it only works on EPSG:3857 COGs (also 900913, 3785, 102100, 102113), and it never resamples other than nearest neighbour. Rotated or sheared rasters can be read with read(), but read_bbox() and tile() need a north-up transform.

Range requests, coalescing, caching

All block reads of one read() call are gathered and handed to the reader in one batch. The reader

1. returns blocks already in its LRU cache (32 MiB by default),
2. merges ranges whose gap is at most merge_gap bytes (64 KiB by default for HTTP) into one request of at most max_request bytes (16 MiB),
3. issues the merged requests concurrently with up to max_workers threads (4 by default, a polite value for public buckets).

COGs store the tiles of a row next to each other, so a typical window costs one request per few tile rows, or a single request. Measured against the local test server (512 x 512 COG, 32 x 32 tiles):

The header is probed with one request of prefetch bytes; if the IFDs are bigger, the buffer grows (at least doubling) instead of issuing many tiny requests. GDAL-written COGs keep all IFDs at the start of the file, so opening costs one request, and blocks that already arrived with the header buffer are never fetched again (a COG smaller than prefetch is read with one request).

HTTP behaviour: only GET with a Range header is used (never HEAD), so URLs presigned for GET work unchanged. Timeouts, connection errors, HTTP 429 and 5xx are retried with exponential backoff; other HTTP errors raise RangeRequestError at once. A server that ignores Range and answers 200 is handled by keeping the body in memory.

Plugging in other storage

# S3 through boto3 (or anything that can read a byte range)
import boto3, coglite
s3 = boto3.client("s3")

def fetch(offset, length):
    r = s3.get_object(Bucket="my-bucket", Key="dem.tif",
                      Range=f"bytes={offset}-{offset + length - 1}")
    return r["Body"].read()

cog = coglite.open(coglite.CallableReader(fetch, name="s3://my-bucket/dem.tif"))

# or presign and use plain HTTPS
url = s3.generate_presigned_url("get_object", Params={"Bucket": "my-bucket", "Key": "dem.tif"})
cog = coglite.open(url)

# or register a URL scheme once
coglite.register_scheme("s3", lambda url, **kw: coglite.HTTPReader(presign(url), **kw))
cog = coglite.open("s3://my-bucket/dem.tif")

Subclass coglite.RangeReader and implement _fetch(offset, length) (and optionally size) for anything else; caching, coalescing and concurrency come for free.

Pyodide / WebAssembly

Threads are not available in Pyodide: pass max_workers=1. Synchronous urllib needs the pyodide-http patch (pyodide_http.patch_all()), or use a CallableReader around a synchronous XMLHttpRequest, or fetch the file yourself and pass the bytes.

Command line

coglite info https://example.com/cog.tif            # profile, bounds, overviews, I/O used
coglite info cog.tif --json
coglite read cog.tif --bbox 500000 4090000 501000 4100000 --max-size 512 -o out.png
coglite read cog.tif --bbox 28.9 41.0 29.1 41.1 --crs EPSG:4326 -o out.npy   # 3857 COGs
coglite read cog.tif --window 0 0 256 256 --overview 1 --bands 3,2,1 -o rgb.png
coglite validate https://example.com/cog.tif        # exit code 1 when not a valid COG

PNG output is stretched to 8 bits per band (min/max of valid pixels); masked pixels become transparent. --header "Authorization: Bearer ..." adds HTTP headers.

COG validation rules

COG.validate() follows GDAL's validate_cloud_optimized_geotiff.py:

• errors: images (or overviews) larger than 512 x 512 that are not tiled; the first IFD not at the start of the file; IFDs not ordered full resolution then decreasing overviews; IFDs located after image data; image data not stored from the smallest overview to full resolution; a ghost area declaring KNOWN_INCOMPATIBLE_EDITION=YES; block leaders/trailers that contradict the ghost area; non row-major block order when the ghost area promises it;
• warnings: no overviews on large images; tile sizes not multiples of 16 or not powers of two; non row-major block order; overviews stored in SubIFDs.

Performance notes and limitations

• Deflate, LZMA and PackBits decode at native speed. LZW is pure Python (about 0.6 s per MiB of noisy data; much faster on smooth data). Prefer Deflate or ZSTD when you write COGs for coglite.
• No resampling beyond nearest neighbour and no reprojection.
• Not supported: bit depths other than 1/8/16/32/64, palette expansion (ColorMap is ignored; indices are returned), old-style JPEG (compression 6), JPEG-XL, CCITT fax codecs, sample-format mixtures inside one image.
• Multi-page TIFFs: only the first page and its reduced-resolution pages are used.

Development

pip install -e ".[dev]"
pytest                                   # GDAL cross-validation runs when gdal_translate + rasterio exist
ruff check . && ruff format --check src tests && mypy src

tests/data/ holds four tiny GDAL-written fixtures (78 KB in total, regenerated with tests/data/make_fixtures.py). Larger cross-validation files are generated at test time when gdal_translate is available (set COGLITE_GDAL_TRANSLATE to its path, or COGLITE_NO_GDAL=1 to skip them). HTTP tests use a local standard-library server; the test suite never touches the internet.

License

MIT, see LICENSE. Citation metadata is in CITATION.cff.