Merge branch 'main' into parquet

Author: avsm

.github/ISSUE_TEMPLATE/embedding-request.yml

@@ -0,0 +1,93 @@
+name: Embedding Request
+description: Request precomputed embeddings for a specific region/years (2017–2024). Please fill out all required fields.
+title: "[Embedding Request] ORG / YEARS / ROI summary"
+labels:
+  - embedding-request
+assignees: []  # Optional: fill in default maintainers' GitHub IDs
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for your request! Please follow the format below. 
+        • Coordinates must be in **lon,lat** (WGS84) with **4 decimal places** (e.g., `103.1234,30.5678`).  
+        • ROI should be a bounding box (Left/Right/Top/Bottom).
+
+  - type: input
+    id: org
+    attributes:
+      label: 1) Your organization
+      description: e.g., University of Cambridge / UESTC / Company X
+      placeholder: e.g., University of Cambridge
+    validations:
+      required: true
+
+  - type: textarea
+    id: purpose
+    attributes:
+      label: 2) Intended use
+      description: Briefly describe how you plan to use these embeddings (project/paper/course/demo, tasks like retrieval/classification/clustering/visualization, etc.)
+      placeholder: e.g., For downstream evaluation in project XXX (retrieval/classification/…)
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: "3) ROI (bounding box) – please provide **four points** as **lon,lat** with **4 decimals**."
+
+  - type: input
+    id: roi_left
+    attributes:
+      label: ROI – Left Top (lon,lat)
+      placeholder: "e.g., 103.1234,30.5678"
+    validations:
+      required: true
+
+  - type: input
+    id: roi_right
+    attributes:
+      label: ROI – Right Top (lon,lat)
+      placeholder: "e.g., 104.4321,30.5678"
+    validations:
+      required: true
+
+  - type: input
+    id: roi_top
+    attributes:
+      label: ROI – Left Bottom (lon,lat)
+      placeholder: "e.g., 103.7777,31.0000"
+    validations:
+      required: true
+
+  - type: input
+    id: roi_bottom
+    attributes:
+      label: ROI – Right Bottom (lon,lat)
+      placeholder: "e.g., 103.7777,30.1000"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: years
+    attributes:
+      label: 4) Years (multi-select)
+      description: Choose one or more years between 2017–2024.
+      multiple: true
+      options:
+        - "2017"
+        - "2018"
+        - "2019"
+        - "2020"
+        - "2021"
+        - "2022"
+        - "2023"
+        - "2024"
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional info (optional)
+      description: e.g., whether near-year/near-area substitution is acceptable, deadlines, etc.
+      placeholder: Leave blank if not applicable

CHANGES.md

@@ -1,7 +1,8 @@
 ## v0.6.0 
 
