---

Initial Example

---

Short description

This notebook introduces the SpaceSense library. In this notebook, you will search and download a Sentinel-2 image.

---

0 - Install Spacesense Client Library and dependencies

Please follow the installation process and use the virtual environment in this notebook.

1 - Import spacesense object(s) and other dependencies

from spacesense import Client
import matplotlib.pyplot as plt
import numpy as np
import json

2 - Configure the API Key by setting the SS_API_KEY environment variable

import os
if "SS_API_KEY" not in os.environ:
    from getpass import getpass
    api_key = getpass('Enter your api key : ')
    os.environ["SS_API_KEY"] = api_key

3 - Define the area of interest (AOI), time of interest (TOI), output options

AOIs can be read in directly as geojson files using the json library, or can be defined directly in the code.

You can download the Mont Blanc geojson here

# Define the area of interest (AOI)
with open("../resources/aois/mont_blanc.geojson", mode="r") as file:
    aoi = json.load(file)

# Define the time range of interest (TOI)
start_date = "2022-07-13"
end_date = "2022-07-14"

# Get an instance of the SpaceSense Client object
client = Client(id="s2_intro_example")

# Enable to save data in local files
client.enable_local_output()

4 - Search S2

# Call the S2 search function, passing the AOI, and TOI
res_S2 = client.s2_search(aoi=aoi, start_date=start_date, end_date=end_date)
# Visualize the Pandas dataframe with the results
res_S2.dataframe

	id	date	tile	valid_pixel_percentage	platform	relative_orbit_number	product_id	datetime	swath_coverage_percentage	no_data	cloud_shadows	vegetation	not_vegetated	water	cloud_medium_probability	cloud_high_probability	thin_cirrus	snow
0	S2A_31TGL_20220713_0_L2A	2022-07-13	31TGL	69.68	sentinel-2a	108	S2A_MSIL2A_20220713T103041_N0400_R108_T31TGL_2...	2022-07-13T10:38:34Z	99.0	0.0	0.23	2.50	53.55	0.86	0.05	0.09	0.0	29.25
1	S2A_32TLR_20220713_0_L2A	2022-07-13	32TLR	70.00	sentinel-2a	108	S2A_MSIL2A_20220713T103041_N0400_R108_T32TLR_2...	2022-07-13T10:38:31Z	100.0	0.0	0.41	2.49	53.51	0.82	0.10	0.16	0.0	29.33
2	S2A_31TGM_20220713_0_L2A	2022-07-13	31TGM	27.20	sentinel-2a	108	S2A_MSIL2A_20220713T103041_N0400_R108_T31TGM_2...	2022-07-13T10:38:19Z	31.0	0.0	0.00	6.59	70.43	0.73	0.00	0.00	0.0	12.26

Select just one S2 result

# Filter the S2 search result to only those that have a 100% swath coverage - Only one result in this case
res_S2.dataframe = res_S2.dataframe[res_S2.dataframe.swath_coverage_percentage == 100]
# Visualize the Pandas dataframe with the results
res_S2.dataframe

	id	date	tile	valid_pixel_percentage	platform	relative_orbit_number	product_id	datetime	swath_coverage_percentage	no_data	cloud_shadows	vegetation	not_vegetated	water	cloud_medium_probability	cloud_high_probability	thin_cirrus	snow
1	S2A_32TLR_20220713_0_L2A	2022-07-13	32TLR	70.0	sentinel-2a	108	S2A_MSIL2A_20220713T103041_N0400_R108_T32TLR_2...	2022-07-13T10:38:31Z	100.0	0.0	0.41	2.49	53.51	0.82	0.1	0.16	0.0	29.33

5 - Select only certain bands of S2

# Select only the Blue, Green, and Red bands of S2
# Selecting individual bands fuses ONLY those bands into
# the fused result, in the specified order.
res_S2.output_bands = ["B02", "B03", "B04"]

6 - Obtain S2 image (Fuse)

The result of the fusion is an Xarray Dataset. This dataset is simply a 3-dimensional array, with the dimensions of time, y (latitude), and x (longitude).

