Add quicklook to copernicus client

Author: lukasbindreiter

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `tilebox-storage`: Added `USGSLandsatStorageClient` to download landsat data from the USGS Landsat S3 bucket.
+- `tilebox-storage`: Storage client now support concurrent downloads of multiple objects, controlled by the
+  `max_concurrent_downloads` parameter.
+- `tilebox-storage`: Added `quicklook` and `download_quicklook` methods to the `CopernicusStorageClient` to download and
+  display preview images for Sentinel data.
+
 ## [0.41.0] - 2025-08-01
 
 ### Added

tilebox-storage/tests/storage_data.py

@@ -51,15 +51,14 @@ def alphanumerical_text(draw: DrawFn, min_size: int = 1, max_size: int = 100) ->
 @composite
 def umbra_granules(draw: DrawFn) -> UmbraStorageGranule:
     """Generate a realistic-looking random Umbra granule."""
-    level = "L0"
     time = draw(datetimes(min_value=datetime(1990, 1, 1), max_value=datetime(2025, 1, 1), timezones=just(None)))
     number = draw(integers(min_value=1, max_value=2))
     text_location = draw(alphanumerical_text(min_size=1, max_size=20))
     granule_id = str(draw(uuids(version=4)))
     granule_name = f"{time:%Y-%m-%d-%H-%M-%S}_UMBRA-{number:02d}"
     location = str(Path(text_location) / granule_id / granule_name)
 
-    return UmbraStorageGranule(time, granule_name, level, location)
+    return UmbraStorageGranule(time, granule_name, location)
 
 
 @composite
@@ -85,8 +84,7 @@ def s5p_granules(draw: DrawFn) -> CopernicusStorageGranule:
     # /eodata/Sentinel-5P/TROPOMI/L2__AER_LH/2024/04/15/S5P_NRTI_L2__AER_LH_20240415T055540_20240415T060040_33707_03_020600_20240415T063447
     location = f"/eodata/Sentinel-5P/{instrument}/{product_type}/{start:%Y}/{start:%m}/{start:%d}/{granule_name.removesuffix('.nc')}"
 
-    file_size = draw(integers(min_value=10_000, max_value=999_999_999))
-    return CopernicusStorageGranule(start, granule_name, location, file_size)
+    return CopernicusStorageGranule(start, granule_name, location)
 
 
 @composite

tilebox-storage/tests/test_granule.py

@@ -11,6 +11,7 @@
     UmbraStorageGranule,
     USGSLandsatStorageGranule,
     _asf_download_urls,
+    _thumbnail_relative_to_eodata_location,
 )
 
 
@@ -59,7 +60,6 @@ def _umbra_granule_to_datapoint(granule: UmbraStorageGranule) -> xr.Dataset:
     datapoint = xr.Dataset()
     datapoint.coords["time"] = np.array(granule.time).astype("datetime64[ns]")
     datapoint["granule_name"] = granule.granule_name
-    datapoint["processing_level"] = granule.processing_level
     datapoint["location"] = granule.location
     return datapoint
 
@@ -82,12 +82,51 @@ def test_granule_from_umbra_datapoints(granules: list[UmbraStorageGranule]) -> N
         assert UmbraStorageGranule.from_data(dataset.isel(time=i)) == granules[i]
 
 
