Wrocław w 3D przez jeden weekend - case study wro3d.pl

Interaktywna, fotorealistyczna mapa 3D Wrocławia z wirtualną wycieczką i głosowym przewodnikiem - zbudowana w jeden weekend, bez frameworka i bez backendu. Ten projekt-ćwiczenie nauczył nas więcej o pracy z API Google, klonowaniu głosu i testowaniu z AI niż niejeden projekt komercyjny. Efekt można zwiedzać pod adresem wro3d.pl, a poniżej opisujemy, co zadziałało, co zaskoczyło i jakie wnioski zabieramy do projektów klienckich.

Punkt wyjścia

Pomysł był prosty: mapa 3D Wrocławia, po której można się przespacerować bez wychodzenia z przeglądarki. Dwanaście najważniejszych miejsc - od Rynku, przez Ostrów Tumski, po Halę Stulecia - z wirtualną wycieczką, która sama oprowadza po mieście.

Żadnego frameworka, żadnego backendu, żadnego procesu budowania. Czysty HTML, CSS i JavaScript - strona, którą można wgrać na dowolny hosting przez FTP. Cały projekt powstał w duecie z AI (Claude Code) w ciągu jednego weekendu.

Wersja pierwsza: mapa wektorowa

Zaczęliśmy od stacku w pełni open source: MapLibre GL JS plus darmowe kafelki wektorowe OpenFreeMap (dane OpenStreetMap). Budynki 3D powstały przez wytłaczanie obrysów z warstwy budynków - wysokość każdej bryły pochodzi wprost z danych OSM, więc Sky Tower faktycznie góruje nad miastem swoimi 212 metrami.

Do tego tryb nocny, zdjęcia satelitarne Esri jako podkład hybrydowy, suwak pochylenia kamery i wyszukiwarka miejsc oparta o Nominatim. Zero kluczy API, zero kosztów, pełna kontrola.

Ta wersja żyje do dziś pod adresem wro3d.pl/mapa.html - jako lżejsza alternatywa i fallback.

Zwrot akcji: fotorealistyczne 3D i pułapka EOG

Bryły wyciągnięte z obrysów robią wrażenie, ale prawdziwy efekt "wow" dają Photorealistic 3D Tiles Google - te same fotorealistyczne modele miast, które znacie z Google Earth. Wrocław jest w pełni pokryty: realne elewacje kamienic, detale katedry, drzewa, mosty.

I tu pierwsza poważna lekcja. Po założeniu klucza API i podpięciu billingu - błąd 403:

"Satellite tiles and 3D tiles are not available for your account and region."

Okazało się, że od lipca 2025 Google wyłączył Photorealistic 3D Tiles (Map Tiles API) dla kont z Europejskiego Obszaru Gospodarczego. Bez formularza, bez listy oczekujących - po prostu nie ma.

Na szczęście istnieje oficjalna furtka dla Europy: "3D Maps" w Maps JavaScript API, czyli komponent gmp-map-3d. Te same fotorealistyczne kafelki, tylko serwowane przez inny, dozwolony w EOG interfejs. Migracja wymagała przepisania logiki kamery, ale funkcjonalnie niczego nie straciliśmy.

Wniosek dla projektów komercyjnych: dostępność API Google bywa zależna od regionu rozliczeniowego i potrafi się zmienić z dnia na dzień. Warstwa mapowa powinna mieć fallback - u nas jest nim wersja wektorowa.

Kamera, która oprowadza

Serce projektu to wirtualna wycieczka: kamera dolatuje do zabytku, a następnie powoli krąży wokół niego (pełne okrążenie w około 2 minuty), podczas gdy lektor opowiada historię miejsca. Po zakończeniu nagrania - przelot do kolejnego przystanku.

Dwie ciekawostki implementacyjne:

