Package: lsru
Interface to USGS and ESPA APIs for Landsat surface reflectance data
orderingOnline doc atlsru.readthedocs.ioBefore, downloading Landsat surface reflectance data for a given area
meant:Manually querying the sceneIDs on Earth ExplorerSaving these lists of sceneIDs to text filesManually uploading these files to ESPA to place the orderDownloading the processed data with a download managerNow, thanks toUSGS
API,
andespa APIit can all be
done programtically.ExampleSend a spatio-temporal query to the Usgs APIUsed to retrieve a list of available scenes metadatafromlsruimportUsgsimportdatetime# Define query extentbbox=(3.5,43.4,4,44)# Instantiate Usgs class and loginusgs=Usgs()usgs.login()# Query the Usgs api to find scene intersecting with the spatio-temporal windowscene_list=usgs.search(collection='LANDSAT_8_C1',bbox=bbox,begin=datetime.datetime(2013,1,1),end=datetime.datetime(2016,1,1),max_results=10,max_cloud_cover=40)# Extract Landsat scene ids for each hit from the metadatascene_list=[x['displayId']forxinscene_list]Place a processing order to EspaThe scene list can be used to send a processing order to Espa via the Espa API.
Many options are available (full scene, pixel resizing, reprojection, cropping).Order full scenesfromlsruimportEspafrompprintimportpprint# Instantiate Espa classespa=Espa()# Place order (full scenes, no reprojection, sr and pixel_qa)order=espa.order(scene_list=scene_list,products=['sr','pixel_qa'])print(order.orderid)# espa-loic.dutrieux@wur.nl-10212018-102816-245'Check current orders statusfororderinespa.orders:# Orders have their own class with attributes and methodsprint('%s:%s'%(order.orderid,order.status))# espa-loic.dutrieux@wur.nl-10222018-062836-330: ordered# espa-loic.dutrieux@wur.nl-10212018-174321-508: complete# espa-loic.dutrieux@wur.nl-10212018-174430-792: complete# espa-loic.dutrieux@wur.nl-10212018-102816-245: complete# espa-loic.dutrieux@wur.nl-10182018-100137-786: completeDownload completed orders. When Espa finishes pre-processing an order, its status
changes tocomplete, we can then download the processed scenes.fororderinespa.orders:iforder.is_complete:order.download_all_complete('/media/landsat/download/dir')It is also possible order processing with reprojection, cropping, resizing, etc# Inspect aea projection parameterspprint(espa.projections['aea'])# Define projection parametersproj_params={'aea':{'central_meridian':3.8,'datum':'wgs84','false_easting':0,'false_northing':0,'latitude_of_origin':43.7,'standard_parallel_1':43,'standard_parallel_2':44}}# Place orderorder_meta=espa.order(scene_list=scene_list,products=['sr','pixel_qa'],note='cropped order with resampling',projection=proj_params,extent=bbox,resolution=60)InstallationActivate a virtualenv (optional but preferable) and run:pipinstalllsruSetupThe package requires a configuration file in which usgs credentials are written.
By default the file is called~/.lsru(this can be modified if you want to join
this configuration with the configuration of another project) and has the following structure.[usgs]
username=your_usgs_username
password=your_very_secure_passwordWhy can’t I just retrieve my Landsat data from Earth Explorer, Amazon or Google cloud?You can but it will be top of atmosphere (TOA) radiance, not surface
reflectance. If you aim to have a scientific use of the data, you
probably want to have surface reflectance.The critical part between TOA radiance and surface reflectance is the
atmospheric correction. That means that surface reflectance data are
corrected for atmospheric effects, therefore providing accurate
measurements of the target’s spectral properties.Today (October 2016), there are a few ways to obtain Landsat surface
reflectance data (All of them have been processed by LEDAPS, the
reference high level Landsat processing tool):By ordering them via the ESPA systemthis is what this utility helps you to doESPA does on demand pre-processing of full (reprojected) scenes or
subsetsA cloud mask (fmask) and vegetation indices can also be added to the
orderBy ordering them from Google Earth EngineGEE has ingested the entire ESPA surface reflectance collection to
make it available via its platformBy downloading TOA data from any source and processing with a local
installation of LEDAPSNot necessarily trivial