Harmonized Landsat Sentinel Service

The Harmonized Landsat-Sentinel Service API produces high-resolution imagery and NDVI data for a desired area-of-interest. From NASA, the Harmonized Landsat-Sentinel-2 project is an initiative to produce a consistent, harmonized surface reflectance product from Landsat and Sentinel-2 data.

a) HLS Service

The Ag-Analytics® Harmonized Landsat-Sentinel Service (HLS) API provides the service in which a user can provide an area-of-interest (AOI) with additional customized options to retrieve the dynamics of their land at various times from the Landsat-8 and Sentinel-2 satellites. This service provides information on cloud cover, statistics, and Normalized Difference Vegetation Index in addition to MSI bands information.

The Harmonized Landsat-Sentinel (HLS) Project is a NASA initiative to produce a Virtual Constellation (VC) of surface reflectance (SR) data from the Operational Land Imager (OLI) and MultiSpectral Instrument (MSI) onboard the Landsat-8 and Sentinel-2 remote sensing satellites, respectively. The data from these satellites creates unprecedented opportunities for timely and accurate observation of Earth status and dynamics at moderate (<30 m) spatial resolution every 2-3 days.



Harmonized Landsat Sentinel Data in Ag-Analytics DataLayers.

Documentation

Github Repo

Notebook

General Flow of Service

When a user passes an area-of-interest (AOI) in the form of a shapefile, json, raster .tif, or geojson, the service finds the correct satellite imagery and clips each image to the AOI given. The service has the options to interpolate the result and to specify the imagery weeks that are returned.


General Algorithm Flow
  1. Determine the AOI polygon given.

**When the interpolation option is chosen, the AOI will be a larger area (determined by the interpolation parameters) of the given field boundary. Otherwise, the AOI will be a rectangle polygon around the given AOI.

  1. Identify the corresponding satellite imageries based on the AOI, acquisition date, interpolation parameters, and other options passed by users.
  2. The satellite imageries will then be clipped to the AOI. If the imageries from the same date overlay with each other on the AOI, the mean of the overlay area will be returned and merged with the area without overlay from each imagery.
  3. The imageries of the AOI will then be mosaiced to get weekly average imageries.
  4. (**) If the interpolation option is chosen, the selected interpolation method and parameters will be applied to each weekly imagery where has cloud cover.

(**when interpolation is chosen)


Interpolation Function

Due to cloud cover, the original satellite images may have many gaps and can not fully cover the area-of-interest (AOI). The interest to solve this problem arose in 2003, and there have been many papers and methods developed for this problem since then. After comparing and testing multiple methods and algorithms that have been used in dealing with the missing data on remote sensing satellite images, we adopted a customized "inpainting" method - which means filling gaps in an image by extrapolating the existing parts of the image in our API service.

To take the spatial and temporal correlation of the images into consideration, our customized inpainting algorithm "inpaints" a sequence of images with cloud covered for the given AOI. Each missing part (multiple pixels) at a certain location is inpainted by linear transformation of the intensity of pixels at the same location of other images where the data of these pixels are available.


Interpolation Algorithm Flow
  1. Identify the missing parts of the image and find the contours of each gap.
  2. Find the best candidates from similar sequences of images which have non-missing pixels to fill the largest part of a given gap.
  3. Define an outline – a thin curve around each gap, then used for obtaining the linear transformation of the pixel intensity between the two images for each of the best candidates. The candidate image with the best linear fit of the outline is chosen.
  4. To better-fit the area close to the outline, an intensity correction mask is then created by blurring the patch-intensity difference image.
  5. The mask is applied to the gap area on the best candidate and generates an inpainted patch.
  6. Finally, this inpainted patch is used to fill the gap in the image.

Request Parameters

