Add tilebox logo to timelapse frames

Author: lukasbindreiter

.gitattributes

@@ -0,0 +1,2 @@
+seasonal-timelapse/assets/*.png filter=lfs diff=lfs merge=lfs -text
+seasonal-timelapse/assets/*.ttf filter=lfs diff=lfs merge=lfs -text

seasonal-timelapse/README.md

@@ -89,9 +89,9 @@ JSON represents tuples as arrays and datetimes as RFC 3339 strings.
 
 ## Outputs
 
-The workflow writes its result to `outputs/<job-specific-directory>/timelapse.webp` in the runner's working directory. Intermediate PNG frames are stored in the `frames/` directory beside it.
+The workflow writes its result to `outputs/<job-specific-directory>/timelapse.webp` in the runner's working directory and uploads it to workflow storage as `<job-specific-directory>/timelapse.webp`. The final structured log message includes its `storage_path`, which the Console quickstart uses to display the animation. Intermediate PNG frames are stored in the local `frames/` directory beside it.
 
-Output directories include the dates, coordinates, and square width, so separate runs do not overwrite each other. Outputs are local to the runners. The frame and assembly tasks therefore need runners that share the same working directory and filesystem.
+Output directories include the dates, coordinates, and square width, so separate runs do not overwrite each other. Intermediate outputs are local to the runners. The frame and assembly tasks therefore need runners that share the same working directory and filesystem.
 
 ## Explore locally
 

seasonal-timelapse/assets/Poppins-Medium.ttf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d909883de81344e0fbcfef30e931872e92d9aeecdf85b6dcf6e0b28c078e98e
+size 156520

seasonal-timelapse/assets/tilebox-logo.png

@@ -5,8 +5,10 @@ description = "Build low-cloud seasonal Sentinel-2 RGB timelapses"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
+  "niquests>=3.21.0",
   "pillow>=11.3.0",
   "pyproj>=3.7.2",
+  "rasterio>=1.4.3",
   "shapely>=2.1.2",
   "tilebox",
   "xarray>=2025.9.0",

seasonal-timelapse/pyproject.toml

@@ -4,11 +4,22 @@
 
 import numpy as np
 import xarray as xr
-from PIL import Image, ImageOps
+from affine import Affine
+from PIL import Image, ImageDraw, ImageFont, ImageOps
+from pyproj import CRS
+from rasterio.enums import Resampling
+from rasterio.transform import from_bounds
+from rasterio.warp import reproject
 from tilebox.datasets.assets import AssetCollection
 from tilebox.storage.aio import Client as StorageClient
 from tilebox.storage.geotiff import window_from_bounds
 
+_ASSETS_DIR = Path(__file__).parent.parent / "assets"
+_FONT_PATH = _ASSETS_DIR / "Poppins-Medium.ttf"
+_LOGO_PATH = _ASSETS_DIR / "tilebox-logo.png"
+_TEXT_COLOR = (21, 27, 43, 255)
+_FRAME_SIZE = 900
+
 
 def lut(gamma: float, black_point: int, white_point: int) -> list[int]:
     """Build an RGB display LUT with fixed levels and gamma correction.
@@ -41,20 +52,86 @@ async def read_visual(datapoint: xr.Dataset, bounds: tuple[float, float, float,
         require_fully_contained=True,
     )
     chunk = await geotiff.read(window=window)
-    return np.moveaxis(chunk.data[:3], 0, -1)
+    return align_visual(
+        chunk.data,
+        source_transform=chunk.transform,
+        source_crs=chunk.crs,
+        source_nodata=chunk.nodata,
+        bounds=bounds,
+    )
+
+
+def align_visual(
+    data: np.ndarray,
+    *,
+    source_transform: Affine,
+    source_crs: CRS | str,
+    source_nodata: float | None,
+    bounds: tuple[float, float, float, float],
+) -> np.ndarray:
+    """Reproject RGB data onto one fixed WGS84 grid so frames stay aligned."""
+    destination = np.zeros((3, _FRAME_SIZE, _FRAME_SIZE), dtype=data.dtype)
+    reproject(
+        data[:3],
+        destination,
+        src_transform=source_transform,
+        src_crs=source_crs,
+        src_nodata=source_nodata,
+        dst_transform=from_bounds(*bounds, width=_FRAME_SIZE, height=_FRAME_SIZE),
+        dst_crs="EPSG:4326",
+        resampling=Resampling.bilinear,
+    )
+    return np.moveaxis(destination, 0, -1)
 
 
 def render_frame(
     visual: np.ndarray,
     *,
     destination: Path,
+    caption: str,
 ) -> None:
-    """Render an unlabelled square RGB frame."""
+    """Render a branded square RGB frame with a readable caption."""
     image = Image.fromarray(visual)
-    size = min(image.width, image.height, 900)
+    size = min(image.width, image.height, _FRAME_SIZE)
     frame = ImageOps.fit(image, (size, size), method=Image.Resampling.LANCZOS)
     frame = frame.point(SENTINEL2_DISPLAY_LUT)
 
+    overlay = Image.new("RGBA", frame.size)
+    draw = ImageDraw.Draw(overlay)
+    margin = max(4, round(size * 0.027))
+    panel_height = max(24, round(size * 0.09))
+    panel_bounds = (margin, size - margin - panel_height, size - margin, size - margin)
+    corner_radius = max(5, round(panel_height * 0.24))
+    shadow_offset = max(1, round(size * 0.004))
+    shadow_bounds = (
+        panel_bounds[0] + shadow_offset,
+        panel_bounds[1] + shadow_offset,
+        panel_bounds[2] + shadow_offset,
+        panel_bounds[3] + shadow_offset,
+    )
+    draw.rounded_rectangle(shadow_bounds, radius=corner_radius, fill=(0, 0, 0, 70))
+    draw.rounded_rectangle(panel_bounds, radius=corner_radius, fill=(255, 255, 255, 235))
+
+    content_padding = max(4, round(panel_height * 0.2))
+    logo_height = panel_height - 2 * content_padding
+    with Image.open(_LOGO_PATH) as source_logo:
+        logo = source_logo.convert("RGBA")
+        logo_width = round(logo.width * logo_height / logo.height)
+        logo = logo.resize((logo_width, logo_height), Image.Resampling.LANCZOS)
+    logo_x = panel_bounds[0] + content_padding
+    logo_y = panel_bounds[1] + (panel_height - logo_height) // 2
+    overlay.alpha_composite(logo, (logo_x, logo_y))
+
+    font = ImageFont.truetype(_FONT_PATH, max(10, round(panel_height * 0.34)))
+    caption_bounds = draw.textbbox((0, 0), caption, font=font)
+    caption_width = caption_bounds[2] - caption_bounds[0]
+    caption_height = caption_bounds[3] - caption_bounds[1]
+    caption_x = panel_bounds[2] - content_padding - caption_width
+    caption_y = panel_bounds[1] + (panel_height - caption_height) // 2 - caption_bounds[1]
+    draw.text((caption_x, caption_y), caption, fill=_TEXT_COLOR, font=font)
+
+    frame = Image.alpha_composite(frame.convert("RGBA"), overlay).convert("RGB")
+
     destination.parent.mkdir(parents=True, exist_ok=True)
     frame.save(destination, format="PNG", optimize=True)
 

seasonal-timelapse/seasonal_rgb_timelapse/imagery.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+import hashlib
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
+from urllib.parse import quote
 from uuid import UUID
 
+import niquests
 import xarray as xr
 from pyproj import CRS, Transformer
 from shapely import Geometry, Point, box, transform
@@ -112,7 +115,7 @@ def identifier() -> tuple[str, str]:
         return "tilebox.com/seasonal-rgb-timelapse/RenderSeasonalFrame", "v1.0"
 
     async def execute(self, context: ExecutionContext) -> None:
-        """Read and render one unlabelled seasonal RGB frame."""
+        """Read and render one branded seasonal RGB frame."""
         context.current_task.display = f"Render {self.season}"
         datapoint = Client().dataset(DATASET).collection(COLLECTION).find(self.datapoint_id)
         stac_id = str(datapoint.stac_id.item())
@@ -125,10 +128,13 @@ async def execute(self, context: ExecutionContext) -> None:
         frame_name = f"{self.season_start:%y_%m}-{end_year % 100:02d}_{end_month:02d}.png"
         relative_frame_path = Path("frames") / frame_name
         frame_path = _output_root() / self.output_name / relative_frame_path
-        render_frame(visual, destination=frame_path)
+        render_frame(visual, destination=frame_path, caption=stac_id)
         context.progress().done(1)
         context.logger.info(
-            "Rendered seasonal frame", frame=str(relative_frame_path), season=self.season, stac_id=stac_id
+            "Rendered seasonal frame",
+            frame=str(relative_frame_path),
+            season=self.season,
+            stac_id=stac_id,
         )
 
 
@@ -154,10 +160,44 @@ def execute(self, context: ExecutionContext) -> None:
         with context.tracer.span("encode-webp"):
             encode_animated(frame_paths, destination)
         context.logger.info(
-            f"Timelapse saved to {destination}",
+            "Timelapse saved to runner output directory",
+            local_path=destination,
             frames=len(frame_paths),
             size_bytes=destination.stat().st_size,
         )
+        with context.tracer.span("upload-webp"):
+            storage_path = _upload_to_workflow_storage(destination, relative_destination.as_posix(), context)
+        context.logger.info(
+            "Timelapse uploaded to workflow storage",
+            storage_path=storage_path,
+        )
+
+
+def _upload_to_workflow_storage(source: Path, object_path: str, context: ExecutionContext) -> str:
+    """Upload a file through the workflow storage HTTP endpoint."""
+    content = source.read_bytes()
+    digest = hashlib.sha256(content).hexdigest()
+
+    # Workflow storage is an upcoming API. Until the high-level client lands, reuse the low-level client connection
+    # inherited by both direct runners and release workers.
+    client = context.runner_context.storage_locations._client  # noqa: SLF001
+    api_url = client._auth["url"].removesuffix("/")  # noqa: SLF001
+    token = client._auth["token"]  # noqa: SLF001
+    if not token:
+        raise RuntimeError("workflow storage upload requires an authenticated Tilebox client")
+
+    encoded_path = quote(object_path, safe="/")
+    response = niquests.put(
+        f"{api_url}/v1/storage/{digest}/{encoded_path}",
+        data=content,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "image/webp",
+        },
+        timeout=60,
+    )
+    response.raise_for_status()
+    return str(response.json()["path"])
 
 
 def _output_root() -> Path:

seasonal-timelapse/seasonal_rgb_timelapse/tasks.py

@@ -1,9 +1,10 @@
 from pathlib import Path
 
 import numpy as np
+from affine import Affine
 from PIL import Image
 
-from seasonal_rgb_timelapse.imagery import encode_animated, lut, render_frame
+from seasonal_rgb_timelapse.imagery import align_visual, encode_animated, lut, render_frame
 
 
 def test_lut_applies_fixed_levels_to_each_rgb_channel() -> None:
@@ -17,15 +18,18 @@ def test_lut_applies_fixed_levels_to_each_rgb_channel() -> None:
     assert table[110] == 255
 
 
-def test_render_frame_writes_unlabelled_square_image(tmp_path: Path) -> None:
-    """A rendered frame contains only a square crop of the source image."""
-    visual = np.full((60, 100, 3), (10, 20, 30), dtype=np.uint8)
+def test_render_frame_writes_branded_square_image(tmp_path: Path) -> None:
+    """A rendered frame contains a square crop and readable branding panel."""
+    visual = np.full((300, 500, 3), (10, 20, 30), dtype=np.uint8)
     destination = tmp_path / "frame.png"
 
-    render_frame(visual, destination=destination)
+    render_frame(visual, destination=destination, caption="S2B_33UXP_20260306_0_L2A")
 
     with Image.open(destination) as image:
-        assert image.size == (60, 60)
+        assert image.size == (300, 300)
+        assert max(image.getpixel((150, 150))) < 40
+        panel = np.asarray(image)[266:292, 8:292]
+        assert np.count_nonzero(panel[:, :, 0] > 200) > panel.shape[0] * panel.shape[1] // 2
 
 
 def test_encode_animated_writes_looping_webp(tmp_path: Path) -> None:
@@ -49,9 +53,49 @@ def test_render_frame_uses_fixed_sentinel2_display_levels(tmp_path: Path) -> Non
     dark_path = tmp_path / "dark.png"
     bright_path = tmp_path / "bright.png"
 
-    render_frame(np.full((8, 8, 3), 5, dtype=np.uint8), destination=dark_path)
-    render_frame(np.full((8, 8, 3), 250, dtype=np.uint8), destination=bright_path)
+    render_frame(
+        np.full((100, 100, 3), 5, dtype=np.uint8),
+        destination=dark_path,
+        caption="S2B_33UXP_20260306_0_L2A",
+    )
+    render_frame(
+        np.full((100, 100, 3), 250, dtype=np.uint8),
+        destination=bright_path,
+        caption="S2B_33UXP_20260306_0_L2A",
+    )
 
     with Image.open(dark_path) as dark, Image.open(bright_path) as bright:
         assert dark.getpixel((0, 0)) == (0, 0, 0)
         assert bright.getpixel((0, 0)) == (255, 255, 255)
+
+
+def test_align_visual_keeps_world_coordinates_fixed_across_source_grids() -> None:
+    """The same geographic feature lands on the same output row for every scene."""
+    first = np.zeros((3, 10, 10), dtype=np.uint8)
+    first[:, 4, :] = 255
+    shifted = np.zeros((3, 12, 12), dtype=np.uint8)
+    shifted[:, 5, 1:11] = 255
+
+    first_aligned = align_visual(
+        first,
+        source_transform=Affine.translation(0, 10) * Affine.scale(1, -1),
+        source_crs="EPSG:4326",
+        source_nodata=None,
+        bounds=(0, 0, 10, 10),
+    )
+    shifted_aligned = align_visual(
+        shifted,
+        source_transform=Affine.translation(-1, 11) * Affine.scale(1, -1),
+        source_crs="EPSG:4326",
+        source_nodata=None,
+        bounds=(0, 0, 10, 10),
+    )
+
+    assert first_aligned.shape == (900, 900, 3)
+    first_profile = first_aligned[:, :, 0].mean(axis=1)
+    shifted_profile = shifted_aligned[:, :, 0].mean(axis=1)
+    assert np.argmax(first_profile) == np.argmax(shifted_profile)
+    np.testing.assert_array_equal(
+        np.flatnonzero(first_profile > first_profile.max() / 2),
+        np.flatnonzero(shifted_profile > shifted_profile.max() / 2),
+    )

seasonal-timelapse/tests/test_imagery.py

@@ -1,4 +1,7 @@
 from datetime import datetime, timezone
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock
 from uuid import UUID
 
 import pytest
@@ -11,6 +14,7 @@
     RenderSeasonalFrame,
     _season_name,
     _square_aoi,
+    _upload_to_workflow_storage,
 )
 
 
@@ -56,6 +60,33 @@ def test_root_task_defaults_to_an_optional_time_range() -> None:
     assert task.max_cloud_percent == 20.0
 
 
+def test_upload_uses_runner_api_connection(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """Workflow storage reuses the API connection inherited by the runner."""
+    source = tmp_path / "timelapse.webp"
+    source.write_bytes(b"webp")
+    response = Mock()
+    response.json.return_value = {
+        "path": "/019d1c17-8636-7259-a5fd-dda1f9f26c1e/a57bb082e728a0cdce930ecfcccf4510a3a247be5f322b09b3a971a3f5ed34f8/seasonal output/timelapse.webp"
+    }
+    put = Mock(return_value=response)
+    monkeypatch.setattr("seasonal_rgb_timelapse.tasks.niquests.put", put)
+    client = SimpleNamespace(_auth={"url": "https://api.tilebox.com/", "token": "secret"})
+    context = SimpleNamespace(
+        runner_context=SimpleNamespace(storage_locations=SimpleNamespace(_client=client)),
+    )
+
+    storage_path = _upload_to_workflow_storage(source, "seasonal output/timelapse.webp", context)
+
+    put.assert_called_once_with(
+        "https://api.tilebox.com/v1/storage/a57bb082e728a0cdce930ecfcccf4510a3a247be5f322b09b3a971a3f5ed34f8/seasonal%20output/timelapse.webp",
+        data=b"webp",
+        headers={"Authorization": "Bearer secret", "Content-Type": "image/webp"},
+        timeout=60,
+    )
+    response.raise_for_status.assert_called_once_with()
+    assert storage_path == response.json.return_value["path"]
+
+
 def test_season_name_for_cross_year_season() -> None:
     """December seasons include both years."""
     name, start = _season_name(xr.DataArray(datetime(2025, 12, 1)))

seasonal-timelapse/tests/test_tasks.py

@@ -8,6 +8,7 @@ include = [
   "pyproject.toml",
   "uv.lock",
   "runner.py",
+  "assets/**",
   "seasonal_rgb_timelapse/**",
 ]
 exclude = [