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(
    dataset: str,
    *,
    name: str,
    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,
    query: dict[str, Any] | None = None,
    prefer_geoparquet: bool = False,
    stac_api: str | None = None,
    cloud_config: Any = None,
    backend: StorageBackend | None = None,
) -> Collection

​
Description

Build a Collection from a registered dataset. Looks up the dataset in the DatasetRegistry and routes to either build_from_stac() or build_from_table() based on the descriptor’s access fields. For descriptors backed only by geoparquet_uri (e.g., local collections registered with register_local()), bbox and date_range are optional and ignored. For auth-required datasets, Rasteret can auto-create a backend from a descriptor’s s3_credentials_url when no explicit backend is passed. This requires valid credentials in the environment (or ~/.netrc) for the relevant provider.

​
Parameters

​
dataset
str
required
Registry ID (e.g., "earthsearch/sentinel-2-l2a").
​
name
str
required
Logical name for the collection.
​
bbox
tuple[float, float, float, float]
(minx, miny, maxx, maxy) bounding box. Required for STAC-backed descriptors.
​
date_range
tuple[str, str]
(start, end) ISO date strings. Required for STAC-backed descriptors.
​
workspace_dir
str | Path
Cache directory. Defaults to ~/rasteret_workspace.
​
force
bool
default:"False"
Rebuild even if a cache already exists.
​
max_concurrent
int
default:"50"
Maximum concurrent COG header fetches.
​
query
dict
Additional STAC search parameters.
​
prefer_geoparquet
bool
default:"False"
Use the GeoParquet path when available.
​
stac_api
str
Override the descriptor’s default STAC API endpoint.
​
cloud_config
CloudConfig
Cloud configuration for URL rewriting.
​
backend
StorageBackend
I/O backend for authenticated range reads. When omitted, Rasteret auto-creates one for known auth-required datasets. See create_backend().

​
Returns

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

​
Raises

  • KeyError: If the dataset is not in the registry.
  • ValueError: If the descriptor has no configured access method, or if auth is required but no backend could be created.

​
Usage Example

import rasteret

# Build from a registered dataset
collection = rasteret.build(
    "earthsearch/sentinel-2-l2a",
    name="bay-area-2024",
    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")

# Force rebuild with additional query parameters
collection = rasteret.build(
    "earthsearch/sentinel-2-l2a",
    name="bay-area-clear",
    bbox=(-122.5, 37.5, -122.0, 38.0),
    date_range=("2024-01-01", "2024-03-31"),
    query={"eo:cloud_cover": {"lt": 10}},
    force=True,
)