Map Components for Delphi – dokumentacja (PL)

English version · strona pomocy: https://help.imetroll.com/

Komponenty map dla RAD Studio 12 Athens (VCL i FireMonkey) oparte na MapLibre GL JS: mapy kafelkowe (rastrowe), mapy wektorowe 3D z własnego serwera, edytor wyglądu, obszary GeoJSON (świat → kontynenty → kraje) i wymienni dostawcy wyszukiwania adresów.

Status: kod napisany dla RAD Studio 12, jeszcze nieskompilowany w Delphi. Testy jednostkowe części niezależnych od frameworka przechodzą pod FPC 3.2 (tests/fpc/run_fpc_check.py). Proszę zgłaszać błędy kompilacji z numerem linii.

Spis treści

1. Komponenty
2. Instalacja
3. Szybki start
4. Mapy kafelkowe TTileMapVCL / TTileMapFMX
5. Mapy 3D T3DMapVCL / T3DMapFMX
6. Punkt zerowy, marker główny, promień
7. Przyciski nawigacji
8. Wyszukiwanie adresów i dostawcy
9. Zaznaczanie obszaru i wyszukiwanie w obszarze
10. TEditMap – edycja wyglądu mapy 3D
11. TMapAreas – świat, kontynenty, kraje
12. TEditMapRaster – kafle rastrowe
13. Teren DEM i wysokości (T3DTerrain / T3DMap.Terrain)
    • 13a. TWeather – middleware pogody
    • 13b. TWeatherScene – animacja tła
    • Rodzina UI HourStrip / DayItems / Chart
14. Dokumentacja referencyjna
15. Przepisy
16. Migracja ze starej wersji
17. Ograniczenia i otwarte kwestie
18. Rozwiązywanie problemów

1. Komponenty

Paleta: Maps.

Wspólny rdzeń (MapCommon.Core) obsługuje wszystkie cztery mapy, więc mają one te same właściwości, metody i zdarzenia. Mapy 3D dodają tryb 2D/3D, motyw i EditMap.

2. Instalacja

1. Otwórz MapComponents.groupproj.
2. Zbuduj kolejno MapComponentsRT, MapComponentsVCL, MapComponentsFMX.
3. Zainstaluj MapComponentsDsgn (Win32, tylko design-time). Komponenty pojawią się na stronie palety Maps.
4. Dodaj Source do Library path albo do ścieżki projektu (dema kompilują się bezpośrednio ze źródeł).
5. Windows: obok EXE skopiuj WebView2Loader.dll o właściwej bitowości ($(BDS)\Redist\win32 lub win64). Wymagany jest WebView2 Runtime (w Windows 10/11 jest preinstalowany).

Dema (Demos): DemoTileVCL (kafelki, punkt zerowy, promień, obszar), Demo3DVCL (3D + TEditMap), DemoAreasVCL (TMapAreas), Demo3DTerritoryVCL / Demo3DTerritoryFMX (DEM + województwa), DemoSearchVCL (dostawcy), DemoFMX (FMX: kafelki + obszary, 3D + edytor).

3. Szybki start

Upuść TTileMapVCL (lub TTileMapFMX) na formularz, ustaw Align = alClient i uruchom. Jeżeli na formularzu leży TNominatimSearchProvider, TMapAreas albo TEditMap, mapa sama podłączy je do pustych właściwości SearchProvider, Areas, EditMap (AutoLinkComponents = True).

uses MapCommon.Types, MapCommon.MapVCL;

procedure TForm1.FormCreate(Sender: TObject);
begin
  TileMap1.Style := tmsOpenStreetMap;     // tmsSatellite, tmsTerrain
  TileMap1.ZeroLat := 52.2297;            // zero point (Home button)
  TileMap1.ZeroLon := 21.0122;
  TileMap1.Zoom := 13;
  TileMap1.SearchToken := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
end;

uses MapCommon.Types, MapCommon.MapFMX;

procedure TForm1.FormCreate(Sender: TObject);
begin
  TileMap1.Style := tmsOpenStreetMap;
  TileMap1.ZeroLat := 52.2297;
  TileMap1.ZeroLon := 21.0122;
  TileMap1.Zoom := 13;
  TileMap1.SearchToken := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
end;

4. Mapy kafelkowe TTileMapVCL / TTileMapFMX

Styl wybiera się z listy (Style: TTileMapStyle). Adresów kafelków nie ma w Inspektorze obiektów: własne źródło ustawia się tylko w kodzie (CustomTileURL, CustomAttribution, CustomTileMaxZoom) razem z Style := tmsCustom.

Warunki korzystania z kafelków (ważne przy wdrożeniu):

• OpenStreetMap (tile.openstreetmap.org): obowiązuje Tile Usage Policy OSMF – serwery są utrzymywane z darowizn, nie mają SLA; zabronione jest masowe pobieranie (prefetch, tryb offline), wymagany jest identyfikujący User-Agent/Referer i widoczna atrybucja. Przy dużym ruchu użyj komercyjnego dostawcy lub własnego serwera kafelków (tmsCustom).
• Esri World Imagery: bez klucza API wolno go używać tylko w ograniczonym zakresie (zgodnie z warunkami Esri, zasadniczo niekomercyjnie); do zastosowań komercyjnych potrzebne jest konto/licencja ArcGIS. Atrybucja Esri jest obowiązkowa.
• OpenTopoMap: dane OSM + SRTM, styl CC-BY-SA; serwis prywatny o ograniczonej przepustowości – nie nadaje się do intensywnego ruchu produkcyjnego.

