API Reference

These pages are generated directly from the package's docstrings.

Geometry

Build a RasterTransform (an "rt") from a point, a bounding box, or a polygon.

Build a RasterTransform centered on (lon, lat).

The resulting patch is width x height pixels at scale meters/pixel, projected to the appropriate UTM zone for the given coordinates.

Parameters:

Name	Type	Description	Default
lon	float	Longitude in decimal degrees, range [-180, 180].	required
lat	float	Latitude in decimal degrees, range [-90, 90].	required
width	int	Patch width in pixels (must be > 0).	required
height	int	Patch height in pixels (must be > 0).	required
scale	float	Pixel size in meters (must be > 0).	required

Returns:

Type	Description
RasterTransform	RasterTransform anchored so its bounding box is centered on (lon, lat).

Build a RasterTransform covering the given bbox at scale units/pixel.

The output raster's upper-left corner is anchored at (xmin, ymax). If the bbox dimensions aren't exact multiples of scale, the resulting raster extends slightly beyond xmax and below ymin (rounded up) to guarantee full coverage of the input bbox.

Parameters:

Name	Type	Description	Default
xmin	float	Minimum x coordinate (longitude or easting) in crs.	required
ymin	float	Minimum y coordinate (latitude or northing) in crs.	required
xmax	float	Maximum x coordinate in crs.	required
ymax	float	Maximum y coordinate in crs.	required
crs	str	Coordinate Reference System (EPSG code or WKT).	required
scale	float	Pixel size in CRS units (typically meters for projected CRS).	required

Returns:

Type	Description
RasterTransform	RasterTransform whose bbox contains the input bbox at the given scale.

Build a RasterTransform that covers a polygon's bbox.

Earth Engine downloads need an axis-aligned raster grid, so this function takes a Polygon and returns a RasterTransform fitted to it.

Input must be a shapely.Polygon. Convert from other formats before calling:

# From GeoJSON dict
from shapely.geometry import shape
poly = shape(geojson_dict)

# From WKT
from shapely import wkt
poly = wkt.loads(wkt_string)

# From GeoDataFrame (single feature)
poly = gdf.geometry.iloc[0]

Parameters:

Name	Type	Description	Default
geometry	Polygon	A shapely.Polygon. MultiPolygon is not supported — split via .geoms and call this function once per part.	required
scale	float	Pixel size in units of target_crs (meters for UTM, degrees for 4326).	required
crs	str	CRS of the input geometry. Default 'EPSG:4326'.	'EPSG:4326'
target_crs	str | None	CRS of the output. None → auto-UTM by polygon centroid.	None

Returns:

Type	Description
RasterTransform	RasterTransform in target_crs covering the polygon's bbox.

Raises:

Type	Description
TypeError	if geometry is not a shapely.Polygon.
ValueError	if scale <= 0, the polygon is topologically invalid, or coordinates are inconsistent with the declared CRS.

Discovery

Find imagery over one rt or a list of rts.

Discover images of an asset over one ROI or many, returning a RequestTable.

Accepts either a single RasterTransform (one ROI) or a list of them (many ROIs, e.g. a tiled dataset). With a list, discovery runs in concurrent server-side batches and the rows of all rts are combined into one table.

Parameters:

Name	Type	Description	Default
asset_id	str	GEE asset id (IMAGE or IMAGE_COLLECTION).	required
raster_transform	RasterTransform | list[RasterTransform]	one RasterTransform, or a list of them. Each becomes the geotransform of its discovered rows.	required
start	str | None	start date 'YYYY-MM-DD' for temporal assets.	None
end	str | None	end date 'YYYY-MM-DD' for temporal assets.	None
with_bands	bool	fetch band names from the asset (one cheap getInfo, cached).	True
mosaic	str | None	if set (e.g. "date"), mosaic the result via table.mosaic(by=...).	None
batch_size	int	(multi-rt only) initial rts per server-side batch.	30
nworkers	int	(multi-rt only) concurrent batches in flight.	8

Returns:

Type	Description
RequestTable	RequestTable. For a list input, any rts that could not be resolved (even
RequestTable	after shrink-and-retry) are reported via a warning; call discover_many
RequestTable	directly if you need the explicit list of unresolved indices.

Metrics

Score each image with your own function, plus automatic coverage.

Enrich a discovered RequestTable with coverage_pct + a user-defined score.

Works for single-rt and multi-rt tables: each row is scored over ITS OWN geometry/scale (from its own raster_transform), so multi-point tables score correctly. Large tables are split into batches scored concurrently; any batch that hits the server memory limit is split and retried.

Parameters:

Name	Type	Description	Default
table	RequestTable	A RequestTable from discover_images OR .mosaic().	required
score_fn	Callable	Callable (image, geometry[, source_ids][, scale]) returning ee.Number. If it declares a scale parameter, it receives the same adaptive coarse scale used for coverage.	required
target_coarse_pixels	int	Approx pixels per side in the metrics reduceRegion.	128
batch_size	int	rows per server-side call (kept modest; heavy score_fns may need a smaller value to avoid the memory limit).	50
nworkers	int	concurrent batches in flight.	8

Returns:

Type	Description
RequestTable	A new RequestTable with coverage_pct and score in each row's metadata.

Raises:

Type	Description
ValueError	if the table is empty, a row has a malformed string image, or score_fn fails the dry-run.

Download

Download a table of requests, with automatic tiling on GEE size limits.

Download every row in a RequestTable to disk using a global tile pool.

Rows are grouped by cost signature (bands, width, height). Each group probes Earth Engine once to learn its bytes-per-pixel; the rest of the group is expanded into tiles by prediction, no extra probes. All tiles of all groups are then downloaded through a single shared queue so workers never sit idle.

Parameters:

Name	Type	Description	Default
table	RequestTable	Plan of requests. May be heterogeneous; it will be grouped.	required
outfolder	str | Path	Where to write the final files (one per row).	required
nworkers	int	Number of worker threads for the global download pool.	8
file_format	str	EE pixel format. NUMPY_NDARRAY is not supported here.	'GEO_TIFF'
overwrite	bool	If False, rows whose output file already exists are skipped.	False
verbose	bool	Print progress lines to stdout.	True

Returns:

Type	Description
ExpressResult	ExpressResult with .paths (id → file path) and .failed (id → exception).