+@pytest.mark.parametrize(
+    ("thumbnail_url", "location", "expected"),
+    [
+        (
+            "https://catalogue.dataspace.copernicus.eu/get-object?path=/Sentinel-1/SAR/EW_GRDM_1S/2025/08/07/S1A_EW_GRDM_1SDH_20250807T111242_20250807T111346_060429_078305_DB6A.SAFE/preview/thumbnail.png",
+            "/eodata/Sentinel-1/SAR/EW_GRDM_1S/2025/08/07/S1A_EW_GRDM_1SDH_20250807T111242_20250807T111346_060429_078305_DB6A.SAFE",
+            "preview/thumbnail.png",
+        ),
+        (
+            "https://catalogue.dataspace.copernicus.eu/get-object?path=/Sentinel-2/MSI/L1C/2025/08/07/S2B_MSIL1C_20250807T004159_N0511_R045_T08XNR_20250807T004945.SAFE/S2B_MSIL1C_20250807T004159_N0511_R045_T08XNR_20250807T004945-ql.jpg",
+            "/eodata/Sentinel-2/MSI/L1C/2025/08/07/S2B_MSIL1C_20250807T004159_N0511_R045_T08XNR_20250807T004945.SAFE",
+            "S2B_MSIL1C_20250807T004159_N0511_R045_T08XNR_20250807T004945-ql.jpg",
+        ),
+        (
+            "https://catalogue.dataspace.copernicus.eu/get-object?path=/Sentinel-3/OLCI/OL_2_LFR___/2025/08/07/S3A_OL_2_LFR____20250807T011653_20250807T011953_20250807T033036_0179_129_074_1620_PS1_O_NR_003.SEN3/quicklook.jpg",
+            "/eodata/Sentinel-3/OLCI/OL_2_LFR___/2025/08/07/S3A_OL_2_LFR____20250807T011653_20250807T011953_20250807T033036_0179_129_074_1620_PS1_O_NR_003.SEN3",
+            "quicklook.jpg",
+        ),
+        (
+            "https://catalogue.dataspace.copernicus.eu/get-object?path=/Sentinel-3/SLSTR/SL_1_RBT___/2025/08/07/S3B_SL_1_RBT____20250807T002314_20250807T002614_20250807T025411_0179_109_316_0720_ESA_O_NR_004.SEN3/quicklook.jpg",
+            "/eodata/Sentinel-3/SLSTR/SL_1_RBT___/2025/08/07/S3B_SL_1_RBT____20250807T002314_20250807T002614_20250807T025411_0179_109_316_0720_ESA_O_NR_004.SEN3",
+            "quicklook.jpg",
+        ),
+        (
+            "https://catalogue.dataspace.copernicus.eu/get-object?path=/Sentinel-3/SYNERGY/SY_2_VG1___/2025/08/04/S3A_SY_2_VG1____20250804T000000_20250804T235959_20250806T202029_AUSTRALASIA_______PS1_O_NT_002.SEN3/quicklook.jpg",
+            "/eodata/Sentinel-3/SYNERGY/SY_2_VG1___/2025/08/04/S3A_SY_2_VG1____20250804T000000_20250804T235959_20250806T202029_AUSTRALASIA_______PS1_O_NT_002.SEN3",
+            "quicklook.jpg",
+        ),
+    ],
+)
+def test_thumbnail_relative_to_eodata_location(thumbnail_url: str, location: str, expected: str) -> None:
+    assert (
+        _thumbnail_relative_to_eodata_location(
+            thumbnail_url,
+            location,
+        )
+        == expected
+    )
+
+
 def _copernicus_granule_to_datapoint(granule: CopernicusStorageGranule) -> xr.Dataset:
     datapoint = xr.Dataset()
     datapoint.coords["time"] = np.array(granule.time).astype("datetime64[ns]")
     datapoint["granule_name"] = granule.granule_name
     datapoint["location"] = granule.location
-    datapoint["file_size"] = granule.file_size
     return datapoint
 
 

tilebox-storage/tilebox/storage/aio.py

@@ -595,7 +595,23 @@ async def list_objects(self, datapoint: xr.Dataset | CopernicusStorageGranule) -
 
         Returns:
             List of object keys available for the given datapoint, relative to the granule location."""
-        return await list_object_paths(self._store, _copernicus_s3_prefix(datapoint))
+        return await self._list_objects(datapoint)
+
+    async def _list_objects(self, datapoint: xr.Dataset | CopernicusStorageGranule) -> list[str]:
+        """List all available objects for a given datapoint.
+
+        Args:
+            datapoint: The datapoint to list available objects the data for.
+
+        Returns:
+            List of object keys available for the given datapoint, relative to the granule location."""
+
+        granule = CopernicusStorageGranule.from_data(datapoint)
+        # special handling for Sentinel-5P, where the location is not a folder but a single file
+        if granule.location.endswith(".nc"):
+            return [Path(granule.granule_name).name]
+
+        return await list_object_paths(self._store, _copernicus_s3_prefix(granule))
 
     async def download(
         self,
@@ -615,8 +631,10 @@ async def download(
         Returns:
             The path to the downloaded data directory.
         """