Parameter Data Type Required? Default Options Description
AOI Geometry, file/text Yes -- JSON, GEOJSON, Shapefile, Raster See Fig. 2 for further explanation.
Band List Yes -- See "Band" Parameter Options Table Provide the list of HLS Spectral band names to retrieve for given AOI. See Figures 3-4.
Startdate Date No -- mm/dd/yyyy • Landsat – data starts from 2013
• Sentinel – data starts from 2015
Enddate Date No -- mm/dd/yyyy In the absence of startdate or enddate, or both, the service retrieves the latest information available on the land.
byweek Int, boolean No 1 1, 0 If set to 1, result raster will be the mosaic of all the tiles in a particular week for a given satellite
satellite text No Landsat Landsat, Sentinel If set to both Landsat, Sentinel then the result raster will be the mosaic of both satellites for the given dates
showlatest Int, boolean No 1 -- If startdate or enddate is not given, shows the latest available tile.
filter Int, boolean No 0 0, 1 If set to 1, returns the response which is cloud-free after mosaic.
qafilter Int, boolean No 0 0, 1 If set to 1, continues to filter tiles until the invalid pixels are < qacloudperc
qacloudperc float No 100 0-100 This parameter comes to action with qafilter. If qafilter parameter is 1, then filters the tiles until the invalid pixels in those are < qacloudperc
displaynormalvalues float No 2000 -- This parameter is used to normalize the band values for display purposes. Used for bands like RGB, AGR, etc.
legendtype text No Relative Relative, Absolute Legend type of display ranges of resulting response.
resolution float No 0.0001 -- Cellsize in meters.
flatten_data Int, boolean No 0 0, 1 Flatten data which has a list of Xcoord, Ycoord and Values for each band in the output. If 1, flatten_data is returned.
statistics Int, boolean No 1 0, 1 Returns statistical features of the output .tif file.
return_tif int No 1 0, 1 Returns the downloadable link to output raster. If 0, link will not be returned.
projection text No Projection of AOI Given See Figure 5 Enter the desired projection for the result raster. See Figure 5 for details.

Band Information

API Variable Band Definition Description
Red Red (0.64-0.67µm) Reflects reds, such as tropical soils or rust-like soils.
Green Green (0.53-0.59µm) Reflects greens, particularly leaf surfaces.
Blue Blue (0.45-0.51µm) Reflects blues, particularly helpful for deep waters.
NIR Near Infrared (0.76-0.90µm) Reflects healthy vegetation.
NIR_Broad Near Infrared (.842 µm central) Good for mapping shorelines and biomass content, as well as at detecting
and analyzing vegetation.
Red_Edge_1 Red Edge (.69 - .71µm) Can gauge foliage chlorophyll, canopy area, and water content.
Applications include growth studies, precision ag, and vegetation productivity modeling.
Red_Edge_2 Red Edge (0.73 – 0.75 µm) Can gauge foliage chlorophyll, canopy area, and water content
Red_edge_3 Red Edge (0.77 – 0.79 µm) Can gauge foliage chlorophyll, canopy area, and water content
SWIR1 Short-wave Infrared (1.57-1.65µm) Sensitive to moisture content. Assists in distinguishing between dry and wet
soils and vegetation.
SWIR2 Short-wave Infrared 2 (2.08-2.35µm) Used in imaging soil types, geological features, and minerals. Sensitive to vegetation
and soil moisture variations.
Coastal Aerosol Coastal Aerosol (0.43-0.45µm) Reflects blues and violets.
QA Quality Assessment Provides useful information for optimizing the value of pixels, identifying
which pixels may be affected by surface conditions, clouds, or sensor conditions.

Index Information

Index Name API Variable Formula Description

Normalized Difference
Vegetation Index (NDVI)
NDVI
NDVI = (NIR - Red) /
(NIR + Red)
NDVI is derived from readily available satellite imagery which is positively
correlated with green vegetation cover

Red-Green-Blue
(RGB)
RGB
Composite of red, green,
and blue bands.
Color imagery, how the human eye would view something.

Normalized Difference
Water Index (NDWI)
NDWI
NDWI = (NIR - SWIR) /
(NIR + SWIR)
NDWI uses the NIR and SWIR bands to determine changes in water content

Normalized Difference
Buildup Index (NDBI)
NDBI
NDBI = (SWIR1 - NIR) /
(SWIR1 + NIR)
NDBI uses SWIR1 and NIR bands to determine urban areas

Normalized Difference
Tillage Index (NDTI)
NDTI
NDTI = (SWIR1 - SWIR2) /
(SWIR1 + SWIR2)
Similarly, NDTI is also derived from satellite imagery but calculated with
different bands. It is positively correlated with crop residue cover

Urban Index (UI)
UI
UI = (SWIR2 - NIR) /
(SWIR2 + NIR)
UI uses SWIR2 and NIR bands to determine urban density

Green Chlorophyll
Vegetation Index (GCVI)
GCVI
GCVI = (NIR/GREEN) − 1
Used to estimate the content of leaf chlorophyll in various species of plants

MERIS-based Terrestrial
Chlorophyll Index (MTCI)
MTCI
MTCI = (NIR_Broad - Red_Edge_1) /
( NIR_Broad + Red )
MTCI can be used to gauge chlorophyll content.

Normalized Difference
Red Edge (NDRE)
NDRE
NDRE = (NIR – Red_Edge_1) /
(NIR + Red_Edge_1)
NDRE uses NIR and red edge bands to gauge late season plant health.
Calculated using Red_Edge_1 based on wavelength used for NDRE
calculation in this paper (Carisse et al 2010).

