GitHub - terrafloww/rasteret: Rasteret is a library for 20x+ faster reads of GeoTIFF than Rasterio/GDAL. Interops with TorchGeo, Xarray, DuckDB, Polars

Build a collection once. Query it like a table. Read pixels 20x faster from cloud COGs.

Rasteret is an index-first reader for cloud-hosted tiled GeoTIFFs and COGs. It builds a queryable Arrow/Parquet collection with scene metadata, asset URLs, CRS sidecars, and parsed COG header metadata. Pixels stay in the original COGs.

After that, you can filter, join, and enrich the collection as a table, then read only the pixels you need into NumPy, xarray, GeoPandas, TorchGeo, or Arrow point-sample tables.

STAC / Parquet / Arrow table -> Rasteret Collection -> NumPy / xarray / GeoPandas / TorchGeo
external labels / plots / points    filter/join/share          read pixels on demand

Why Rasteret

Remote raster workflows often repeat the same setup work: STAC loops, COG header parsing, tile byte-range planning, CRS transforms, retries, and output assembly.

Rasteret moves the expensive raster metadata discovery into a Collection build step and reuses that metadata for later reads.

That helps when you:

• train or evaluate models over many remote COG scenes
• repeatedly sample the same imagery with different AOIs, points, labels, or splits
• avoid rediscovering raster header metadata in new notebooks, containers, or machines
• want one source collection to feed TorchGeo, xarray, NumPy, GeoPandas, and Arrow tools
• need DuckDB, Polars, PyArrow, or GeoPandas to work on metadata and external geometries before pixel reads

Quick Example

import rasteret

sentinel2_collection = rasteret.build(
    "earthsearch/sentinel-2-l2a",
    name="s2_bangalore",
    bbox=(77.5, 12.9, 77.7, 13.1),
    date_range=("2024-01-01", "2024-01-31"),
)

clear = sentinel2_collection.subset(cloud_cover_lt=50)

arr = clear.get_numpy(
    geometries=(77.55, 13.01, 77.58, 13.08),
    bands=["B04", "B08"],
)

The same collection can feed TorchGeo:

dataset = clear.to_torchgeo_dataset(
    bands=["B04", "B03", "B02", "B08"],
    chip_size=256,
)

Bring Your Own Geometry And Metadata

Rasteret works well with the table tools you already use. External labels, farm plots, asset locations, fire boundaries, or point samples can stay in GeoPandas, DuckDB, Polars, or PyArrow until you need pixels.

import duckdb
import geopandas as gpd
import rasteret
from shapely.geometry import box

plots = gpd.GeoDataFrame(
    {
        "plot_id": ["plot-a"],
        "crop": ["rice"],
    },
    geometry=[box(77.55, 13.01, 77.58, 13.08)],
    crs="OGC:CRS84",
)
plots_arrow = plots.to_arrow(geometry_encoding="WKB")

con = duckdb.connect()
con.sql("INSTALL spatial; LOAD spatial;")
con.register("sen2_rasteret", clear)
con.register("plots", plots_arrow)

# Bring your own geometries
plot_aois = con.sql("""
    SELECT
        plots.plot_id,
        plots.crop,
        plots.geometry AS plot_geometry
    FROM sen2_rasteret, plots
    WHERE sen2_rasteret."eo:cloud_cover" < 10
      AND ST_Intersects(
          ST_GeomFromWKB(sen2_rasteret.geometry),
          ST_GeomFromWKB(plots.geometry)
      )
""")

plot_patches = clear.get_gdf(
    geometries=plot_aois,
    geometry_column="plot_geometry",
    geometry_crs=4326,
    bands=["B04", "B08"],
)

The same pattern works with Polars or PyArrow for split/label columns, and with sample_points(...) when your external data is point-based. get_gdf(...) and sample_points(...) keep business columns such as plot_id in their outputs.

What You Can Do

Dataset Catalog

Rasteret ships with dataset IDs so you do not have to remember STAC endpoints, band maps, license metadata, or cloud access settings. Most catalog entries are recipes for rasteret.build(...): Rasteret searches the source catalog, parses the COG metadata once, and writes a reusable local Collection.

Only one built-in ID is already a read-ready Rasteret Collection: aef/v1-annual. Use rasteret.load("aef/v1-annual") for AlphaEarth Foundation Embeddings. The built-in alias loads Rasteret's maintained Source Cooperative Collection. You do not need to call build() for this dataset.

You can browse the same list from the CLI:

rasteret datasets list
rasteret datasets info aef/v1-annual

To make your own dataset ID for a reusable local collection or Parquet record table, see Register A Local Collection into Dataset Catalog.

Performance

Rasteret is 10x to 20x faster than rasterio/GDAL

Rasteret also compares well against time-series workflows that use Google Earth Engine or thread-pooled rasterio for the measured setup:

See the Benchmarks guide for methodology, environment details, and additional Hugging Face datasets comparisons.

Install

Optional integrations:

uv pip install "rasteret[torchgeo]"
uv pip install "rasteret[aws]"
uv pip install "rasteret[azure]"
uv pip install "rasteret[all]"  # all optional integrations for exploration

Rasteret requires Python 3.12 or later.

Learn More

• Getting Started
• Build from Parquet and Arrow Tables
• Bring Your Own AOIs, Points, And Metadata
• TorchGeo Integration
• Benchmarks
• API Reference

License

Code: Apache-2.0