-- Add support for a Parquet registry as an alternative source to
-  lookup tile information.
+- registry: Add support for a Parquet registry as an alternative source
+  to lookup tile information (#16).
+- docs: Fix old documentation examples (#22, #18 report by @cjissmart)
 
 ## v0.5.2 (2025-09-02)
 

README.md

@@ -13,6 +13,18 @@ geospatial analysis tasks. Read more details about [the model](https://github.co
 
 ![Coverage map](https://raw.githubusercontent.com/ucam-eo/tessera-coverage-map/refs/heads/main/map.png)
 
+### Request missing embeddings
+
+This repo provides **precomputed embeddings** for multiple years and regions.
+Embeddings are generated by **randomly sampling tiles** within each region to ensure broad spatial coverage.
+
+If some **years (2017–2024) / areas** are still missing for your use case, please submit an **Embedding Request**:
+
+- 👉 **[Open an Embedding Request](../../issues/new?template=embedding-request.yml&labels=embedding-request)**
+- Please include: **your organization, intended use, ROI as a bounding box with four points (lon,lat, 4 decimals), and the year(s)**.
+
+After you submit the request, we will **prioritize your ROI** and notify you via a comment in the issue once the embeddings are ready.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -188,15 +200,15 @@ from geotessera import GeoTessera
 gt = GeoTessera()
 
 # Method 1: Fetch a single tile
-embedding, crs, transform = gt.fetch_embedding(lat=52.05, lon=0.15, year=2024)
+embedding, crs, transform = gt.fetch_embedding(lon=0.15, lat=52.05, year=2024)
 print(f"Shape: {embedding.shape}")  # e.g., (1200, 1200, 128)
 print(f"CRS: {crs}")  # Coordinate reference system from landmask
 
 # Method 2: Fetch all tiles in a bounding box
 bbox = (-0.2, 51.4, 0.1, 51.6)  # (min_lon, min_lat, max_lon, max_lat)
 embeddings = gt.fetch_embeddings(bbox, year=2024)
 
-for tile_lat, tile_lon, embedding_array, crs, transform in embeddings:
+for tile_lon, tile_lat, embedding_array, crs, transform in embeddings:
     print(f"Tile ({tile_lat}, {tile_lon}): {embedding_array.shape}")
 ```
 
@@ -231,7 +243,7 @@ files = gt.export_embedding_geotiffs(
 # Fetch and process embeddings directly
 embeddings = gt.fetch_embeddings(bbox, year=2024)
 
-for lat, lon, embedding, crs, transform in embeddings:
+for lon, lat, embedding, crs, transform in embeddings:
     # Compute statistics
     mean_values = np.mean(embedding, axis=(0, 1))  # Mean per channel
     std_values = np.std(embedding, axis=(0, 1))    # Std per channel
@@ -247,18 +259,19 @@ for lat, lon, embedding, crs, transform in embeddings:
 
 ```python
 from geotessera.visualization import (
-    create_rgb_mosaic_from_geotiffs,
+    create_rgb_mosaic,
+    visualize_global_coverage
+)
+from geotessera.web import (
     create_coverage_summary_map,
-    visualize_global_coverage,
     geotiff_to_web_tiles
 )
 
 # Create an RGB mosaic from multiple GeoTIFF files
-create_rgb_mosaic_from_geotiffs(
+create_rgb_mosaic(
     geotiff_paths=["tile1.tif", "tile2.tif"],
     output_path="mosaic.tif",
-    bands=(0, 1, 2),  # RGB bands
-    normalize=True  # Normalize to 0-255
+    bands=(0, 1, 2)  # RGB bands
 )
 
 # Generate web tiles for interactive maps

docs/geotessera.rst

@@ -62,9 +62,9 @@ Visualization utilities for creating maps, web tiles, and interactive visualizat
 **Key Features:**
 
 * :func:`~geotessera.visualization.visualize_global_coverage` - Create global coverage maps
-* :func:`~geotessera.visualization.create_rgb_mosaic_from_geotiffs` - Combine multiple GeoTIFFs into a mosaic
-* :func:`~geotessera.visualization.geotiff_to_web_tiles` - Generate web tiles for interactive maps
-* :func:`~geotessera.visualization.create_coverage_summary_map` - Create coverage summary visualizations
+* :func:`~geotessera.visualization.create_rgb_mosaic` - Combine multiple GeoTIFFs into a mosaic
+* :func:`~geotessera.web.geotiff_to_web_tiles` - Generate web tiles for interactive maps
+* :func:`~geotessera.web.create_coverage_summary_map` - Create coverage summary visualizations
 
 .. automodule:: geotessera.visualization
    :members:
@@ -141,16 +141,15 @@ Create Visualizations
 Generate visualizations::
 
     from geotessera.visualization import (
-        create_rgb_mosaic_from_geotiffs,
+        create_rgb_mosaic,
         visualize_global_coverage
     )
     
     # Create RGB mosaic
-    create_rgb_mosaic_from_geotiffs(
+    create_rgb_mosaic(
         geotiff_paths=rgb_files,
         output_path="mosaic.tif",
-        bands=(0, 1, 2),
-        normalize=True
+        bands=(0, 1, 2)
     )
     
     # Create coverage map