Skip to content
Ahmad Ammar

2. Finding and reading an image

2.1 Find an image: catalogues and STAC

Satellite archives are described by STAC (SpatioTemporal Asset Catalog) catalogues. Each item is one image (one place, one time) and lists its assets, the files for each band. We search the Sentinel-2 Level-2A collection (surface reflectance, corrected for the atmosphere) for summer 2025 over Belfast, keep images with under 10% cloud, and take the clearest.

In [2]
BBOX = [-6.05, 54.55, -5.85, 54.65]                 # west, south, east, north in degrees (WGS84)
catalog = pystac_client.Client.open("https://planetarycomputer.microsoft.com/api/stac/v1", modifier=planetary_computer.sign_inplace)
search = catalog.search(collections=["sentinel-2-l2a"], bbox=BBOX, datetime="2025-05-01/2025-08-31", query={"eo:cloud_cover": {"lt": 10}})
items = sorted(search.items(), key=lambda i: i.properties["eo:cloud_cover"])
item = items[0]
print(f"{len(items)} images found; using {item.id}")
print("date:", item.properties["datetime"][:10], "| cloud cover:", round(item.properties["eo:cloud_cover"], 3), "%",
      "| tile:", item.properties["s2:mgrs_tile"], "| processing baseline:", item.properties["s2:processing_baseline"])
print("bands available:", ", ".join(k for k in item.assets if k.startswith("B")))
Out [2]
10 images found; using S2B_MSIL2A_20250713T114349_R123_T30UUF_20250713T134456
date: 2025-07-13 | cloud cover: 0.003 % | tile: 30UUF | processing baseline: 05.11
bands available: B01, B02, B03, B04, B05, B06, B07, B08, B09, B11, B12, B8A

2.2 Read the bands for our area

A raster is a grid of numbers (one grid per band) plus the information that places it on the Earth: the coordinate reference system (CRS) and the transform (the coordinates of the top-left corner and the pixel size). Sentinel-2 files are Cloud-Optimised GeoTIFFs, so we can read just the window covering our area instead of the whole 110 km tile. Bands come at 10 m (blue B02, green B03, red B04, near-infrared B08) and 20 m (shortwave infrared B11); we read B11 onto the 10 m grid.

The files store whole numbers (digital numbers, DN). Reflectance, the share of sunlight the surface reflects (0 to 1), is DN / 10000 for older images. Since processing baseline 04.00 (January 2022), an offset of 1000 was added, so reflectance = (DN − 1000) / 10000. Forgetting this skews every index computed from the bands.

In [3]
BANDS = {"B02": "blue", "B03": "green", "B04": "red", "B08": "nir", "B11": "swir"}
with rasterio.open(item.assets["B04"].href) as ref:
    crs = ref.crs
    bounds = transform_bounds("EPSG:4326", crs, *BBOX)
    win = from_bounds(*bounds, transform=ref.transform).round_offsets().round_lengths()
    transform = ref.window_transform(win)
    shape = (int(win.height), int(win.width))
offset = 1000 if float(item.properties["s2:processing_baseline"]) >= 4.0 else 0
img = {}
for b, name in BANDS.items():
    with rasterio.open(item.assets[b].href) as src:
        w = from_bounds(*bounds, transform=src.transform)
        dn = src.read(1, window=w, out_shape=shape, resampling=rasterio.enums.Resampling.bilinear).astype("float32")
    img[name] = np.where(dn == 0, np.nan, (dn - offset) / 10000)          # 0 means no data
print("CRS:", crs, "| pixel size:", transform.a, "m | rows x columns:", shape, f"| area {shape[0] * shape[1] / 1e4:.0f} km²")
for name, a in img.items():
    print(f"{name:6s} reflectance: median {np.nanmedian(a):.3f}, 2nd-98th percentile {np.nanpercentile(a, 2):.3f} to {np.nanpercentile(a, 98):.3f}")
Out [3]
CRS: EPSG:32630 | pixel size: 10.0 m | rows x columns: (1166, 1338) | area 156 km²
blue   reflectance: median 0.041, 2nd-98th percentile 0.015 to 0.157
green  reflectance: median 0.062, 2nd-98th percentile 0.029 to 0.174
red    reflectance: median 0.050, 2nd-98th percentile 0.014 to 0.190
nir    reflectance: median 0.256, 2nd-98th percentile 0.014 to 0.509
swir   reflectance: median 0.174, 2nd-98th percentile 0.009 to 0.290