Band Insertion Into RGB

Features can be isolated to stand out by loading different combinations of bands into the red, green, and blue channels. Read more here.

Combo Name API Variable Formula (R-G-B) Description
Traditional Color Infrared Image (CIR) CIR NIR - Red - Green Combination of colors within the visible spectrum with addition
of NIR light; useful for determining pigments in vegetation.
Urban Environment (UE) UE SWIR2 - SWIR1 - Red False Color useful for visualizing urban environments.
Land and Water (LW) LW NIR - SWIR1 - Red False Color good for picking out land from water.
Atmospheric Penetration (AP) AP SWIR2 - NIR - Green False color image with good atmospheric penetration.
Agriculture (AGR) AGR SWIR1 - NIR - Blue False color for visualizing agricultural activity.
Forest Fire Burn Scars (FFBS) FFBS SWIR2 - NIR - Blue False color often used for visualizing forest fire burn scars
Bare Earth (BE) BE SWIR1 - Green - Blue False color for distinguishing differences in bare earth.
Vegetation and Water (VW) VW NIR - SWIR2 - Coastal Aerosol False color for visualizing vegetation and water.

Response Parameters

Parameter Data Type Description
download_url URL URL to download result raster (.tif) file
flattendtext -- An array of Xcoords, Ycoords values from the .tif files.
tiledate Date (mm/dd/yyyy) The tile dates from where the band values are retrieved.
tilenames -- List of the Blob names from the Azure Storage Container.
features -- An array of features from the database.
features.attributes.CellSize Resolution Resolution of result Geotiff file in meters.
features.attributes.CoordinateSystem -- Coordinate system of the result raster.
features.attributes.Extent -- Extents of the result raster.
features.attributes.Legend List Legend gives ranges of values for: Area: Area covered in % Count : # of pixels from the result raster in range CountAllPixels : Total # of pixels in result Max : Maximum value in range Min : Minimum value in range Mean : Mean value in range Color : Hex color used for value ranges
features.attributes.Matrix List Rows and Columns.
features.attributes.Max Number Maximum value from the result raster
features.attributes.Min Number Minimum value from the result raster
features.attributes.Mean Number Average value from the result raster
features.attributes.Percentile5 Number 5th percentile value from result raster
features.attributes.Percentile95 Number 95th percentile value from result raster
features.attributes.pngb64 URL base64png image of the result raster with legend entries

Figure 1.

Acronyms and Definitions

Acronym Description
MSI Multi-Spectral Instrument
HLS Harmonized Landsat and Sentinel-2
HDF Hierarchical Data Format
NIR Near-Infrared
GLS Global Land Survey
BRDF Bidirectional Reflectance Distribution Function
NBAR Nadir BRDF-normalized Reflectance
OLI Operational Land Imager
QA Quality assessment
SWIR Short-wave Infrared
SDS Scientific Data Sets
SR Surface reflectance
SZA Sun Zenith angle
NDVI Normalized Difference Vegetation Index
UTM Universal Transverse Mercator
WRS Worldwide Reference System

Figure 2.

AOI Structure Examples

JSON Example

{"geometryType":"esriGeometryPolygon","features":[{"geometry":{"rings":[[[-92.678953,41.741707],[-
92.678966,41.740563],[-92.678972,41.739963],[-92.67896,41.738874],[-92.686062,41.738873],[-92.688546,41.738868],[-92.688544,41.739223],[-92.688555,41.743961],[-92.688124,41.743969],[-92.686658,41.744045],[-92.685481,41.74411],[-92.68513,41.744086],[-92.684627,41.743993],[-92.684352,41.743833],[-92.683972,41.743603],[-92.683789,41.743476],[-92.683333,41.742983],[-92.682923,41.742627],[-92.682497,41.742283],[-92.68213,41.742294],[-92.681444,41.742131],[-92.680101,41.741842],[-92.679444,41.741817],[-92.679094,41.741713],[-92.678953,41.741707]]],"spatialReference":{"wkid":4326}}}]}

GEOJSON Example
{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-93.998809,41.993243],[-93.99873,41.988358],[94.001444,41.98838],[-94.00144,41.989089],[-94.003556,41.989116],[-94.003571,41.991767],[94.002054,41.991735],[-94.002086,41.993278],[-93.998809,41.993243]]]},"properties":{"OBJECTID":2038888,"CALCACRES":44.63000107,"CALCACRES2":null} ,"id":2038888}

Shapefile Example

A Zip folder with following files [example.shp, example.prj, example.dbf, example.shx]

Raster Example