-        all_objects = await list_object_paths(self._store, _copernicus_s3_prefix(datapoint))
-        return await self._download_objects(datapoint, all_objects, output_dir, show_progress, max_concurrent_downloads)
+        granule = CopernicusStorageGranule.from_data(datapoint)
+
+        all_objects = await self._list_objects(granule)
+        return await self._download_objects(granule, all_objects, output_dir, show_progress, max_concurrent_downloads)
 
     async def download_objects(
         self,
@@ -652,7 +670,14 @@ async def _download_objects(
         show_progress: bool = True,
         max_concurrent_downloads: int = 4,
     ) -> Path:
-        prefix = _copernicus_s3_prefix(datapoint)
+        granule = CopernicusStorageGranule.from_data(datapoint)
+        prefix = _copernicus_s3_prefix(granule)
+        single_file = False
+
+        # special handling for Sentinel-5P, where the location is not a folder but a single file
+        if granule.location.endswith(".nc"):
+            single_file = True
+            prefix = str(Path(prefix).parent)
 
         base_folder = output_dir or self._cache
         if base_folder is None:
@@ -663,8 +688,61 @@ async def _download_objects(
             return output_folder
 
         await download_objects(self._store, prefix, objects, output_folder, show_progress, max_concurrent_downloads)
+        if single_file:
+            return output_folder / objects[0]
         return output_folder
 
+    async def download_quicklook(self, datapoint: xr.Dataset | CopernicusStorageGranule) -> Path:
+        """Download the quicklook image for a given datapoint.
+
+        Args:
+            datapoint: The datapoint to download the quicklook for.
+
+        Raises:
+            ValueError: If no quicklook is available for the given datapoint.
+
+        Returns:
+            The path to the downloaded quicklook image.
+        """
+        return await self._download_quicklook(datapoint)
+
+    async def quicklook(
+        self, datapoint: xr.Dataset | CopernicusStorageGranule, width: int = 600, height: int = 600
+    ) -> None:
+        """Display the quicklook image for a given datapoint.
+
+        Requires an IPython kernel to be running. If you are not using IPython, use download_quicklook instead.
+
+        Args:
+            datapoint: The datapoint to download the quicklook for.
+            width: Display width of the image in pixels. Defaults to 600.
+            height: Display height of the image in pixels. Defaults to 600.
+
+        Raises:
+            ImportError: In case IPython is not available.
+            ValueError: If no quicklook is available for the given datapoint.
+        """
+        if Image is None:
+            raise ImportError("IPython is not available, please use download_preview instead.")
+        granule = CopernicusStorageGranule.from_data(datapoint)
+        quicklook = await self._download_quicklook(granule)
+        _display_quicklook(quicklook, width, height, f"<code>{granule.granule_name} © ESA {granule.time.year}</code>")
+
+    async def _download_quicklook(self, datapoint: xr.Dataset | CopernicusStorageGranule) -> Path:
+        granule = CopernicusStorageGranule.from_data(datapoint)
+        if granule.thumbnail is None:
+            raise ValueError(f"No quicklook available for {granule.granule_name}")
+
+        prefix = _copernicus_s3_prefix(granule)
+        output_folder = (
+            self._cache / self._STORAGE_PROVIDER / Path(prefix)
+            if self._cache is not None
+            else Path.cwd() / self._STORAGE_PROVIDER
+        )
+
+        await download_objects(self._store, prefix, [granule.thumbnail], output_folder, show_progress=False)
+        return output_folder / granule.thumbnail
+
 
 def _landsat_s3_prefix(datapoint: xr.Dataset | USGSLandsatStorageGranule) -> str:
     granule = USGSLandsatStorageGranule.from_data(datapoint)

tilebox-storage/tilebox/storage/granule.py

@@ -1,5 +1,6 @@
 from dataclasses import dataclass
 from datetime import datetime
+from pathlib import Path
 
 import xarray as xr
 
@@ -64,7 +65,6 @@ def _asf_download_urls(granule_name: str) -> StorageURLs:
 class UmbraStorageGranule:
     time: datetime
     granule_name: str
-    processing_level: str
     location: str
 
     @classmethod
@@ -84,17 +84,34 @@ def from_data(cls, dataset: "xr.Dataset | UmbraStorageGranule") -> "UmbraStorage
         return cls(
             time,
             dataset.granule_name.item(),
-            dataset.processing_level.item(),
             dataset.location.item(),
         )
 
 
+def _thumbnail_relative_to_eodata_location(thumbnail_url: str, location: str) -> str:
+    """
+    Returns a thumbnail path from a URL as a path relative to a storage location.
+
+    For example:
+        >>> _thumbnail_relative_to_location(
+        >>>     "https://catalogue.dataspace.copernicus.eu/get-object?path=/Sentinel-1/SAR/EW_GRDM_1S/2025/08/07/S1A_EW_GRDM_1SDH_20250807T111242_20250807T111346_060429_078305_DB6A.SAFE/preview/thumbnail.png",
+        >>>     "/eodata/Sentinel-1/SAR/EW_GRDM_1S/2025/08/07/S1A_EW_GRDM_1SDH_20250807T111242_20250807T111346_060429_078305_DB6A.SAFE"
+        >>> )
+        "preview/thumbnail.png"
+    """
+
+    url_path = thumbnail_url.split("?path=")[-1]
+    url_path = url_path.removeprefix("/")
+    location = location.removeprefix("/eodata/")
+    return str(Path(url_path).relative_to(location))
+
+
 @dataclass
 class CopernicusStorageGranule:
     time: datetime
     granule_name: str
     location: str
-    file_size: int
+    thumbnail: str | None = None
 
     @classmethod
     def from_data(cls, dataset: "xr.Dataset | CopernicusStorageGranule") -> "CopernicusStorageGranule":
@@ -110,11 +127,23 @@ def from_data(cls, dataset: "xr.Dataset | CopernicusStorageGranule") -> "Coperni
 
         time = datetime.combine(dataset.time.dt.date.item(), dataset.time.dt.time.item())
 
+        location = dataset.location.item()
+
+        thumbnail_path = None
+        if "thumbnail" in dataset:
+            thumbnail_path = dataset.thumbnail.item().strip()
+
+        thumbnail = (
+            _thumbnail_relative_to_eodata_location(thumbnail_path, location)
+            if isinstance(thumbnail_path, str) and len(thumbnail_path) > 0
+            else None
+        )
+
         return cls(
             time,
             dataset.granule_name.item(),
-            dataset.location.item(),
-            dataset.file_size.item(),
+            location,
+            thumbnail,
         )