odc.stac.load¶
- odc.stac.load(items, bands=None, *, groupby=None, resampling=None, chunks=None, crs=None, resolution=None, geobox=None, bbox=None, lon=None, lat=None, x=None, y=None, align=None, like=None, geopolygon=None, stac_cfg=None, patch_url=None, product_cache=None, skip_broken_datasets=False, progress_cbk=None, fuse_func=None, **kw)[source]¶
STAC
Item
toxarray.Dataset
.Load several STAC
Item
objects (from the same or similar collections) as anxarray.Dataset
.This method can load pixel data directly on a local machine or construct a Dask graph that can be processed on a remote cluster.
catalog = pystac.Client.open(...) query = catalog.search(...) xx = odc.stac.load( query.get_items(), bands=["red", "green", "blue"], crs="EPSG:32606", resolution=(-100, 100), ) xx.red.plot.imshow(col="time")
- Parameters
Common Options
- Parameters
groupby (
Optional
[str
]) – Controls what items get placed in to the same pixel plane, supported values are “time” or “solar_day”, default is “time”resampling (
Union
[str
,Dict
[str
,str
],None
]) – Controls resampling strategy, can be specified per bandchunks (
Optional
[Dict
[str
,int
]]) – Rather than loading pixel data directly, construct Dask backed arrays.chunks={'x': 2048, 'y': 2048}
Control Pixel Grid of Output
There are many ways to control footprint and resolution of returned data. The most precise way is to use
GeoBox
,geobox=GeoBox(..)
. Similarly one can uselike=xx
to match pixel grid to previously loaded data (xx = odc.stac.load(...)
).Other common way is to configure crs and resolution only
xx = odc.stac.load(... crs="EPSG:3857", resolution=(-10, 10)) # resolution units must match CRS # here we assume 1 degree == 111km to load at roughly # the same 10m resolution as statement above. yy = odc.stac.load(... crs="EPSG:4326", resolution=0.00009009)
By default
odc.stac.load()
loads all available pixels in the requested projection and resolution. To limit extent of loaded data you have to supply bounds via eithergeobox=
orlike=
parameters (these also select projection and resolution). Alternatively use a pair ofx, y
orlon, lat
parameters.x, y
allows you to specify bounds in the output projection, whilelon, lat
operate in degrees. You can also usebbox
which is equivalent tolon, lat
.It should be noted that returned data is likely to reach outside of the requested bounds by fraction of a pixel when using
bbox
,x, y
orlon, lat
mechanisms. This is due to pixel grid “snapping”. Pixel edges will still start atN*pixel_size
whereN is int
regardless of the requested bounding box.- Parameters
crs (
Union
[str
,CRS
,CRS
,Dict
[str
,Any
],None
]) – Load data in a given CRSresolution (
Union
[float
,int
,Tuple
[float
,float
],None
]) – Set resolution of output inY, X
order, it is common forY
to be negative, e.g.resolution=(-10, 10)
. Resolution must be supplied in the units of the output CRS, so they are commonly in meters for Projected and in degrees for Geographic CRSs.resolution=10
is equivalent toresolution=(-10, 10)
.bbox (
Optional
[Tuple
[float
,float
,float
,float
]]) – Specify bounding box in Lon/Lat.[min(lon), min(lat), max(lon), max(lat)]
lon (
Optional
[Tuple
[float
,float
]]) – Define output bounds in Lon/Latlat (
Optional
[Tuple
[float
,float
]]) – Define output bounds in Lon/Latx (
Optional
[Tuple
[float
,float
]]) – Define output bounds in output projection coordinate unitsy (
Optional
[Tuple
[float
,float
]]) – Define output bounds in output projection coordinate unitsalign (
Union
[float
,int
,Tuple
[float
,float
],None
]) – Control pixel snapping, default is to align pixel grid toX
/Y
axis such that pixel edges lie on the axis.geobox (
Optional
[GeoBox
]) – Allows to specify exact region/resolution/projection usingGeoBox
objectlike (
Optional
[Any
]) – Match output grid to the data loaded previously.
STAC Related Options
- Parameters
stac_cfg (
Optional
[Dict
[str
,Any
]]) –Controls
pystac.Item
->
datacube.model.Dataset
conversion, mostly used to specify “missing” metadata like pixel data types.See
stac2ds()
and section below for more details.patch_url (
Optional
[Callable
[[str
],str
]]) – Optionally transform url of every band before loadingproduct_cache (
Optional
[Dict
[str
,DatasetType
]]) – Passed on tostac2ds()
Pass-through to
datacube.Datacube.load()
- Parameters
progress_cbk (
Optional
[Callable
[[int
,int
],Any
]]) – Get data loading progress via callback, ignored when constructing Dask arraysskip_broken_datasets (
bool
) – Continue processing when IO errors are encounteredfuse_func (
Optional
[Callable
[[ndarray
,ndarray
],ndarray
]]) –Provide custom function for fusing pixels from different sources into one pixel plane.
The default behaviour is to use first observed valid pixel. Item timestamp is used to determine order,
nodata
is used to determine “valid”.kw – Any other named parameter is passed on to
datacube.Datacube.load()
- Return type
Dataset
- Returns
xarray.Dataset
with requested bands populated
Complete Example Code
import planetary_computer as pc from pystac_client import Client from odc import stac catalog = Client.open("https://planetarycomputer.microsoft.com/api/stac/v1") query = catalog.search( collections=["sentinel-2-l2a"], datetime="2019-06-06", query={"s2:mgrs_tile": dict(eq="06VVN")}, ) xx = stac.load( query.get_items(), bands=["red", "green", "blue"], crs="EPSG:32606", resolution=100, patch_url=pc.sign, ) xx.red.plot.imshow(col="time", size=8, aspect=1)
Example Configuration
Sample
stac_cfg={..}
parameter.sentinel-2-l2a: # < name of the collection, i.e. ``.collection_id`` assets: "*": # Band named "*" contains band info for "most" bands data_type: uint16 nodata: 0 unit: "1" SCL: # Those bands that are different than "most" data_type: uint8 nodata: 0 unit: "1" aliases: #< unique alias -> canonical map rededge: B05 rededge1: B05 rededge2: B06 rededge3: B07 warnings: ignore # ignore|all (default all) some-other-collection: assets: #... "*": # Applies to all collections if not defined on a collection warnings: ignore
See also
STAC item interpretationstac2ds()
Data loading:datacube.Datacube.load()