Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/terrafloww/rasteret/llms.txt

Use this file to discover all available pages before exploring further.

​
Function Signature

rasteret.build_from_stac(
    *,
    name: str,
    stac_api: str,
    collection: str,
    data_source: str | None = None,
    band_map: dict[str, str] | None = None,
    band_index_map: dict[str, int] | None = None,
    bbox: tuple[float, float, float, float] | None = None,
    date_range: tuple[str, str] | None = None,
    workspace_dir: str | Path | None = None,
    force: bool = False,
    max_concurrent: int = 50,
    cloud_config: Any = None,
    query: dict[str, Any] | None = None,
    backend: StorageBackend | None = None,
    static_catalog: bool = False,
) -> Collection

​
Description

Build or load a local Parquet-backed collection from a STAC API. Searches STAC, parses COG headers for tile metadata, and stores everything in a local Parquet index. On subsequent calls with the same parameters, Rasteret reuses the cached index (no STAC query / header parsing), but pixel reads still fetch remote tiles unless assets are local.

​
Parameters

​
name
str
required
Logical name for the collection.
​
stac_api
str
required
STAC API endpoint URL.
​
collection
str
required
STAC collection ID (e.g., "sentinel-2-l2a").
​
data_source
str
Optional Rasteret data-source key used for band mapping and cloud config lookup. Defaults to collection. Use this to namespace provider-specific conventions (e.g., "earthsearch/sentinel-2-l2a" vs "pc/sentinel-2-l2a") and avoid collisions.
​
band_map
dict[str, str]
Optional mapping of band code to STAC asset key. When omitted, Rasteret falls back to built-in mappings for known collections.
​
band_index_map
dict[str, int]
Optional mapping of band code to the 0-based band/sample index within a multi-sample GeoTIFF asset. Required when multiple requested bands map to the same STAC asset key (e.g., a single multi-band "image" COG).
​
bbox
tuple[float, float, float, float]
required
(minx, miny, maxx, maxy) bounding box for the search.
​
date_range
tuple[str, str]
required
(start, end) ISO date strings.
​
workspace_dir
str | Path
Directory for the local cache. Defaults to ~/rasteret_workspace.
​
force
bool
default:"False"
Rebuild even if a cache already exists.
​
max_concurrent
int
default:"50"
Maximum concurrent COG header fetch operations.
​
cloud_config
CloudConfig
Cloud configuration for URL rewriting.
​
query
dict
Additional STAC search query parameters.
​
backend
StorageBackend
I/O backend for authenticated range reads during COG header parsing. See create_backend().
​
static_catalog
bool
default:"False"
Set to True for static STAC catalogs (no /search endpoint).

​
Returns

​
collection
Collection
A Collection object ready for spatial queries and pixel reads.

​
Usage Example

import rasteret

# Build from Earth Search STAC API
collection = rasteret.build_from_stac(
    name="bay-area-s2",
    stac_api="https://earth-search.aws.element84.com/v1",
    collection="sentinel-2-l2a",
    bbox=(-122.5, 37.5, -122.0, 38.0),
    date_range=("2024-01-01", "2024-03-31"),
)

print(f"Built collection with {len(collection)} scenes")

# Build with custom band mapping
collection = rasteret.build_from_stac(
    name="landsat-c2",
    stac_api="https://landsatlook.usgs.gov/stac-server",
    collection="landsat-c2l2-sr",
    data_source="usgs/landsat-c2l2-sr",
    band_map={
        "B02": "blue",
        "B03": "green",
        "B04": "red",
        "B05": "nir08",
    },
    bbox=(-122.5, 37.5, -122.0, 38.0),
    date_range=("2024-01-01", "2024-03-31"),
)

# Build with additional query filters
collection = rasteret.build_from_stac(
    name="low-cloud",
    stac_api="https://earth-search.aws.element84.com/v1",
    collection="sentinel-2-l2a",
    bbox=(-122.5, 37.5, -122.0, 38.0),
    date_range=("2024-01-01", "2024-03-31"),
    query={"eo:cloud_cover": {"lt": 10}},
)

# Force rebuild of existing cache
collection = rasteret.build_from_stac(
    name="bay-area-s2",
    stac_api="https://earth-search.aws.element84.com/v1",
    collection="sentinel-2-l2a",
    bbox=(-122.5, 37.5, -122.0, 38.0),
    date_range=("2024-01-01", "2024-03-31"),
    force=True,
)

Build docs developers (and LLMs) love

Get started for freeTalk to us