feat(3d-buildings): add detailed German LoD2

Author: Medformatik

apps/web/next.config.ts

@@ -21,7 +21,9 @@ const contentSecurityPolicy = [
   "style-src 'self' 'unsafe-inline'",
   "worker-src 'self' blob:",
   "connect-src 'self' https: http: ws: wss: data: blob:",
-  "script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:",
+  // The only third-party script is BKG's official basemap.de 3D renderer.
+  // Its loader also enforces a reviewed SHA-384 Subresource Integrity hash.
+  "script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: https://sgx.geodatenzentrum.de",
 ].join("; ");
 
 // Security headers applied to every route. CSP enforces object/base/frame/form

apps/web/src/lib/attributionWiringCoverage.test.ts

@@ -131,8 +131,6 @@ const BORROWED_CREDIT_WIRES = ATTRIBUTION_WIRES.filter(
  * used to fail nothing.
  */
 const NO_CREDIT_OWED: Record<string, string> = {
-  "overlay-3d-buildings":
-    "extrudes the basemap's own `building` source-layer; the base style's credits already cover it",
   "overlay-cycling":
     "restyles the basemap's own `transportation`/`poi` source-layers; the base style's credits already cover it",
   "overlay-tool-measurement": "draws only the user's own measurement geometry — no external data",

apps/web/src/test/fakeMap.ts

@@ -21,6 +21,7 @@ export interface FakeMapState {
   styleLoaded: boolean;
   /** Backing value for `getZoom()` — mutate then emit("moveend") to simulate a zoom gesture. */
   zoom: number;
+  center: { lng: number; lat: number };
   pitch: number;
   maxPitch: number;
   cameraTransitions: Array<{
@@ -47,6 +48,7 @@ export interface CreateFakeMapOptions {
   styleLoaded?: boolean;
   /** Initial `getZoom()` value (default 10). */
   zoom?: number;
+  center?: { lng: number; lat: number };
   /** Initial camera pitch and pitch constraint. */
   pitch?: number;
   maxPitch?: number;
@@ -62,6 +64,7 @@ export function createFakeMap(options: CreateFakeMapOptions = {}): FakeMap {
     images: new Set(),
     styleLoaded: options.styleLoaded ?? true,
     zoom: options.zoom ?? 10,
+    center: options.center ?? { lng: 0, lat: 0 },
     pitch: options.pitch ?? 0,
     maxPitch: options.maxPitch ?? 60,
     cameraTransitions: [],
@@ -156,7 +159,11 @@ export function createFakeMap(options: CreateFakeMapOptions = {}): FakeMap {
     setLight: (light: Record<string, unknown>) => {
       state.light = light;
     },
-    getCenter: () => ({ lng: 0, lat: 0 }),
+    getCenter: () => state.center,
+    setCenter: (center: { lng: number; lat: number }) => {
+      state.center = center;
+    },
+    getProjection: () => ({ type: "mercator" }),
     getBounds: () => ({
       getWest: () => -180,
       getSouth: () => -90,
@@ -177,6 +184,7 @@ export function createFakeMap(options: CreateFakeMapOptions = {}): FakeMap {
       if (typeof options.pitch === "number") state.pitch = options.pitch;
     },
     fitBounds: () => {},
+    triggerRepaint: () => {},
     on,
     off,
     once: on,

docs/docs/features/map-layers.md

@@ -133,7 +133,23 @@ a glance.
 | **Winter sports**    | Ski areas, pistes, and lifts                          | OpenSnowMap                  |
 | **Nautical**         | Sea marks, depths, tides, and water levels            | OpenSeaMap and marine agencies |
 | **Satellite imagery**| A true-color satellite overlay (distinct from the satellite base) | NASA GIBS / MODIS |
-| **3D buildings**     | Extruded building footprints                          | OpenMapTiles building data   |
+| **3D buildings**     | Detailed LoD2 roofs in Germany at z16+, with extruded-footprint fallback | GeoBasis-DE/BKG and OpenMapTiles |
+
+The **3D buildings** overlay uses the official basemap.de LoD2 building service
+when the map is in Germany, in Web Mercator, and zoomed to level 16 or closer.
+Roofs and building parts then use their generalized official geometry instead
+of remaining flat-topped boxes. At lower zooms, outside Germany, on the globe,
+while the detailed tiles load, or if the external service is unavailable, the
+overlay keeps rendering the lightweight OpenMapTiles footprint extrusion.
+
+The detailed source is a hosted BKG test service rather than downloadable open
+data. OpenMapX streams it directly at runtime, does not mirror or persist its
+tiles, and displays the required `© GeoBasis-DE/BKG` credit and modification
+notice while it is active. Its current terms cover testing, demos, and genuine
+beta use; operators planning regular commercial-production use must first
+obtain written permission from BKG. See the
+[basemap.de 3D product page](https://basemap.de/produkte-und-dienste/3d/) and
+[test-operation terms](https://sgx.geodatenzentrum.de/public/gdz/lizenz/deu/lizenz_basemapde_3d-testbetrieb.pdf).
 
 ### Map tools
 

integrations/overlay-3d-buildings/__tests__/basemap-lod2.test.ts

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(() => {
+  document.getElementById("openmapx-basemap-de-3d-renderer")?.remove();
+  delete window.Mapbox3DTiles;
+  vi.resetModules();
+});
+
+describe("basemap.de LoD2 renderer", () => {
+  it("loads only the reviewed renderer bytes with CORS-enabled SRI", async () => {
+    const { BASEMAP_LOD2_RENDERER_INTEGRITY, BASEMAP_LOD2_RENDERER_URL, loadBasemapLod2Renderer } =
+      await import("../basemap-lod2");
+
+    const pending = loadBasemapLod2Renderer();
+    const script = document.getElementById("openmapx-basemap-de-3d-renderer") as HTMLScriptElement;
+
+    expect(script.src).toBe(BASEMAP_LOD2_RENDERER_URL);
+    expect(script.integrity).toBe(BASEMAP_LOD2_RENDERER_INTEGRITY);
+    expect(script.crossOrigin).toBe("anonymous");
+
+    class FakeDetailedLayer {
+      id = "fake";
+      type = "custom" as const;
+      render = vi.fn();
+    }
+    window.Mapbox3DTiles = {
+      Mapbox3DTilesLayer: FakeDetailedLayer as never,
+    };
+    script.dispatchEvent(new Event("load"));
+
+    await expect(pending).resolves.toBe(window.Mapbox3DTiles);
+  });
+
+  it("fails closed and removes a renderer that does not pass browser loading checks", async () => {
+    const { loadBasemapLod2Renderer } = await import("../basemap-lod2");
+    const pending = loadBasemapLod2Renderer();
+    const script = document.getElementById("openmapx-basemap-de-3d-renderer") as HTMLScriptElement;
+
+    script.dispatchEvent(new Event("error"));
+
+    await expect(pending).rejects.toThrow("integrity-pinned");
+    expect(document.getElementById("openmapx-basemap-de-3d-renderer")).toBeNull();
+  });
+
+  it("removes an incompatible renderer so a later activation can retry", async () => {
+    const { loadBasemapLod2Renderer } = await import("../basemap-lod2");
+    const pending = loadBasemapLod2Renderer();
+    const script = document.getElementById("openmapx-basemap-de-3d-renderer") as HTMLScriptElement;
+
+    script.dispatchEvent(new Event("load"));
+
+    await expect(pending).rejects.toThrow("without its layer constructor");
+    expect(document.getElementById("openmapx-basemap-de-3d-renderer")).toBeNull();
+  });
+});

integrations/overlay-3d-buildings/__tests__/map-layer.test.tsx

@@ -5,6 +5,16 @@ import { useBuildingsStore } from "../store";
 
 let fake: FakeMap;
 
+const createBasemapLod2LayerMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../basemap-lod2", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../basemap-lod2")>();
+  return {
+    ...actual,
+    createBasemapLod2Layer: createBasemapLod2LayerMock,
+  };
+});
+
 vi.mock("@/lib/MapContext", () => ({
   useMap: () => ({
     mapRef: { current: fake.map },
@@ -16,6 +26,7 @@ vi.mock("@/lib/MapContext", () => ({
 import { BuildingExtrusionLayer } from "../map-layer";
 
 const LAYER_ID = "openmapx-3d-buildings";
+const DETAILED_LAYER_ID = "openmapx-3d-buildings-lod2";
 const BUILDING_LAYER_ID = "base-buildings";
 const SYMBOL_LAYER_ID = "place-labels";
 
@@ -46,6 +57,14 @@ function addBaseStyle(): void {
 beforeEach(() => {
   fake = createFakeMap({ zoom: 16, pitch: 20, maxPitch: 70 });
   addBaseStyle();
+  createBasemapLod2LayerMock.mockReset();
+  createBasemapLod2LayerMock.mockImplementation(async (id: string) => ({
+    id,
+    type: "custom",
+    renderingMode: "3d",
+    loadStatus: 1,
+    render: vi.fn(),
+  }));
   useBuildingsStore.setState({ panelOpen: false, layerVisible: false });
   vi.stubGlobal(
     "matchMedia",
@@ -71,6 +90,58 @@ describe("BuildingExtrusionLayer", () => {
     expect(layer?.source).not.toBe("unrelated");
   });
 
+  it("replaces the fallback with detailed LoD2 geometry at z16 in Germany", async () => {
+    fake.state.center = { lng: 8.6821, lat: 50.1109 };
+    useBuildingsStore.setState({ layerVisible: true });
+
+    render(<BuildingExtrusionLayer />);
+    await vi.waitFor(() => expect(fake.state.layers.has(DETAILED_LAYER_ID)).toBe(true));
+    expect(createBasemapLod2LayerMock).toHaveBeenCalled();
+    expect(fake.state.layout.get(DETAILED_LAYER_ID)?.visibility).toBe("visible");
+    expect(fake.state.layout.get(LAYER_ID)?.visibility).toBe("none");
+    expect(fake.state.layout.get(BUILDING_LAYER_ID)?.visibility).toBe("none");
+
+    act(() => {
+      fake.state.center = { lng: -73.9855, lat: 40.758 };
+      fake.emit("moveend");
+    });
+    expect(fake.state.layers.has(DETAILED_LAYER_ID)).toBe(false);
+    expect(fake.state.layout.get(LAYER_ID)?.visibility).toBe("visible");
+  });
+
+  it("keeps the extrusion fallback below z16 and outside Germany", async () => {
+    fake.state.center = { lng: 8.6821, lat: 50.1109 };
+    fake.state.zoom = 15;
+    useBuildingsStore.setState({ layerVisible: true });
+
+    render(<BuildingExtrusionLayer />);
+    await act(async () => Promise.resolve());
+
+    expect(createBasemapLod2LayerMock).not.toHaveBeenCalled();
+    expect(fake.state.layout.get(LAYER_ID)?.visibility).toBe("visible");
+
+    fake.state.zoom = 16;
+    fake.state.center = { lng: -73.9855, lat: 40.758 };
+    act(() => fake.emit("moveend"));
+    await act(async () => Promise.resolve());
+
+    expect(createBasemapLod2LayerMock).not.toHaveBeenCalled();
+    expect(fake.state.layout.get(LAYER_ID)?.visibility).toBe("visible");
+  });
+
+  it("falls back without hiding buildings when the detailed renderer fails", async () => {
+    fake.state.center = { lng: 8.6821, lat: 50.1109 };
+    createBasemapLod2LayerMock.mockRejectedValueOnce(new Error("renderer unavailable"));
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    useBuildingsStore.setState({ layerVisible: true });
+
+    render(<BuildingExtrusionLayer />);
+
+    await vi.waitFor(() => expect(warn).toHaveBeenCalledTimes(1));
+    expect(fake.state.layers.has(DETAILED_LAYER_ID)).toBe(false);
+    expect(fake.state.layout.get(LAYER_ID)?.visibility).toBe("visible");
+  });
+
   it("re-anchors after idle when the overlay is restored before its layer exists", () => {
     useBuildingsStore.setState({ layerVisible: true });
     render(<BuildingExtrusionLayer />);

integrations/overlay-3d-buildings/basemap-lod2.ts

@@ -0,0 +1,126 @@
+import type maplibregl from "maplibre-gl";
+
+export const BASEMAP_LOD2_TILESET_URL =
+  "https://sgx.geodatenzentrum.de/gdz_basemapde_3d_gebaeude/lod2_3857_null.json";
+export const BASEMAP_LOD2_RENDERER_URL =
+  "https://sgx.geodatenzentrum.de/gdz_basemapde_3d_gebaeude/Maplibre3DTiles.js";
+
+// BKG publishes the renderer at an unversioned URL. Pin the reviewed bytes so
+// activating the optional layer cannot silently execute changed third-party
+// JavaScript. If BKG updates it, the detailed layer fails closed to the normal
+// OpenMapTiles extrusion until this hash is reviewed and updated.
+export const BASEMAP_LOD2_RENDERER_INTEGRITY =
+  "sha384-q3pnK85xX/QxPjhFutyFScKvWMrmzh3pmdUcx19wM/zWhsLLbguExO88f2LpvmFd";
+
+export const BASEMAP_LOD2_MIN_ZOOM = 16;
+
+const RENDERER_SCRIPT_ID = "openmapx-basemap-de-3d-renderer";
+const GERMANY_BOUNDS = {
+  west: 5.5,
+  south: 47,
+  east: 15.5,
+  north: 55.2,
+} as const;
+
+export interface BasemapLod2Layer extends maplibregl.CustomLayerInterface {
+  /** Set to 1 by BKG's renderer after the root tileset is ready. */
+  loadStatus?: number;
+}
+
+interface BasemapLod2Renderer {
+  Mapbox3DTilesLayer: new (options: {
+    id: string;
+    url: string;
+    colorWall: string;
+    colorRoof: string;
+    colorBridge: string;
+  }) => BasemapLod2Layer;
+}
+
+declare global {
+  interface Window {
+    Mapbox3DTiles?: BasemapLod2Renderer;
+  }
+}
+
+let rendererPromise: Promise<BasemapLod2Renderer> | null = null;
+
+function rendererFromWindow(): BasemapLod2Renderer {
+  const renderer = window.Mapbox3DTiles;
+  if (!renderer?.Mapbox3DTilesLayer) {
+    throw new Error("basemap.de 3D renderer loaded without its layer constructor");
+  }
+  return renderer;
+}
+
+export function loadBasemapLod2Renderer(): Promise<BasemapLod2Renderer> {
+  if (window.Mapbox3DTiles?.Mapbox3DTilesLayer) {
+    return Promise.resolve(window.Mapbox3DTiles);
+  }
+  if (rendererPromise) return rendererPromise;
+
+  rendererPromise = new Promise<BasemapLod2Renderer>((resolve, reject) => {
+    const existing = document.getElementById(RENDERER_SCRIPT_ID) as HTMLScriptElement | null;
+    const script = existing ?? document.createElement("script");
+
+    const handleLoad = () => {
+      try {
+        resolve(rendererFromWindow());
+      } catch (error) {
+        rendererPromise = null;
+        script.remove();
+        reject(error);
+      }
+    };
+    const handleError = () => {
+      rendererPromise = null;
+      script.remove();
+      reject(new Error("Unable to load the integrity-pinned basemap.de 3D renderer"));
+    };
+
+    script.addEventListener("load", handleLoad, { once: true });
+    script.addEventListener("error", handleError, { once: true });
+
+    if (!existing) {
+      script.id = RENDERER_SCRIPT_ID;
+      script.src = BASEMAP_LOD2_RENDERER_URL;
+      script.integrity = BASEMAP_LOD2_RENDERER_INTEGRITY;
+      script.crossOrigin = "anonymous";
+      script.async = true;
+      document.head.append(script);
+    }
+  });
+
+  return rendererPromise;
+}
+
+export async function createBasemapLod2Layer(id: string): Promise<BasemapLod2Layer> {
+  const renderer = await loadBasemapLod2Renderer();
+  return new renderer.Mapbox3DTilesLayer({
+    id,
+    url: BASEMAP_LOD2_TILESET_URL,
+    colorWall: "#c8c4c0",
+    colorRoof: "#b86f63",
+    colorBridge: "#8f9094",
+  });
+}
+
+/**
+ * BKG's MapLibre tileset is Web Mercator, Germany-only, and expensive enough
+ * that its own example starts it at z16. Everywhere else the existing vector
+ * extrusion remains the correct low-cost fallback.
+ */
+export function supportsBasemapLod2View(map: maplibregl.Map): boolean {
+  if (map.getZoom() < BASEMAP_LOD2_MIN_ZOOM) return false;
+
+  const projection = map.getProjection?.();
+  if (projection?.type && projection.type !== "mercator") return false;
+
+  const center = map.getCenter();
+  return (
+    center.lng >= GERMANY_BOUNDS.west &&
+    center.lng <= GERMANY_BOUNDS.east &&
+    center.lat >= GERMANY_BOUNDS.south &&
+    center.lat <= GERMANY_BOUNDS.north
+  );
+}