A GeoTiff file of ‘.tif’ extension


Figure 3.

Bands Information and Request Syntax

Figure 3.

HLS spectral bands nomenclature

Band Name OLI Band Number MSI Band Number HLS Band Code Name L30 HLS Band Code Name S30 L30 Subdataset Number S30 Subdataset Number Wavelength (micrometers)
Coastal Aerosol 1 1 band01 B01 01 01 0.43 – 0.45*
Blue 2 2 band02 B02 02 02 0.45 – 0.51*
Green 3 3 band03 B03 03 03 0.53 – 0.59*
Red 4 4 band04 B04 04 04 0.64 – 0.67*
Red-Edge 1 -- 5 -- B05 -- 05 0.69 – 0.71**
Red-Edge 2 -- 6 -- B06 -- 06 0.73 – 0.75**
Red-Edge 3 -- 7 -- B07 -- 07 0.77 – 0.79**
NIR Broad -- 8 -- B08 -- 08 0.78 –0.88**
NIR Narrow 5 8A band05 B8A 05 09 0.85 – 0.88*
SWIR 1 6 11 band06 B11 06 12 1.57 – 1.65*
SWIR 2 7 12 band07 B12 07 13 2.11 – 2.29*
Water vapor -- 9 -- B09 -- 10 0.93 – 0.95**
Cirrus 9 10 band09 B10 08 11 1.36 – 1.38*
TIRS1 (Thermal Infrared 1) 10 -- band10 -- 09 -- 10.60 – 11.19*
TIRS2 (Thermal Infrared 2) 11 -- band11 -- 10 -- 11.50 – 12.51*
QA -- -- -- -- 11 14 --

Figure 4

Projection Syntax and Example

Projection Syntax

Projection: Projection of a new resampled raster. It may take the following forms:

  1. Well Known Text definition
  2. "EPSG:n"
  3. "EPSGA:n"
  4. "AUTO:proj_id,unit_id,lon0,lat0" - WMS auto projections
  5. "urn:ogc:def:crs:EPSG::n" - ogc urns
  6. PROJ.4 definitions
    1. 6.__well known name, such as NAD27, NAD83, WGS84 or WGS72
    2. 7.__"IGNF:xxxx", "ESRI:xxxx", etc. definitions from the PROJ database

Projection Example: "urn:ogc:def:crs:EPSG::n"


Figure 5

Request Examples – form-data and urlencoded

form-data
application/json
  { 
 Band: "['NDVI']" 
 Enddate: "3/8/2019" 
 Startdate: "3/2/2019" 
 aoi: "{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-93.511545,42.071053],[93.511565,42.074566],[-93.50667,42.074588],[-93.501908,42.074559],[-93.501936,42.071045],[-
93.511545,42.071053]]]},"properties":{"OBJECTID":3350330,"CALCACRES":77.09999847,"CALCACRES2":null},"id":3350330}" 
legendtype: "Relative" 
satellite: "Landsat" 
}
application/x-www-form-urlencoded
    aoi=%7B%22type%22%3A%22Feature%22%2C%22geometry%22%3A%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B-101.02684%2C38.598114%5D%2C%5B-101.026842%2C38.597962%5D%2C%5B-101.026956%2C38.59093%5D%2C%5B-101.028768%2C38.590943%5D%2C%5B-101.029234%2C38.590946%5D%2C%5B-101.035523%2C38.590991%5D%2C%5B-101.035526%2C38.590991%5D%2C%5B-101.035564%2C38.590991%5D%2C%5B-101.035576%2C38.590991%5D%2C%5B-101.035595%2C38.590991%5D%2C%5B-101.035956%2C38.590994%5D%2C%5B-101.035974%2C38.591099%5D%2C%5B-101.035957%2C38.594349%5D%2C%5B-101.036017%2C38.598193%5D%2C%5B-101.035203%2C38.598193%5D%2C%5B-101.033665%2C38.598182%5D%2C%5B-101.031726%2C38.598158%5D%2C%5B-101.02684%2C38.598114%5D%5D%5D%7D%2C%22properties%22%3A%7B%22OBJECTID%22%3A8091992%2C%22CALCACRES%22%3A156.1000061%2C%22CALCACRES2%22%3Anull%7D%2C%22id%22%3A8091992%7D&amp;satellite=Landsat%2CSentinel&amp;Band=%5B&#39;NDVI&#39;%5D&amp;filter=1&amp;interpolate=1&amp;showlatest=1&amp;resolution=0.0001&amp;statistics=1&amp;Startdate=9%2F26%2F2019&amp;Enddate=10%2F2%2F2019&amp;legendtype=Relative



Call API