The data we are interested in, the reflectance values of the selected bands, is found in the Data Variables. This data can be selected, enhanced, and manipulated using any Xarray Dataset methods.

# Call the core fusion function, passing our filtered S2 result
# This function obtains the result we selected in step 4, with the band selection
# specified in step 5
fusion = client.fuse([res_S2])
# Visualize the Pandas dataframe with the results
fusion.dataset

2022-11-28 08:22:35,682 INFO spacesense.core : created everything

<xarray.Dataset>
Dimensions:  (time: 1, y: 624, x: 949)
Coordinates:
  * time     (time) datetime64[ns] 2022-07-13
  * y        (y) float32 45.91 45.91 45.91 45.91 ... 45.86 45.86 45.86 45.86
  * x        (x) float64 6.907 6.907 6.907 6.908 ... 6.992 6.992 6.992 6.992
Data variables:
    S2_B02   (time, y, x) float32 0.0 0.0 0.0 0.0 ... 0.1596 0.1596 0.146 0.1048
    S2_B03   (time, y, x) float32 0.0 0.0 0.0 0.0 ... 0.188 0.188 0.175 0.1228
    S2_B04   (time, y, x) float32 0.0 0.0 0.0 0.0 ... 0.1914 0.1758 0.1232
Attributes:
    crs:              +init=epsg:4326
    transform:        [ 8.98360017e-05  0.00000000e+00  6.90722067e+00  0.000...
    res:              [8.98360017e-05 9.04414549e-05]
    ulx, uly:         [ 6.90722067 45.9145943 ]
    s2_data_lineage:  {"Data origin": "S3 bucket (ARN=arn:aws:s3:::sentinel-c...

xarray.Dataset

• Dimensions:
  • time: 1
  • y: 624
  • x: 949
• Coordinates: (3)
  • time
    (time)
    datetime64[ns]
    2022-07-13

    array(['2022-07-13T00:00:00.000000000'], dtype='datetime64[ns]')

  • y
    (y)
    float32
    45.91 45.91 45.91 ... 45.86 45.86

    _FillValue :

    nan

    array([45.91455 , 45.91446 , 45.914368, ..., 45.858383, 45.858295, 45.858204],
          dtype=float32)

  • x
    (x)
    float64
    6.907 6.907 6.907 ... 6.992 6.992

    _FillValue :

    nan

    array([6.907266, 6.907355, 6.907445, ..., 6.99225 , 6.99234 , 6.99243 ])

• Data variables: (3)
  • S2_B02
    (time, y, x)
    float32
    0.0 0.0 0.0 ... 0.1596 0.146 0.1048

    _FillValue :

    nan

    transform :

    [ 8.98360017e-05 0.00000000e+00 6.90722067e+00 0.00000000e+00 -9.04414549e-05 4.59145943e+01]

    crs :

    +init=epsg:4326

    descriptions :

    S2_B02

    AREA_OR_POINT :

    Area

    color_description :

    BLUE

    band_wavelength :

    490 nm

    scene_id :

    {"2022-07-13": "S2A_32TLR_20220713_0_L2A"}

    scene_classification :

    {'2022-07-13': '{"no_data": 0.0, "cloud_shadows": 0.41, "cloud_high_probability": 0.16, "vegetation": 2.49, "water": 0.82, "not_vegetated": 53.51, "unclassified": 0.01, "cloud_medium_probability": 0.1, "snow": 29.33, "saturated_or_defective": 0.0, "thin_cirrus": 0.0, "dark_area_pixels": 13.17}'}

    array([[[0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
            [0.    , 0.1612, 0.1618, ..., 0.1472, 0.1412, 0.    ],
            [0.    , 0.1632, 0.1632, ..., 0.1436, 0.1266, 0.    ],
            ...,
            [0.    , 0.    , 0.5968, ..., 0.185 , 0.185 , 0.1654],
            [0.    , 0.    , 0.5944, ..., 0.1842, 0.169 , 0.144 ],
            [0.    , 0.    , 0.5772, ..., 0.1596, 0.146 , 0.1048]]],
          dtype=float32)

  • S2_B03
    (time, y, x)
    float32
    0.0 0.0 0.0 ... 0.188 0.175 0.1228

    _FillValue :

    nan

    transform :

    [ 8.98360017e-05 0.00000000e+00 6.90722067e+00 0.00000000e+00 -9.04414549e-05 4.59145943e+01]

    crs :

    +init=epsg:4326

    descriptions :

    S2_B03

    AREA_OR_POINT :

    Area

    color_description :

    GREEN

    band_wavelength :

    560 nm

    scene_id :

    {"2022-07-13": "S2A_32TLR_20220713_0_L2A"}

    scene_classification :

    {'2022-07-13': '{"no_data": 0.0, "cloud_shadows": 0.41, "cloud_high_probability": 0.16, "vegetation": 2.49, "water": 0.82, "not_vegetated": 53.51, "unclassified": 0.01, "cloud_medium_probability": 0.1, "snow": 29.33, "saturated_or_defective": 0.0, "thin_cirrus": 0.0, "dark_area_pixels": 13.17}'}

    array([[[0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
            [0.    , 0.189 , 0.1966, ..., 0.1748, 0.167 , 0.    ],
            [0.    , 0.1934, 0.1934, ..., 0.1656, 0.1494, 0.    ],
            ...,
            [0.    , 0.    , 0.674 , ..., 0.2194, 0.2194, 0.198 ],
            [0.    , 0.    , 0.6744, ..., 0.2116, 0.203 , 0.17  ],
            [0.    , 0.    , 0.66  , ..., 0.188 , 0.175 , 0.1228]]],
          dtype=float32)

  • S2_B04
    (time, y, x)
    float32
    0.0 0.0 0.0 ... 0.1758 0.1232

    _FillValue :

    nan

    transform :

    [ 8.98360017e-05 0.00000000e+00 6.90722067e+00 0.00000000e+00 -9.04414549e-05 4.59145943e+01]

    crs :

    +init=epsg:4326

    descriptions :

    S2_B04

    AREA_OR_POINT :

    Area

    color_description :

    RED

    band_wavelength :

    665 nm

    scene_id :

    {"2022-07-13": "S2A_32TLR_20220713_0_L2A"}

    scene_classification :

    {'2022-07-13': '{"no_data": 0.0, "cloud_shadows": 0.41, "cloud_high_probability": 0.16, "vegetation": 2.49, "water": 0.82, "not_vegetated": 53.51, "unclassified": 0.01, "cloud_medium_probability": 0.1, "snow": 29.33, "saturated_or_defective": 0.0, "thin_cirrus": 0.0, "dark_area_pixels": 13.17}'}

    array([[[0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
            [0.    , 0.2014, 0.2008, ..., 0.1802, 0.1698, 0.    ],
            [0.    , 0.2014, 0.2014, ..., 0.165 , 0.151 , 0.    ],
            ...,
            [0.    , 0.    , 0.728 , ..., 0.2328, 0.2328, 0.2008],
            [0.    , 0.    , 0.728 , ..., 0.2226, 0.2142, 0.1742],
            [0.    , 0.    , 0.7192, ..., 0.1914, 0.1758, 0.1232]]],
          dtype=float32)

• Attributes: (5)

  crs :

  +init=epsg:4326

  transform :

  [ 8.98360017e-05 0.00000000e+00 6.90722067e+00 0.00000000e+00 -9.04414549e-05 4.59145943e+01]

  res :

  [8.98360017e-05 9.04414549e-05]

  ulx, uly :

  [ 6.90722067 45.9145943 ]

  s2_data_lineage :

  {"Data origin": "S3 bucket (ARN=arn:aws:s3:::sentinel-cogs-inventory)"}

7 - Visualize

# Function to detect and plot RGB images from the fused result
rgb = fusion.plot_rgb(brightness_factor=2, all_dates=False)

2022-11-28 08:22:52,800 WARNING matplotlib.image : Clipping input data to the valid range for imshow with RGB data ([0..1] for floats or [0..255] for integers).