5. Mapy 3D T3DMapVCL / T3DMapFMX

Mapa wektorowa z kafelkami z mapa.imetroll.com (styl liberty, 111 warstw). Wszystko, co mają mapy kafelkowe, plus tryb 2D/3D, pochylenie, budynki 3D i motyw dzień/noc. Kolorów nie edytuje się w samej mapie – służy do tego TEditMap podłączony przez Edit3D (alias EditMap).

Map3D.Style := m3sVector;             // own 3D vector tiles (mapa.imetroll.com)
Map3D.Mode := mm3D;                   // or Map3D.ToggleMode
Map3D.Pitch3D := 55;
Map3D.Theme := mtNight;
Map3D.Buildings3D := True;
// a style saved on the map server:
Map3D.ServerStyleName := 'moj-styl';
Map3D.Style := m3sServerStyle;
// custom URL - code only (public, not in the Object Inspector):
Map3D.CustomStyleURL := 'https://example.com/style.json';
Map3D.Style := m3sCustom;

StyleURL nie jest już publikowane. Jedynym „adresem” w Inspektorze pozostaje BoundariesURL (źródło danych granic, a nie styl) oraz SearchProviderURL (zapasowy adres wyszukiwarki).

6. Punkt zerowy, marker główny, promień

Punkt zerowy (ZeroLat, ZeroLon, domyślnie Warszawa 52.2297, 21.0122) to punkt odniesienia: przycisk Home leci do niego (HomeUsesZeroPoint), od niego liczone są odległości (MainMarkerDistanceFromZero, MainMarkerBearingFromZero, MainMarkerPixelOffsetFromZero – ta sama matematyka pikseli co w starym OSMMapViewer). Może mieć własną ikonę (ZeroIcon).

Marker główny – źródło MainMarkerSource:

Własny obrazek: MainMarkerIcon (TPicture w VCL, TBitmap w FMX; zapisywany jako PNG data-URL). Bez obrazka rysowana jest kropka (MainMarkerColor, MainMarkerBorderColor, MainMarkerSize, MainMarkerSquare, puls PulseEnabled/PulseColor).

Map.ZeroLat := 52.2297;
Map.ZeroLon := 21.0122;
Map.ZeroPointVisible := True;
Map.ZeroIcon.LoadFromFile('zero.png');          // TPicture (VCL) / TBitmap (FMX)
Map.MainMarkerSource := mmsDeviceLocation;      // GPS, falls back to the zero point
Map.MainMarkerIcon.LoadFromFile('pin.png');     // own image instead of the dot
Map.MainMarkerIconWidth := 32;
Map.MainMarkerIconHeight := 40;
Map.PulseEnabled := True;
ShowMessage(Format('%.0f m od punktu zerowego', [Map.MainMarkerDistanceFromZero]));

Promień – okrąg wokół markera głównego, punktu zerowego albo dowolnego punktu, z kolorami i kryciem wypełnienia i obrysu:

Map.RadiusCenter := rcMainMarker;
Map.RadiusMeters := 1500;
Map.RadiusColor := clRed;                // VCL TColor / FMX TAlphaColor
Map.RadiusFillOpacity := 0.12;
Map.RadiusLineColor := clMaroon;
Map.RadiusLineOpacity := 0.9;
Map.RadiusLineWidth := 2;
Map.RadiusLineStyle := mlsDashed;
Map.RadiusLabel := '1,5 km';
Map.RadiusVisible := True;

7. Przyciski nawigacji

Panel przycisków (NavVisible, NavPosition, NavOrientation, NavButtonSize) z kolekcją NavButtons. Każdy przycisk ma Kind, Visible, Hint, Icon (własna ikona) i Action.

Każde kliknięcie wywołuje OnNavButtonClick(Kind); z Action = nbaEventOnly wykonywane jest tylko zdarzenie.

// own icon and hint for a built-in button
with Map.NavButtons.Find(nbkHome) do
begin
  Icon.LoadFromFile('home.png');
  Hint := 'Wróć do punktu zerowego';
end;
// hide a button
Map.NavButtons.Find(nbkStyle).Visible := False;
// only the event, no built-in action
Map.NavButtons.Find(nbkMyLocation).Action := nbaEventOnly;
Map.NavPosition := bppTopRight;
Map.NavOrientation := bpoHorizontal;

8. Wyszukiwanie adresów i dostawcy