• Wbudowana funkcja orbity Google (flyCameraAround) okazała się zawodna - parametr rounds jest przestarzały i ignorowany, przez co "orbita" kończyła się po dwóch sekundach. Rozwiązanie: własna pętla requestAnimationFrame, która płynnie inkrementuje kierunek kamery. Prostsze, przewidywalne, z pełną kontrolą prędkości.
• Podobnie z pochyleniem kamery: Map3DElement ignoruje bezpośrednie przypisanie właściwości tilt - działa tylko flyCameraTo. Takie rzeczy odkrywa się wyłącznie testując, nie czytając dokumentację.

Sterowanie wycieczką wygląda jak pilot odtwarzacza: pływający pasek na dole mapy z przyciskami start, pauza (ze wznowieniem narracji dokładnie od miejsca przerwania), przeskakiwaniem między przystankami i wyciszeniem. Na telefonie panel boczny chowa się automatycznie, więc pasek jest jedynym potrzebnym interfejsem.

Głos Romualda z ElevenLabs

Najbardziej "ludzki" element projektu powstał najszybciej. Opisy dwunastu zabytków czyta głos Romualda - współzałożyciela C3S - sklonowany w ElevenLabs. Kilka minut próbki wystarczyło, żeby wygenerować dwanaście naturalnie brzmiących nagrań lektorskich, których Romuald nigdy nie przeczytał na głos.

Techniczne spięcie audio z mapą jest trywialne: pliki MP3 (mono, około 1 MB każdy) nazwane po identyfikatorach zabytków, jeden obiekt Audio i zdarzenie ended, które steruje rytmem wycieczki - kolejny przystanek dopiero, gdy lektor skończy. Cała "magia" siedzi w jakości głosu, nie w kodzie.

Szczegóły, które robią różnicę

• Herb Wrocławia (SVG z Wikimedia Commons, domena publiczna) w nagłówku, faviconie i grafice OG - mała rzecz, a strona od razu wygląda "na swoją".
• Grafika Open Graph to prawdziwy zrzut fotorealistycznej mapy (Ostrów Tumski z lotu ptaka) z nałożonym brandingiem - generowany skryptem Playwright, więc po każdej większej zmianie można go odświeżyć jedną komendą.
• Ikony SVG w stylu Lucide zamiast emoji - spójny język wizualny panelu, przy zachowaniu emoji na znacznikach mapy, gdzie kolor poprawia czytelność.
• Cache busting przez wersjonowanie plików - banał, który oszczędza godziny tłumaczenia "a odśwież z Cmd+Shift+R".
• Bezpiecznik kosztowy: dzienne limity zapytań w konsoli Google ustawione tak, że przekroczenie darmowego progu jest fizycznie niemożliwe - mapa co najwyżej przestanie się ładować.

Testowanie bez klikania

Każda funkcja - orbita, pauza wycieczki, chowanie panelu na mobile, nawigacja między przystankami - była weryfikowana automatycznie w Playwright: skrypt otwiera stronę, klika, odpytuje stan kamery i sprawdza wynik. To właśnie testy wyłapały zarówno martwą orbitę Google, jak i subtelny race condition, w którym zaległy nasłuch animacji potrafił po cichu zabić świeżo wystartowaną wycieczkę.

W projekcie "na weekend" łatwo odpuścić testy. Nie warto - połowa błędów, które znaleźliśmy, była niewidoczna przy zwykłym klikaniu.

Podsumowanie

• Czas realizacji: jeden weekend
• Stack: HTML/CSS/JS (zero frameworków), Google Maps 3D, MapLibre GL, ElevenLabs, Playwright
• Backend: brak - statyczny hosting
• Koszty stałe: 0 zł przy ruchu do około 1000 sesji miesięcznie (darmowe progi Google)
• Efekt: wro3d.pl

Projekt-ćwiczenie, ale wnioski jak z produkcji: API bywają regionalnie kapryśne (miej fallback), dokumentacja bywa nieaktualna (testuj, nie wierz), a klonowany głos z ElevenLabs przesuwa poprzeczkę tego, co da się zrobić w weekend, o kilka poziomów.

Masz pomysł na podobne narzędzie dla swojego miasta, produktu albo biznesu? Odezwij się - takie rzeczy robimy na co dzień, nie tylko w weekendy.