# Surface Reflectance¶

We developed a general Descartes Labs Surface Reflectance algorithm (DLSR for short) that applies to any optical satellite imagery. This generic atmospheric correction makes it easier to fuse images from multiple sources and over time.

Initially, we are offering surface reflectance versions of all Landsat 8 and Sentinel-2 imagery that we ingest.

## Viewer¶

You can explore the differences between top-of-atmosphere (TOA) and surface reflectance imagery in Descartes Labs Viewer. When creating or editing a layer select a processing level (TOA or Surface) if it applies to the product. Follow this Viewer link for preconfigured layers that compare Landsat 8 and Sentinel-2 imagery.

This is a side-by-side comparison of these layers:

The DLSR layers appear to be less “hazy” compared to the TOA ones - the impact of the atmosphere between the satellite and the earth has been reduced.

You can toggle the visibility of the different levels with the eye icon to the left of a layer name or you can cycle through layers by using the keyboard keys “j” and “k”.

## Code Example¶

Define an area of interest (AOI):

In [1]: aoi = {
...:     "type": "Polygon",
...:     "coordinates": [[
...:         [-107.33367919921875, 31.977793589351563], [-105.216064453125, 31.977793589351563],
...:         [-105.216064453125, 33.80882018730745], [-107.33367919921875, 33.80882018730745],
...:         [-107.33367919921875, 31.977793589351563]
...:      ]]
...: }
...:


Search for Landsat 8 and Sentinel-2 scenes within it:

In [2]: import descarteslabs as dl

In [3]: scenes, context = dl.scenes.search(
...:     aoi,
...:     products=["landsat:LC08:01:RT:TOAR", "sentinel-2:L1C"],
...:     start_datetime="2018-06-18",
...:     end_datetime="2018-06-21",
...:     query=dl.properties.confidence_dlsr > 0.0,
...: )
...:

In [4]: scenes
Out[4]:
SceneCollection of 11 scenes
* Dates: Jun 18, 2018 to Jun 20, 2018
* Products: sentinel-2:L1C: 8, landsat:LC08:01:RT:TOAR: 3


Note that we are looking only for scenes with a confidence_dlsr property greater than 0. This excludes scenes for which surface reflectance version is not available.

A small number of scenes are not available because of missing auxiliary data used as input into the algorithm. Additionally, recent scenes may not yet be available. After a new scene is ingested into the platform, it may take up to two days until a surface reflectance version has been computed. For these reasons, we recommend to always filter by confidence_dlsr when working with surface reflectance.

Now we visualize a mosaic for each of the two products at top of atmosphere (TOA) and surface reflectance, by using the processing_level argument:

In [5]: context_120m = context.assign(resolution=120)

In [6]: mosaics, mosaic_titles = [], []

In [7]: for product, product_scenes in scenes.groupby("properties.product"):
...:     toa = product_scenes.mosaic(
...:         "red green blue",
...:         context_120m,
...:     )
...:     dlsr = product_scenes.mosaic(
...:         "red green blue",
...:         context_120m,
...:         processing_level="surface",
...:     )
...:     mosaics += [toa, dlsr]
...:     mosaic_titles += ["{} TOA".format(product), "{} Surface".format(product)]
...:

In [8]: dl.scenes.display(*mosaics, title=mosaic_titles, size=5)


The unique geographical feature in the center of these images is White Sands, a gypsum desert in New Mexico. Explore the same area for this timespan in Viewer here.

This example code uses the descarteslabs.scenes API. The lower-level raster and metadata APIs have equivalent surface reflectance support. Anytime you search for scenes (e.g., Metadata.search()) you can filter by confidence_dlsr, and anytime you raster or download image data (e.g., Raster.ndarray()) you can pass a processing_level="surface" argument.

## Applicable Products¶

As of now surface reflectance is available for the following products:

Landsat 8 (NASA)
landsat:LC08:01:RT:TOAR (Real Time Collection 1)
landsat:LC08:01:T1:TOAR (Tier 1 Collection)
landsat:LC08:01:T2:TOAR (Tier 2 Collection)
landsat:LC08:PRE:TOAR (pre-Collection)
Sentinel-2 (ESA)
sentinel-2:L1C (Sentinel-2 L1C)

For newly ingested scenes, the DLSR version can be delayed up to two days after the initial ingestion of the scene into the platform.

DLSR is available for all native spectral bands in these products, except for cirrus bands.