Mapa wyszukuje przez komponent wskazany w SearchProvider (automatycznie podłączany, jeśli leży na formularzu). Gdy jest pusty, używa wewnętrznego TNominatimSearchProvider z SearchProviderURL (domyślnie https://geoloc.imetroll.com) i SearchToken (nigdy nie zapisywany w DFM).

Walidacja przed zapytaniem (pre-flight): brak tokenu, zły format tokenu, niepoprawny URL, test /status przy pierwszym użyciu (wynik w LastCheck*), klasyfikacja błędów HTTP. Błędy trafiają do OnSearchError z rodzajem TMapProviderErrorKind i komunikatem PL/EN:

// drop TNominatimSearchProvider on the form: every map links it automatically
NominatimSearchProvider1.BaseURL := 'https://geoloc.imetroll.com';
NominatimSearchProvider1.Token := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
NominatimSearchProvider1.Language := 'pl';
NominatimSearchProvider1.CountryCodes := 'pl';
NominatimSearchProvider1.CheckConnection(
  procedure(Ok: Boolean; ErrorKind: TMapProviderErrorKind; const ErrorMessage, StatusJSON: string)
  begin
    if not Ok then
      ShowMessage(ErrorMessage);         // e.g. pekInvalidToken: "Token odrzucony (403)"
  end);
// any JSON geocoder
CustomUrlSearchProvider1.SearchURL := 'https://photon.komoot.io/api/?q={query}&limit={limit}&lang={lang}';
TileMap1.SearchProvider := CustomUrlSearchProvider1;

Zasady korzystania i licencja danych. Wyniki pochodzą z OpenStreetMap – licencja ODbL: w aplikacji musi być widoczna atrybucja „© OpenStreetMap contributors”, a udostępniane dalej bazy pochodne podlegają zasadzie share-alike. Publiczny serwer nominatim.openstreetmap.org ma własną politykę (maks. 1 zapytanie/s na całą aplikację, identyfikujący User-Agent, zakaz autouzupełniania i zapytań systematycznych, obowiązkowy cache). Komponent domyślnie używa własnej bramki geoloc.imetroll.com, ale adres jest konfigurowalny – zgodnie z polityką OSMF musi dać się zmienić bez aktualizacji programu. SearchLive (szukanie podczas pisania) włączaj tylko na własnym serwerze.

Limit zapytań po stronie klienta. TNominatimSearchProvider.MinRequestIntervalMs (domyślnie 1000 ms) ustawia zapytania w kolejce tak, by dostawca wysyłał najwyżej jedno żądanie HTTP na sekundę (sonda /status też się liczy) – nic nie jest odrzucane, kolejne wyniki po prostu przychodzą później. Po odpowiedzi 429 (pekRateLimited, zdarzenie OnError) następne żądanie wyjdzie dopiero po RateLimitBackoffMs (domyślnie 10000 ms). Dla TCustomUrlSearchProvider limit jest domyślnie wyłączony (0).

9. Zaznaczanie obszaru i wyszukiwanie w obszarze

AreaShape = masRectangle, masPolygon albo masCircle. Zaznaczanie zaczyna przycisk nbkSelectArea lub StartAreaSelection. Po zakończeniu: OnAreaSelected(Area), HasArea, Area. SearchInArea(Query) szuka wewnątrz obszaru (viewbox + filtr punkt-w-wielokącie), a z SearchOnAreaSelected = True zapytanie AreaSearchQuery uruchamia się samo.

Map.AreaShape := masPolygon;             // masRectangle, masCircle
Map.StartAreaSelection;                  // or the "select area" button
// ...
procedure TForm1.MapAreaSelected(Sender: TObject; const Area: TMapArea);
begin
  Map.SearchInArea('hydraulik');         // results -> OnSearchResults
end;

10. TEditMap – edycja wyglądu mapy 3D

Dziedziczenie Edit / Edit3D (jak InfoWindow): Edit = TEditMapRaster (mapy 2D/raster, Areas.EditPopupEnabled); Edit3D = TEditMap / TEdit3DMap (mapy 3D + teren). Właściwości: TileMap.Edit, Map3D.Edit3D (alias EditMap), Areas.Edit, Terrain.Edit3D. Szczegóły: docs/TEDIT_INHERITANCE_REQUIREMENTS.md.

TEditMap (w kodzie można używać nazwy TEdit3DMap) przechowuje zmiany wyglądu 111 warstw stylu: kolor, krycie, widoczność, szerokość linii i wartości zależne od zoomu. Zmiany są od razu stosowane na wszystkich podłączonych mapach (T3DMap*.Edit3D / EditMap) i ponownie po każdym wczytaniu stylu oraz po przeładowaniu strony.

• edycja: SetColor, SetPaintColor, SetOpacity, SetVisible, SetWidth, SetZoomStops, SetValueJSON, SetCategoryColor, SetCategoryVisible; odczyt Get*;
• BeginUpdate/EndUpdate – kilka zmian jako jeden krok cofania;
• Undo, Redo, CanUndo, CanRedo, UndoLimit;
• RestoreDefaults – powrót do DefaultSettingsFile (jeśli poprawny) lub fabrycznego wyglądu; można cofnąć, wywołuje OnRestoreDefaults;
• pliki: SettingsFile (wczytywany przy starcie, gdy AutoLoad = True), LoadFromFile, SaveToFile, LoadFromJSON, SaveToJSON, ShowOpenDialog, ShowSaveDialog;
• serwer: SaveToServer(Name, Password) (styl bazowy + zmiany → styles_api.php), LoadFromServer;
• okno edytora: ShowEditor (drzewo kategorii i warstw, kolor, krycie, szerokość, widoczność, Cofnij/Ponów, Przywróć domyślne, wczytaj/zapisz JSON).

W IDE: SettingsFile i DefaultSettingsFile mają przycisk „…” z oknem wyboru *.json; dwuklik na komponencie otwiera edytor, menu kontekstowe ma „Przywróć domyślne”. Ustawienia nie są zapisywane w DFM – edytor proponuje zapis do pliku SettingsFile.

Niepoprawny plik (zły JSON, nieznana warstwa, zły kolor, krycie poza 0..1) nie jest stosowany; lista błędów trafia do OnValidationError i LastErrors.

// T3DMapVCL1.EditMap := EditMap1 (automatic at design time)
EditMap1.SetColor('water', '#1a3a6b');
EditMap1.BeginUpdate;                    // one undo step
try
  EditMap1.SetColor('road_trunk_primary', '#ff9800');
  EditMap1.SetWidth('road_trunk_primary', 6);
  EditMap1.SetOpacity('road_trunk_primary', 0.9);
finally
  EditMap1.EndUpdate;
end;
EditMap1.SetCategoryVisible('etykiety', False);
EditMap1.Undo;
EditMap1.RestoreDefaults;                // undoable, OnRestoreDefaults
EditMap1.SaveToFile('map-settings.json');
EditMap1.ShowEditor;                     // window: tree, colour, opacity, width, undo/redo

EditMap1.SaveToServer('moj-styl', Password);   // asynchronous, OnSaved
// later, in any application:
T3DMapVCL1.ServerStyleName := 'moj-styl';
T3DMapVCL1.Style := m3sServerStyle;

procedure TForm1.EditMap1ValidationError(Sender: TObject; const Source: string; Errors: TStrings);
begin
  Memo1.Lines.Add('Plik ustawień odrzucony (' + Source + '):');
  Memo1.Lines.AddStrings(Errors);        // e.g. "layers.water.color: not a colour"
end;

Kategorie warstw (SetCategoryColor, SetCategoryVisible): tlo, teren, zielen, woda, lotniska, tunele, drogi, mosty, kolej, budynki, obiekty, granice, poi, etykiety, inne. Nazwy i opisy wszystkich 111 warstw: MapCommon.LayerInfo (MAP_LAYER_CATEGORIES, MAP_LAYERS).

11. TMapAreas – świat, kontynenty, kraje

Edycja obszaru na mapie (RMB / long-press): prawy klawisz myszy oraz na mobile długie przytrzymanie palcem (~500 ms, anulowane przy ruchu) otwierają to samo okno edycji stylu obiektu: kolor wypełnienia, kolor i grubość granicy, edytowalny tekst na środku (kolor, wielkość czcionki). Właściwość EditPopupEnabled (domyślnie True) wyłącza to okno — wtedy ani RMB, ani long-press nic nie otwierają. Strona: komenda mostu setAreasEditEnabled ({"enabled":false}).

Areas1.EditPopupEnabled := False;   // wyłącz popup edycji (np. tryb tylko do odczytu)
Areas1.EditPopupEnabled := True;    // RMB + long-press znowu otwierają edytor

Wymaganie (2026-10-05): po wyborze państwa na liście pojawia się lista jego jednostek administracyjnych (np. województwa PL, stany USA; analogicznie inne kraje).

TMapAreas wyświetla obszary GeoJSON na każdej podłączonej mapie (Areas). Wybór jest hierarchiczny:

WholeWorld = True          → cały świat: countries.geojson (258 krajów)
                             (WorldDetail = mwdProvinces → regiony admin-1 całego świata)
WholeWorld = False
  Continents = [ ... ]     → po jednym pliku *_full.geojson na zaznaczony kontynent,
                             z granicami krajów i regionami (ShowCountryOutlines / ShowRegions)
  Countries = 'PL,DE,CZ'   → opcjonalny filtr krajów (ISO alpha-2 lub alpha-3);
                             przy pustym Continents kontynenty dobierane są z krajów

Continents to zbiór (TMapAreaContinents) – w Inspektorze obiektów każdy kontynent ma własne pole wyboru, a przycisk „…” otwiera drzewo Świat › kontynenty › kraje z polami wyboru (to samo okno otwiera „…” przy Countries i dwuklik na komponencie). Zaznaczenie kontynentu zaznacza wszystkie jego kraje; zaznaczenie tylko części krajów zapisuje je w Countries.

Kontynenty (TMapAreaContinent) odpowiadają plikom na serwerze. Dlatego jest osobna Ameryka Środkowa i nie ma Antarktydy (jest tylko w pliku świata, WholeWorld). Wyliczenie TMapContinent (mcAuto, mcEurope …) z MapCommon.Types dotyczy routingu wyszukiwarki, a nie plików obszarów.

Pliki na serwerze – https://mapa.imetroll.com/geojson/ (wersja w versiongeojson.json, aktualizacja 2026-07-28):

Pliki pobiera Delphi (wątek w tle, Timeout), zapisuje w CacheFolder (domyślnie <cache>\MapComponents\geojson) i odświeża po zmianie versiongeojson.json (CheckVersion). Bez sieci używana jest kopia z cache. Do strony dane trafiają w porcjach po 256 KB, więc serwer nie musi mieć CORS.

MapAreas1.WholeWorld := True;            // countries.geojson (258 countries)
MapAreas1.WorldDetail := mwdCountries;   // mwdProvinces = admin-1 regions of the world

MapAreas1.WholeWorld := False;
MapAreas1.Continents := [macEurope, macAfrica];   // europe_full + africa_full
MapAreas1.ShowCountryOutlines := True;
MapAreas1.ShowRegions := True;                    // admin-1 regions inside the countries

MapAreas1.BeginUpdate;                   // one reload
try
  MapAreas1.Continents := [];            // derived from the countries
  MapAreas1.Countries := 'PL,CZ,SK';
finally
  MapAreas1.EndUpdate;
end;
MapAreas1.ShowCountry('PL');             // filter + zoom

Zdarzenia: OnAreaClick / OnAreaHover (HoverEvents) z kodem ISO kraju, nazwą i wszystkimi właściwościami obiektu, OnAreaLoaded (liczba obiektów lub błąd), OnValidationError (np. nieznany kod kraju, plik niebędący GeoJSON, współrzędne zamienione miejscami).

procedure TForm1.MapAreas1AreaClick(Sender: TObject; const SetId: string;
  const Lat, Lon: Double; const CountryISO2, FeatureName, PropertiesJSON: string);
begin
  Caption := FeatureName + ' (' + CountryISO2 + ')';
end;

Własne pliki: kolekcja Items (ścieżka lub URL, Countries, Style) oraz LoadFromFile, LoadFromURL, LoadFromString; wygląd hierarchii – HierarchyStyle (kolory CSS, krycie, grubość i styl linii, podświetlenie, etykiety LabelProperty np. name_pl, zakres zoomu).

Item := MapAreas1.LoadFromFile('C:\dane\strefy.geojson', 'Strefy dostaw');
Item.Style.FillColor := '#2e7d32';
Item.Style.FillOpacity := 0.2;
MapAreas1.FitToArea(Item);

Granice administracyjne (ShowAdministrative + AdminLevel)

Na serwerze map (mapa.imetroll.com/geojson/) są:

Areas1.ShowAdministrative := True;
Areas1.AdminLevel := malAdmin1;          // malCountry / malAdmin1 / malAdmin2
Areas1.Countries := 'PL';                // Polska → 16 województw
Areas1.ShowAdministrativeCountry('PL', malAdmin1);
// admin-2 (geoBoundaries):
Areas1.AdminLevel := malAdmin2;
Areas1.Admin2BaseURL := '';              // domyślny szablon GitHub gbOpen/{ISO}/ADM2/...
Areas1.Countries := 'PL';

Styl per poziom: CountryStyle, Admin1Style, Admin2Style (wypełnienie, obrys, grubość).

Kraj + granice w środku: przy AdminLevel = malAdmin1 (i malAdmin2) mapa pokazuje kontur państwa (CountryStyle, linia rysowana na wierzchu, co najmniej o 1 px grubsza) oraz granice jednostek admin wewnątrz (Admin1Style: własny kolor / grubość / LineStyle). Każde województwo jest osobnym obszarem (podświetlenie, OnAreaClick); kontur kraju z jednostkami w środku nie przykrywa ich wypełnieniem ani kliknięciem. Drabinka zoomu = okna MinZoom/MaxZoom stylów (te same, z których korzysta TWeather): poza oknem Admin1Style widać i wybiera się tylko kraj, w oknie – województwa.

Areas1.ShowAdministrativeCountry('PL');      // Polska + 16 województw
Areas1.CountryStyle.LineColor := '#1A237E';  // kontur państwa
Areas1.Admin1Style.LineColor := '#7E57C2';   // granice województw
Areas1.Admin1Style.MinZoom := 3.5;           // < 3,5: tylko kraj

Trwałość ustawień edytora (SettingsFile / AutoSave / AutoLoad)

JSON jak w TEditMap (format map-areas-settings v1):

{
  "format": "map-areas-settings",
  "version": 1,
  "countries": "PL",
  "showAdministrative": true,
  "adminLevel": "admin-1",
  "hierarchyStyle": { "fillColor": "#3B82F6", "lineColor": "#1D4ED8", "lineWidth": 1.5 },
  "levelStyles": {
    "country": { "fillColor": "#3B82F6", "lineWidth": 1 },
    "admin-1": { "fillColor": "#60A5FA", "lineWidth": 1.5 },
    "admin-2": { "fillColor": "#93C5FD", "lineWidth": 1 }
  }
}

Areas1.SettingsFile := 'areas-settings.json';
Areas1.AutoLoad := True;    // przy otwarciu formularza
Areas1.AutoSave := True;    // po każdej zmianie właściwości / stylu

Strona HTML dodatkowo zapisuje opcje zestawów w localStorage (mapcomponents.areas.settings.v1). Opcjonalnie można trzymać ten sam JSON w bazie / na serwerze (np. endpoint jak TEditMap.SaveToServer) — komponent tego nie wymusza.

12. TEditMapRaster – kafle rastrowe {#editmapraster}

TEditMapRaster to host Edit (2D). Łączy się z TTileMap* (Map / TileMap.Edit, AutoLinkComponents). EditPopupEnabled dziedziczą powiązane TMapAreas (Areas.Edit).

Raster1.Map := TileMap1;                                 // lub AutoDetect
Raster1.UrlTemplate := 'https://tile.example.com/{z}/{x}/{y}.png?key={apikey}';
Raster1.ApiKey := GetEnvironmentVariable('MAP_TILE_KEY'); // doklejane automatycznie
Raster1.ProxyURL := 'http://127.0.0.1:8090';              // opcjonalnie
Raster1.StyleName := 'night';                             // bez przeładowania mapy
Raster1.ApplyBuiltinStyle(mrsGoogleLike);
Raster1.LocalStore := True;                              // IndexedDB first, then server
Raster1.RefreshTile(12, 2273, 1383);                     // cache-bust + drop local

Przykład konfiguracji JSON (ConfigFile):

{
  "format": "map-raster-config",
  "version": 1,
  "urlTemplate": "https://{s}.tiles.example.com/{z}/{x}/{y}.png?key={apikey}",
  "apiKey": "DEMO-KEY",
  "cacheFolder": "",
  "proxyURL": "http://127.0.0.1:8090",
  "defaultStyle": "night"
}

Przykład stylu JSON:

{
  "format": "map-raster-style",
  "version": 1,
  "name": "night",
  "brightness": 0.7,
  "contrast": 1.1,
  "saturation": 0.55,
  "cssFilter": "brightness(0.700) contrast(1.100) saturate(0.550)",
  "colorMap": {
    "pairs": [
      { "from": "#F2EFE9", "to": "#1A2332", "tolerance": 18 },
      { "from": "#AAD3DF", "to": "#0B1A2A", "tolerance": 24 }
    ]
  }
}

Lokalny magazyn: IndexedDB w stronie; SQLite MBTiles-like (tiles + kolumna modified) w folderze danych aplikacji (StoreFile / CacheFolder). Kolejność: lokalnie → serwer/proxy.
Uwaga na politykę OSM i ToS Google/Apple — zob. tools/server/README.md.

13. Teren DEM i wysokości (T3DTerrain / T3DMap.Terrain) {#terrain}

Komponent palety T3DTerrain (MapCommon.Terrain, pakiet RT, paleta Maps) oraz właściwość zagnieżdżona Terrain na T3DMapVCL / T3DMapFMX (MapLibre raster-dem + setTerrain) pokazują prawdziwą wysokość terenu w metrach n.p.m. dla całego świata. Po włączeniu Enabled mapa 3D wznosi się według DEM; „Pokaż wysokości” (ShowElevation) odczytuje wysokość pod kursorem / kliknięciem (OnElevation) i pozwala oznaczyć punkty (ShowElevationSpots). Styl satelitarny m3sSatelliteHybrid na mapach 3D pozostaje.

T3DTerrain – powiązania (auto-link)

Gdy T3DTerrain zostanie powiązany z mapą 3D (i opcjonalnie z TEditMap), teren 3D włącza się automatycznie (Enabled := True + ApplyToMap). Nested T3DMap*.Terrain nadal działa bez osobnego komponentu.

Widok samodzielny: T3DTerrainVCL / T3DTerrainFMX (paleta Maps) to mapa 3D z domyślnym terenem (EditSubjectKind = eskTerrain) – EditMap może się do niej podłączyć bez osobnego T3DMap*. Gdy na formie jest też T3DMap*, jedno TEditMap wystarczy: EditSubject przełącza edycję warstw mapy (eskMapLayers) vs opcji terenu (eskTerrain); metody SetTerrainContourLines / SetTerrainElevationLabels / SetTerrainHillshade / SetTerrainObjectElevation ustawiają nakładki niezależnie (tylko etykiety, tylko linie, obie, żadna).

Etykiety wysokości i poziomnice są niezależne. Budynki i POI pozostają na DEM; przy ShowObjectElevation klik odczytuje teren / wysokość obiektu / dach (OnObjectElevation).

Źródło DEM (Mapterhorn planet.pmtiles)

Domyślne źródło (MAP_DEM_DEFAULT_URL):

pmtiles://https://mapa.imetroll.com/terrain/planet.pmtiles

Archiwum Mapterhorn (~331 GB, kafle WebP 512 px, kodowanie Terrarium, zoom 0–12), serwowane z CORS i Range. MapLibre ładuje je jako raster-dem przez protokół pmtiles:// (url: źródła, bez dopisywania /{z}/{x}/{y}). Biblioteka PMTiles JS (MAP_DEFAULT_PMTILES_JS / PMTilesJSURL) jest doklejana automatycznie, gdy SourceURL zaczyna się od pmtiles://.

• Kafle do zoom ≤ 12 – planet.pmtiles (cały świat); powyżej MapLibre overzoomuje z12.
• Wyższe zoomy (ścieżki, stoki) – regionalne 6-x-y.pmtiles z rodziny Mapterhorn.
• TileBuffer dotyczy źródeł http(s) XYZ; przy pmtiles:// ustaw 0.

{ Preferowane: komponent palety (auto-link + auto-enable) }
Terrain1.Map := Map3D;           // lub AutoLinkComponents na formie
Terrain1.EditMap := EditMap1;    // opcjonalnie
Terrain1.Exaggeration := 1.5;
Terrain1.ShowElevation := True;
Terrain1.OnElevation := TerrainElevation;
Terrain1.ShowElevationSpots([49.2510], [19.9338], ['Giewont']);

{ Albo nested właściwość mapy: }
Map3D.Terrain.SourceURL := MAP_DEM_DEFAULT_URL;  // bez /{z}/{x}/{y}
Map3D.Terrain.Encoding := mteTerrarium;
Map3D.Terrain.TileBuffer := 0;
Map3D.Terrain.ShowElevation := True;
Map3D.Terrain.Enabled := True;

Strona pomocy: T3DTerrain.

Demo na żywo (HTML): help.imetroll.com/demo/t3dterrain.html – ta sama strona mapy co w komponencie, z przełącznikami Exaggeration / etykiety / poziomnice / hillshade / wysokości obiektów i przelotami Tatry–Alpy–Himalaje.

Demo Delphi: Demos/Demo3DTerritoryVCL, Demos/Demo3DTerritoryFMX.

13a. TWeather – middleware pogody

TWeather (moduł MapCommon.Weather, paleta Maps) to middleware między formularzem/mapą a serwerem https://weather.imetroll.com/v1/forecast — nie moduł wykresów. Przyjmuje parametry od programisty, dokleja key= (ApiKey / Key, ApiKeyParam='key'), wysyła GET, zwraca JSON w OnDataReady(JSON) / DataJSON. Wykresy Chart.js są opcjonalne (Charts, domyślnie wyłączone).

Co wysłać / co wraca (I/O)

Pola (m.in.): temperatura, wilgotność, UV (uv_index), wiatr (wind_speed_10m + wind_direction_10m), odczuwalna (apparent_temperature), dzień/noc (is_day), opady, nasłonecznienie: sunshine_duration [s] oraz shortwave_radiation [W/m²] (daily: shortwave_radiation_sum [MJ/m²]).

Serwer wymaga ?key= na /v1/* (HTTP 401 bez klucza). Komponent bez ApiKey → wekUnauthorized.

Mapa i prezentacja

DensityMode (AM HTML centroid + średnia):

• admin — jeden widget na widoczną jednostkę administracyjną (PL ~16 województw; wewnątrz stanu gęstsze podziały); temperatura = średnia z próbek; ikona obszaru NIE jest średnią kodów WMO — stany binarne jako potęgi dwójki (WBS_CLEAR=1, WBS_SUN=2, WBS_CLOUDS=4, WBS_RAIN=8), suma głosów próbek w poligonie (AreaBinaryVotes.SumBits), WinningBit → ikona; widget w centroida (WeatherLabelAnchor = turf.centroid jeśli w środku, inaczej punkt wewnętrzny).
• grid — widgety na siatce próbek, limit MaxPoints / PointsPerAdmin.
• auto — wg zoomu / WeatherClickTarget: kraj = liczba admin1; zoom w admin = gęstsza siatka; place/punkt = 1 widget.

Votes := Weather1.Data.AreaBinaryVotes;
Win := Votes.WinningBit;   // remis: rain > clouds > sun > clear
Icon := WeatherBinaryStateIcon(Win, True, Weather1.Data.AverageCurrent(wpTemperature2m));
// AverageCurrent(wpWeatherCode) = WMO zwycięskiego bitu (0/1/3/61), nie mean(codes)
Weather1.Display.DensityMode := wdnmAdmin;
Weather1.CreateWidgetsForAreas;

Zdarzenia mapy (programista obsługuje): Map.OnMapClick, TMapAreas.OnAreaClick (lewy); prawy/long-press = edycja obszaru gdy EditPopupEnabled. Pozostałe właściwości zapytania: Sections, GridResolutionKm, MaxPoints, ForecastDays, PastDays, Timezone, TemperatureUnit, WindSpeedUnit, PrecipitationUnit, Models, CacheTTLSeconds, TimeoutMs, MaxRetries, MaxPointsPerRequest, MinRequestIntervalMs. Zdarzenia dodatkowe: OnProgress, OnResolveArea, OnChartsRequest (opcjonalne). Metody: Request / Refresh / RefreshAsync, DataJSON, UpdateDisplay, ClearDisplay, DetectLinkedComponents, ChartsJSON / ChartsJSONAt, HourlySeries / HourlySeriesAt.

Weather1.ApiKey := GetEnvironmentVariable('WEATHER_API_KEY');
Weather1.ForecastKind := wfkDaily7;
Weather1.Area.Kind := wakRegion;
Weather1.Area.RegionName := 'mazowieckie';
TileMap1.WeatherInfo := True;
Weather1.Display.ShowAreaLabels := True;
Weather1.Display.ScaleFactor := 1.4;
Weather1.Display.MinScreenWidth := 768;
Weather1.OnDataReady := Weather1DataReady;  // procedure(..., const JSON: string)
Weather1.Request;

Roadmap 2c (po middleware / ikonach — nie blokuje bieżącego API)

1. 2D / kafle: gradient zachmurzenia i intensywności opadów na tile/raster.
2. 3D: żywe chmury na wysokościach + warstwa deszczu razem z chmurami.

Demo: https://help.imetroll.com/demo/tweather-icons.html · https://help.imetroll.com/demo/tweather-click-point.html

Powiązanie ze sceną / UI: Weather.Scene ↔ Scene.Weather; Weather.Header ↔ TWeatherHeader; HourStrip / DayItems / Popup — AutoLink. Scene i widoki nie wołają serwera — tylko ApplyJSON / OnDataReady / DataJSON.

13b. TWeatherScene – animacja tła aplikacji pogodowej

TWeatherScene (MapCommon.Weather.Scene, paleta Maps) to lekka scenografia tła (dzień/noc, chmury, deszcz, słońce, wiatr, gwiazdy) za panelami z danymi. Nie jest mapą i nie woła weather.imetroll.com.

Presety: wspAuto, wspClear, wspPartlyCloudy, wspOvercast, wspRain, wspNightClear, wspNightCloudy.

Właściwości: Weather, Host, AutoLinkComponents, Active, Preset, Options (Animated, ShowStarsAtNight, IntensityScale, SoftClouds), IsDay, CloudCover, PrecipIntensity, WindDirectionDeg, WindSpeedMs, SunVisible, StarsVisible, Overcast. Publiczne: LastSceneJSON, SceneJSON, ApplyJSON, ApplyFromWeather, RefreshHost, Clear, DetectLinkedComponents. Zdarzenia: OnStateChanged.

Rodzina UI (AutoLink tylko do TWeather)

Upuść na formę obok TWeather — rejestrują się przez RegisterLinkedView i wypełniają się na OnDataReady (bez GET):

Ikony: WeatherIconEmoji / WeatherWmoCodeDesc / WeatherCustomIconUrl. Tabela kodów WMO: help komponenty/tweather.html#kody-wmo.

Demo: https://help.imetroll.com/demo/tweather-area-popup.html

14. Dokumentacja referencyjna

Tabele generowane są z tej samej specyfikacji co kod (tools/gen_components.py).

14.1 Właściwości wspólne (wszystkie cztery mapy)

Dodatkowo: MainMarkerIcon, ZeroIcon (TPicture / TBitmap), NavButtons, SearchProvider, Areas, AutoLinkComponents; VCL: WebView2UserDataFolder, WebView2BrowserFolder, DevToolsEnabled, OpenLinksExternally; FMX: BridgeTransport.

14.2 Kolory

14.3 Tylko mapy 3D

Plus Style: TMap3DStyle i EditMap: TEditMap. Mapy kafelkowe mają Style: TTileMapStyle.

14.4 Właściwości publiczne (tylko w kodzie)

CustomTileURL, CustomAttribution, CustomTileMaxZoom (kafelki), CustomStyleURL (3D), Core, Browser, IsMapReady, View, MarkerCount, LastResults, Area, HasArea.

14.5 Zdarzenia

Tylko mapy 3D:

14.6 Metody

Tylko mapy 3D:

Oraz AddMarker(Id, Lat, Lon, Color, Title, PopupText) i AddMarker(Id, Lat, Lon, Icon, …), Reload, DetectLinkedComponents.

14.7 Pełne API wszystkich komponentów (generowane z kodu)

Poniższe tabele są generowane z deklaracji w Source/*.pas (tools/api_ref.py) – zawierają każdą opublikowaną właściwość i zdarzenie (także dziedziczone), właściwości publiczne i metody publiczne.

TTileMapVCL (MapCommon.MapVCL)

Właściwości opublikowane

Zdarzenia

Właściwości publiczne (tylko w kodzie)

Metody publiczne

TTileMapFMX (MapCommon.MapFMX)

Właściwości opublikowane

Zdarzenia

Właściwości publiczne (tylko w kodzie)

Metody publiczne

T3DMapVCL (MapCommon.MapVCL)

Właściwości opublikowane

Zdarzenia

Właściwości publiczne (tylko w kodzie)

Metody publiczne

T3DMapFMX (MapCommon.MapFMX)

Właściwości opublikowane

Zdarzenia

Właściwości publiczne (tylko w kodzie)

Metody publiczne

TEditMap (MapCommon.EditMap)

Właściwości opublikowane

Zdarzenia

Właściwości publiczne (tylko w kodzie)

Metody publiczne

TEditMapRaster (MapCommon.EditMapRaster)

Właściwości opublikowane

Zdarzenia

Metody publiczne

TMapAreas (MapCommon.Areas)

Właściwości opublikowane