feat: multi-species enclosures and multipolygon OSM relations (#11)

* feat: support multi-species enclosures and multipolygon OSM relations

Agent-Logs-Url: https://github.com/PapaBravo/zoomap/sessions/107cf439-c2d5-484e-95b1-43cbe88be8ae

Co-authored-by: PapaBravo <2863907+PapaBravo@users.noreply.github.com>

* fix: exclude closing vertex from multipolygon centroid; clarify inner-ring comment

Agent-Logs-Url: https://github.com/PapaBravo/zoomap/sessions/107cf439-c2d5-484e-95b1-43cbe88be8ae

Co-authored-by: PapaBravo <2863907+PapaBravo@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: PapaBravo <2863907+PapaBravo@users.noreply.github.com>

Author: Copilot

app.js

@@ -38,10 +38,19 @@ function buildPopupHtml(props) {
   const img = props.image
     ? `<img src="${escapeHtml(props.image)}" alt="${escapeHtml(props.name)}" class="popup-image" />`
     : '';
+  const species = props.species
+    ? `<em>${escapeHtml(props.species)}</em>`
+    : '';
+  const enclosureTag = props.enclosure && props.enclosure !== props.name
+    ? `<div class="popup-enclosure">📍 ${escapeHtml(props.enclosure)}</div>`
+    : '';
+  const desc = props.description
+    ? `<p>${escapeHtml(props.description)}</p>`
+    : '';
   const wikiLink = props.wikipedia
     ? `<a href="${escapeHtml(props.wikipedia)}" target="_blank" rel="noopener noreferrer" class="popup-wiki-link">Wikipedia ↗</a>`
     : '';
-  return `${img}<strong>${escapeHtml(props.name)}</strong><em>${escapeHtml(props.species)}</em><p>${escapeHtml(props.description)}</p>${wikiLink}`;
+  return `${img}<strong>${escapeHtml(props.name)}</strong>${species}${enclosureTag}${desc}${wikiLink}`;
 }
 
 function defaultStyle() {
@@ -140,7 +149,7 @@ fetch(DATA_URL)
 
           const listItem = document.createElement('li');
           listItem.dataset.id = id;
-          listItem.dataset.search = `${props.name} ${props.species} ${props.description}`.toLowerCase();
+          listItem.dataset.search = `${props.name} ${props.species || ''} ${props.description || ''} ${props.enclosure || ''}`.toLowerCase();
 
           const thumb = props.image
             ? `<img src="${escapeHtml(props.image)}" alt="${escapeHtml(props.name)}" class="animal-thumb" />`

docs/architecture.adoc

@@ -49,7 +49,7 @@ The pipeline follows a *medallion architecture* (Bronze → Silver → Gold) imp
 
 | `download_osm.py`
 | `pipeline/scripts/`
-| Queries the Overpass API for POI nodes, ways, and relations within the configured bounding box. Caches raw JSON responses, computes centroids for multi-point geometries, and loads results into the `raw_osm_elements` table in DuckDB (Bronze layer).
+| Queries the Overpass API for POI nodes, ways, and relations within the configured bounding box. Caches raw JSON responses, reconstructs Polygon and MultiPolygon geometries from relation member ways, computes centroids for multi-point geometries, and loads results into the `raw_osm_elements` table in DuckDB (Bronze layer).
 
 | `bronze_osm_pois.sql`
 | `pipeline/dbt/models/bronze/`
@@ -61,11 +61,11 @@ The pipeline follows a *medallion architecture* (Bronze → Silver → Gold) imp
 
 | `enrich_wiki.py`
 | `pipeline/scripts/`
-| Reads QIDs and Wikipedia titles from the Silver layer, calls Wikidata and Wikipedia REST APIs, caches individual entity responses, and writes enrichment data to the `wiki_enrichment` table.
+| Reads QIDs and Wikipedia titles from the Silver layer, calls Wikidata and Wikipedia REST APIs, caches individual entity responses, and writes enrichment data to the `wiki_enrichment` table. When the OSM `species:wikidata` tag contains multiple semicolon-separated QIDs, one enrichment record is produced per QID so that each species in a shared enclosure gets its own GeoJSON feature.
 
 | `gold_animals.sql`
 | `pipeline/dbt/models/gold/`
-| dbt model that joins Silver POIs with enrichment data, coalesces display names and images, constructs Wikipedia URLs, and produces the final `gold_animals` table.
+| dbt model that joins Silver POIs with enrichment data, coalesces display names and images, constructs Wikipedia URLs, and produces the final `gold_animals` table. Because `wiki_enrichment` may contain multiple records per OSM element (one per species), the join naturally expands to one output row per species, each sharing the same geometry. The `enclosure` column always carries the raw OSM `name` tag to remain stable across multi-species expansions.
 
 | `export_geojson.py`
 | `pipeline/scripts/`
@@ -88,7 +88,7 @@ The pipeline follows a *medallion architecture* (Bronze → Silver → Gold) imp
 
 | `app.js`
 | project root
-| Fetches `data/animals.geojson` at startup, renders the Leaflet map with OSM tiles, populates the animal list, handles full-text search, and synchronises list selection with map highlights.
+| Fetches `data/animals.geojson` at startup, renders the Leaflet map with OSM tiles, populates the animal list, handles full-text search (including enclosure name), and synchronises list selection with map highlights. Multiple features sharing the same geometry (multi-species enclosures) each receive their own list entry; MultiPolygon geometries are handled natively by Leaflet.
 
 | `style.css`
 | project root
@@ -120,7 +120,7 @@ Each element in the `features` array represents one animal enclosure.
 
 *Geometry*
 
-The `geometry` field is one of two GeoJSON geometry types:
+The `geometry` field is one of three GeoJSON geometry types:
 
 [cols="1,3", options="header"]
 |===
@@ -130,7 +130,10 @@ The `geometry` field is one of two GeoJSON geometry types:
 | Single coordinate `[longitude, latitude]`; used when the OSM source element is a node.
 
 | `Polygon`
-| Closed ring of coordinates; used when the OSM source element is a way or relation. The pipeline computes the centroid for display purposes but preserves the full polygon.
+| Closed ring of coordinates; used when the OSM source element is a way or a relation with a single outer ring. The pipeline computes the centroid for display purposes but preserves the full polygon. Inner rings (holes) are included when present.
+
+| `MultiPolygon`
+| Multiple outer rings; used when an OSM relation contains more than one outer-role member way (e.g. a non-contiguous enclosure spread across two areas).
 |===
 
 *Properties*
@@ -152,7 +155,7 @@ The `geometry` field is one of two GeoJSON geometry types:
 | `enclosure`
 | string
 | ✓
-| Raw OSM `name` tag of the enclosure; may differ slightly from `name` when the pipeline normalizes the display value.
+| Raw OSM `name` tag of the enclosure element. For multi-species enclosures this value is the same across all species features sharing that enclosure, while `name` holds the individual species common name.
 
 | `species`
 | string

pipeline/dbt/models/gold/gold_animals.sql

@@ -33,9 +33,9 @@ joined as (
         coalesce(w.common_name, s.name)                         as name,
         coalesce(w.scientific_name, s.species)                  as species,
         w.description                                           as description,
-        -- Use element name as the enclosure name for enclosure ways;
-        -- for animal nodes the enclosure is usually their own name
-        coalesce(w.common_name, s.name)                         as enclosure,
+        -- Enclosure is always the raw OSM name tag so that all species sharing
+        -- the same enclosure display a consistent enclosure name.
+        s.name                                                  as enclosure,
         -- Build Wikipedia URL from enrichment title or OSM tag
         case
             when w.wikipedia_title is not null

pipeline/scripts/download_osm.py

@@ -192,6 +192,15 @@ def _centroid_from_geometry(geometry: list) -> tuple[float, float]:
     return (sum(lats) / len(lats), sum(lons) / len(lons))
 
 
+def _centroid_from_coord_pairs(coord_pairs: list) -> tuple[float, float]:
+    """Compute centroid (lat, lon) from a list of [lon, lat] coordinate pairs."""
+    if not coord_pairs:
+        return (None, None)
+    lons = [c[0] for c in coord_pairs]
+    lats = [c[1] for c in coord_pairs]
+    return (sum(lats) / len(lats), sum(lons) / len(lons))
+
+
 def _coords_from_geometry(geometry: list) -> list:
     """Convert Overpass geometry list to GeoJSON coordinate pairs [lon, lat]."""
     return [[p["lon"], p["lat"]] for p in geometry if "lat" in p and "lon" in p]
@@ -230,14 +239,57 @@ def parse_elements(elements: list) -> list[dict]:
                 geom_coords = json.dumps(coords)
 
         elif osm_type == "relation":
-            # Relations are complex; skip for now unless they have a center
-            center = elem.get("center", {})
-            lat = center.get("lat")
-            lon = center.get("lon")
-            if lat is None:
-                continue
-            geom_type = "Point"
-            geom_coords = json.dumps([lon, lat])
+            members = elem.get("members", [])
+
+            # Collect outer and inner rings from way members (multipolygon support)
+            outer_rings = []
+            inner_rings = []
+            for member in members:
+                if member.get("type") != "way":
+                    continue
+                geom = member.get("geometry", [])
+                if not geom:
+                    continue
+                coords = _coords_from_geometry(geom)
+                if len(coords) < 2:
+                    continue
+                role = member.get("role", "")
+                if role == "outer":
+                    outer_rings.append(coords)
+                elif role == "inner":
+                    inner_rings.append(coords)
+
+            if outer_rings:
+                # Compute centroid from unique outer ring vertices (excluding the
+                # duplicate closing vertex present in closed GeoJSON rings).
+                all_outer = [
+                    c
+                    for ring in outer_rings
+                    for c in (ring[:-1] if len(ring) > 1 and ring[0] == ring[-1] else ring)
+                ]
+                lat, lon = _centroid_from_coord_pairs(all_outer)
+                if lat is None:
+                    continue
+                if len(outer_rings) == 1:
+                    # Single outer ring, possibly with holes
+                    geom_type = "Polygon"
+                    geom_coords = json.dumps([outer_rings[0]] + inner_rings)
+                else:
+                    # Multiple outer rings → MultiPolygon.
+                    # Associating inner rings with specific outer rings requires
+                    # spatial containment tests; zoo enclosures rarely have holes
+                    # in multi-part geometries, so inner rings are omitted here.
+                    geom_type = "MultiPolygon"
+                    geom_coords = json.dumps([[ring] for ring in outer_rings])
+            else:
+                # Fall back to center point if no member geometries are available
+                center = elem.get("center", {})
+                lat = center.get("lat")
+                lon = center.get("lon")
+                if lat is None:
+                    continue
+                geom_type = "Point"
+                geom_coords = json.dumps([lon, lat])
 
         else:
             continue

pipeline/scripts/enrich_wiki.py

@@ -208,7 +208,12 @@ def parse_osm_wikipedia_tag(tag: str) -> str | None:
 # ---------------------------------------------------------------------------
 
 def enrich() -> list[dict]:
-    """Read silver_pois, enrich each row, return list of enrichment dicts."""
+    """Read silver_pois, enrich each row, return list of enrichment dicts.
+
+    When the OSM ``species:wikidata`` tag contains multiple QIDs separated by
+    semicolons (e.g. ``Q1;Q2``), one enrichment record is produced per QID so
+    that each species gets its own GeoJSON feature with the same geometry.
+    """
     con = duckdb.connect(DB_PATH)
     try:
         rows = con.execute(
@@ -219,42 +224,53 @@ def enrich() -> list[dict]:
 
     enrichments = []
     for osm_id, species_wikidata_id, wikidata_id, wikipedia_tag in rows:
-        record = {
-            "osm_id": osm_id,
-            "wikidata_id": species_wikidata_id or wikidata_id,
-            "common_name": None,
-            "scientific_name": None,
-            "wikipedia_title": None,
-            "description": None,
-            "image_url": None,
-        }
-
-        # --- Wikidata: prefer species:wikidata, fall back to wikidata ---
-        effective_qid = species_wikidata_id or wikidata_id
-        if effective_qid:
-            entity = fetch_wikidata_entity(effective_qid)
-            if entity:
-                wd_info = extract_wikidata_info(entity, effective_qid)
-                record["common_name"] = wd_info["common_name"]
-                record["scientific_name"] = wd_info["scientific_name"]
-                if wd_info["wikipedia_title"]:
-                    record["wikipedia_title"] = wd_info["wikipedia_title"]
-                if wd_info["image_filename"]:
-                    record["image_url"] = commons_image_url(wd_info["image_filename"])
-
-        # --- Wikipedia (from Wikidata sitelink or OSM tag) ---
-        wp_title = record["wikipedia_title"] or parse_osm_wikipedia_tag(wikipedia_tag)
-        if wp_title:
-            summary = fetch_wikipedia_summary(wp_title)
-            if summary:
-                wp_info = extract_wikipedia_info(summary)
-                record["wikipedia_title"] = wp_title
-                record["description"] = wp_info["description"]
-                # Prefer Wikidata P18 image; fall back to Wikipedia thumbnail
-                if not record["image_url"]:
-                    record["image_url"] = wp_info["image_url"]
-
-        enrichments.append(record)
+        # Split species:wikidata on ';' to handle multiple species per enclosure
+        species_qids = (
+            [q.strip() for q in species_wikidata_id.split(";") if q.strip()]
+            if species_wikidata_id
+            else []
+        )
+
+        # Produce one record per species QID; fall back to a single record using
+        # the enclosure-level wikidata tag when no species QIDs are present.
+        effective_qids = species_qids if species_qids else [wikidata_id]
+
+        for qid in effective_qids:
+            record = {
+                "osm_id": osm_id,
+                "wikidata_id": qid,
+                "common_name": None,
+                "scientific_name": None,
+                "wikipedia_title": None,
+                "description": None,
+                "image_url": None,
+            }
+
+            # --- Wikidata lookup ---
+            if qid:
+                entity = fetch_wikidata_entity(qid)
+                if entity:
+                    wd_info = extract_wikidata_info(entity, qid)
+                    record["common_name"] = wd_info["common_name"]
+                    record["scientific_name"] = wd_info["scientific_name"]
+                    if wd_info["wikipedia_title"]:
+                        record["wikipedia_title"] = wd_info["wikipedia_title"]
+                    if wd_info["image_filename"]:
+                        record["image_url"] = commons_image_url(wd_info["image_filename"])
+
+            # --- Wikipedia (from Wikidata sitelink or OSM tag) ---
+            wp_title = record["wikipedia_title"] or parse_osm_wikipedia_tag(wikipedia_tag)
+            if wp_title:
+                summary = fetch_wikipedia_summary(wp_title)
+                if summary:
+                    wp_info = extract_wikipedia_info(summary)
+                    record["wikipedia_title"] = wp_title
+                    record["description"] = wp_info["description"]
+                    # Prefer Wikidata P18 image; fall back to Wikipedia thumbnail
+                    if not record["image_url"]:
+                        record["image_url"] = wp_info["image_url"]
+
+            enrichments.append(record)
 
     return enrichments
 

pipeline/scripts/export_geojson.py

@@ -41,6 +41,8 @@ def _build_geometry(geom_type: str, geom_coords: str) -> dict | None:
         return {"type": "Point", "coordinates": coords}
     if geom_type == "Polygon":
         return {"type": "Polygon", "coordinates": coords}
+    if geom_type == "MultiPolygon":
+        return {"type": "MultiPolygon", "coordinates": coords}
     if geom_type == "LineString":
         return {"type": "LineString", "coordinates": coords}
     return None

pipeline/scripts/test_download_osm.py

@@ -146,5 +146,93 @@ def test_has_retry_adapter_mounted(self):
         self.assertEqual(adapter.max_retries.total, 3)
 
 
+class TestParseElementsRelations(unittest.TestCase):
+    """parse_elements should build polygon/multipolygon geometry from relation members."""
+
+    def _make_relation(self, members, center=None, tags=None):
+        elem = {
+            "type": "relation",
+            "id": 1,
+            "members": members,
+            "tags": tags or {"attraction": "animal"},
+        }
+        if center:
+            elem["center"] = center
+        return elem
+
+    def _outer(self, coords):
+        return {
+            "type": "way",
+            "ref": 1,
+            "role": "outer",
+            "geometry": [{"lat": lat, "lon": lon} for lon, lat in coords],
+        }
+
+    def _inner(self, coords):
+        return {
+            "type": "way",
+            "ref": 2,
+            "role": "inner",
+            "geometry": [{"lat": lat, "lon": lon} for lon, lat in coords],
+        }
+
+    def test_relation_with_single_outer_ring_produces_polygon(self):
+        ring = [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0], [0.0, 0.0]]
+        elem = self._make_relation([self._outer(ring)])
+        rows = dl.parse_elements([elem])
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["geom_type"], "Polygon")
+        coords = json.loads(rows[0]["geom_coords"])
+        # Polygon coords: list of rings; first ring is outer
+        self.assertEqual(coords[0], ring)
+
+    def test_relation_with_outer_and_inner_ring_produces_polygon_with_hole(self):
+        outer = [[0.0, 0.0], [2.0, 0.0], [2.0, 2.0], [0.0, 2.0], [0.0, 0.0]]
+        inner = [[0.5, 0.5], [1.5, 0.5], [1.5, 1.5], [0.5, 1.5], [0.5, 0.5]]
+        elem = self._make_relation([self._outer(outer), self._inner(inner)])
+        rows = dl.parse_elements([elem])
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["geom_type"], "Polygon")
+        coords = json.loads(rows[0]["geom_coords"])
+        self.assertEqual(len(coords), 2)  # outer + one hole
+        self.assertEqual(coords[0], outer)
+        self.assertEqual(coords[1], inner)
+
+    def test_relation_with_multiple_outer_rings_produces_multipolygon(self):
+        ring1 = [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0], [0.0, 0.0]]
+        ring2 = [[2.0, 2.0], [3.0, 2.0], [3.0, 3.0], [2.0, 3.0], [2.0, 2.0]]
+        elem = self._make_relation([self._outer(ring1), self._outer(ring2)])
+        rows = dl.parse_elements([elem])
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["geom_type"], "MultiPolygon")
+        coords = json.loads(rows[0]["geom_coords"])
+        self.assertEqual(len(coords), 2)  # two polygons
+        self.assertEqual(coords[0], [ring1])
+        self.assertEqual(coords[1], [ring2])
+
+    def test_relation_without_members_falls_back_to_center_point(self):
+        elem = self._make_relation([], center={"lat": 52.5, "lon": 13.5})
+        rows = dl.parse_elements([elem])
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["geom_type"], "Point")
+        self.assertAlmostEqual(rows[0]["centroid_lat"], 52.5)
+        self.assertAlmostEqual(rows[0]["centroid_lon"], 13.5)
+
+    def test_relation_without_members_and_no_center_is_skipped(self):
+        elem = self._make_relation([])
+        rows = dl.parse_elements([elem])
+        self.assertEqual(len(rows), 0)
+
+    def test_relation_centroid_computed_from_outer_ring_vertices(self):
+        # A closed ring: [0,0]-[2,0]-[2,2]-[0,2]-[0,0].
+        # The closing vertex is excluded from the centroid calculation so the
+        # 4 unique vertices are averaged: lon=(0+2+2+0)/4=1.0, lat=(0+0+2+2)/4=1.0
+        ring = [[0.0, 0.0], [2.0, 0.0], [2.0, 2.0], [0.0, 2.0], [0.0, 0.0]]
+        elem = self._make_relation([self._outer(ring)])
+        rows = dl.parse_elements([elem])
+        self.assertAlmostEqual(rows[0]["centroid_lat"], 1.0)
+        self.assertAlmostEqual(rows[0]["centroid_lon"], 1.0)
+
+
 if __name__ == "__main__":
     unittest.main()