TWeather

Opis

Komponent niewidoczny z palety „Maps”. Pobiera prognozę z serwera https://weather.imetroll.com/v1/forecast. Przyjmuje parametry od programisty, dokleja key= (ApiKey), wysyła GET, zwraca JSON w OnDataReady / DataJSON. Mapa z WeatherInfo=True rysuje ikonę + temperaturę na obszarze. Wykresy Chart.js nie są rdzeniem TWeather — używaj innych komponentów / własnego UI.

Moduł: MapCommon.Weather (+ Weather.Types / Area / Client / Colors / Overlay / AreaResolve) · Klasa bazowa: TComponent · Platformy: VCL + FMX

Demo na żywo

Dwa dema middleware: ikony+temp na obszarach z JSON; surowy JSON do aplikacji. Nakładka gradient + modal wykresów pozostaje jako przykład opcjonalny.

Funkcje

• Middleware: programista → TWeather (Request/RefreshAsync) → GET + key= → OnDataReady(JSON).
• Auth: RequireApiKey=True (domyślnie) blokuje pobranie bez klucza; serwer weather.imetroll.com wymaga ?key= na /v1/*.
• ForecastKind: wfkCurrent / wfkHourly / wfkDaily7 (mapuje Sections + ForecastDays).
• JSON: current (temp, wilgotność, wiatr speed+direction, UV, odczuwalna, nasłonecznienie: sunshine_duration [s] + shortwave_radiation [W/m²], weather_code, is_day, opady), hourly, daily (~7 dni; daily: shortwave_radiation_sum MJ/m²), pole icon.
• Map.WeatherInfo: True = mapa renderuje pogodę z JSON; False = ignoruje nakładkę/etykiety.
• Display (ikony): ShowAreaLabels, DensityMode (admin/grid/auto), LabelDensity (thin 0/1/2), IconMotion (static/pulse/wave), LabelChrome (tło / same etykiety), Opacity, ScaleFactor, MinScreenWidth, UseCustomIcons + CustomIcons (PNG).
• Interval / AutoRefreshMinutes — cykliczny Refresh (samodzielna aplikacja pogodowa bez Chart.js).
• Active = auto query: zaznaczenie obszaru na mapie (prostokąt → wakBBox, koło / wielokąt → wakPolygon) lub ApplyCoords(Lat, Lon[, RadiusKm]) (bez promienia = 1 punkt) → od razu RefreshAsync; stare zapytanie anulowane.
• Serwer area-scoped: GET weather.imetroll.com/v1/area (prostokąt / koło / punkt / area=) – siatka punktów w jednym zapytaniu, ten sam kontrakt co fly / boatsea.
• CreateWidget / CreateWidgetAtCentroid / CreateWidgetsForAreas: ikona+wartość w środku obszaru; treść z OnWidgetContent; WidgetStyle (border/text/bg/opacity).
• Ikona obszaru: NIE średnia kodów WMO — stany binarne potęgi 2 (WBS_CLEAR=1, WBS_SUN=2, WBS_CLOUDS=4, WBS_RAIN=8); suma głosów próbek w województwie (AreaBinaryVotes.SumBits); WinningBit → ikona; temp = średnia; widget w centroida.
• Display.DensityMode: admin (1 widget / jednostka + głosy ikony) | grid (MaxPoints/PointsPerAdmin) | auto (kraj=admin1, zoom-in=gęściej, punkt=1).
• Map.WeatherClickMode: drabinka zoom — kraj → województwo → punkt (gdy znikają granice); średnia obszaru + środek obszaru.
• Zdarzenia mapy: OnMapClick / Areas.OnAreaClick (lewy); prawy/long-press = edycja obszaru; programista sam woła TWeather.
• Opcjonalnie: gradient/piksele (ShowAreaLabels=False); Charts demoted (ShowOn* = False).
• Roadmap 2c (po middleware/ikonach, nie blokuje bieżącego API): (1) intensywność opadów + zachmurzenie jako gradient na kaflach/raster 2D; (2) na mapie 3D żywe chmury na wysokościach + warstwa deszczu razem z chmurami.
• TWeatherScene: animacja tła aplikacji — Weather.Scene / Scene.Weather; Scene tylko ApplyJSON (bez GET).

Właściwości

Zdarzenia

Metody

Przykłady

TWeather middleware + ikony + ScaleFactor

// Middleware: ApiKey wymagany; ForecastKind; ikony+temp na obszarach
// Map.WeatherInfo = True → mapa rysuje JSON; Display.ScaleFactor / MinScreenWidth
procedure TForm1.FormCreate(Sender: TObject);
begin
  Weather1.ApiKey := GetEnvironmentVariable('WEATHER_API_KEY'); // doklejane jako &key=
  Weather1.RequireApiKey := True;
  Weather1.ForecastKind := wfkDaily7;          // current / hourly / daily7
  Weather1.Area.Kind := wakRegion;
  Weather1.Area.RegionName := 'mazowieckie';
  Weather1.Interval := 30;                     // alias AutoRefreshMinutes (aplikacja cykliczna)
  TileMap1.Weather := Weather1;
  TileMap1.WeatherInfo := True;                // mapa ma rysować pogodę z JSON
  Weather1.Display.ShowAreaLabels := True;     // ikona + temperatura na obszarze
  Weather1.Display.IconMotion := wimPulse;     // wimStatic / wimWave
  Weather1.Display.LabelChrome := wlcIconLabelBackground; // lub wlcLabelsOnly
  Weather1.Display.Opacity := 0.95;
  Weather1.Display.ScaleFactor := 1.4;         // skalowanie ikon na większym ekranie
  Weather1.Display.MinScreenWidth := 768;      // poniżej = bez powiększania
  Weather1.OnDataReady := Weather1DataReady;
  Weather1.OnError := Weather1Error;
  Weather1.Request;                            // alias Refresh; lub RefreshAsync
end;

OnDataReady(JSON) / OnError

procedure TForm1.Weather1DataReady(Sender: TObject; const JSON: string);
begin
  MemoRaw.Text := JSON;   // current / hourly / daily + icon (jak odpowiedź serwera)
  // albo Weather1.DataJSON; ikony już na mapie gdy WeatherInfo + ShowAreaLabels
end;

procedure TForm1.Weather1Error(Sender: TObject; Kind: TWeatherErrorKind;
  const ErrorMessage: string);
begin
  Memo1.Lines.Add('TWeather: ' + ErrorMessage);  // wekUnauthorized bez ApiKey
end;

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

// Co wysłać DO TWeather → co wraca z serwera (middleware)
// 1) Programista ustawia: ApiKey/Key, ForecastKind, Area (lat/lon lub region), Parameters
// 2) TWeather buduje GET na https://weather.imetroll.com/v1/forecast?...&key=APIKEY
// 3) OnDataReady(JSON) / DataJSON — pola current/hourly/daily jak Open-Meteo

// Przykład URL (klucz zawsze na końcu):
// GET /v1/forecast?latitude=52.23&longitude=21.01
//   &current=temperature_2m,...,uv_index,wind_speed_10m,wind_direction_10m,
//            sunshine_duration,shortwave_radiation,is_day
//   &hourly=...&daily=...&forecast_days=7&timezone=auto&key=***

// JSON (skrót): current.temperature_2m, .weather_code, .apparent_temperature (feels-like),
//   .uv_index, .wind_speed_10m, .wind_direction_10m,
//   .sunshine_duration (nasłonecznienie [s]), .shortwave_radiation (W/m²),
//   .is_day; hourly.*; daily.* + shortwave_radiation_sum; + "icon"

Weather1.ForecastKind := wfkHourly;
Weather1.Area.Kind := wakPoints;
Weather1.Area.Points.Text := '52.23,21.01';
Weather1.RefreshAsync;

Zdarzenia mapy/obszaru

// Zdarzenia mapy/obszaru (programista obsługuje — TWeather nie jest modułem wykresów)
// Lewy klik obszaru:  TMapAreas.OnAreaClick
// Lewy klik mapy:     Map.OnMapClick
// Prawy / long-press: edycja obszaru gdy Areas.EditPopupEnabled (contextmenu / touch)
// Dblclick:           zaznaczanie poligonu w trybie rysowania mapy
//
// W handlerze: ustaw Area na punkt/region → Request/RefreshAsync → OnDataReady(JSON)
procedure TForm1.Areas1AreaClick(Sender: TObject; const SetId: string;
  const Lat, Lon: Double; const CountryISO2, FeatureName, PropertiesJSON: string);
begin
  Weather1.Area.Kind := wakPoints;
  Weather1.Area.Points.Text := Format('%.5f,%.5f', [Lat, Lon]);
  Weather1.RefreshAsync;
end;

Prezentacja: motion, chrome, custom PNG, skala

// prezentacja bez nowego zapytania
Weather1.Display.IconMotion := wimWave;
Weather1.Display.LabelChrome := wlcLabelsOnly;
Weather1.Display.ScaleFactor := 1.6;
Weather1.Display.MinScreenWidth := 600;
TileMap1.WeatherInfo := True;
Weather1.UpdateDisplay;

// własne PNG zamiast emoji (WMO code = URL / data:image/png;base64,…)
Weather1.Display.UseCustomIcons := True;
Weather1.Display.CustomIcons.Text :=
  '0=https://cdn.example/sun.png' + sLineBreak +
  '3=https://cdn.example/cloud.png';
Weather1.UpdateDisplay;

Parsowanie JSON middleware

// Middleware: OnDataReady(JSON) — surowy + pola
procedure TForm1.Weather1DataReady(Sender: TObject; const JSON: string);
var
  Root: TJSONValue;
  Cur: TJSONObject;
begin
  MemoRaw.Text := JSON;
  Root := TJSONObject.ParseJSONValue(JSON);
  try
    Cur := (Root as TJSONObject).GetValue('current') as TJSONObject;
    if Cur <> nil then
      Caption := Format('%.0f °C  %s', [
        Cur.GetValue('temperature_2m').AsDouble,
        (Root as TJSONObject).GetValue('icon').Value]);
  finally
    Root.Free;
  end;
end;

Ikona obszaru: głosy binarne (WBS_* / WinningBit)

// Ikona obszaru = głosy binarne (potęgi 2), NIE średnia kodów WMO
// WBS_CLEAR=1, WBS_SUN=2, WBS_CLOUDS=4, WBS_RAIN=8
procedure TForm1.ShowAreaIcon;
var
  Votes: TWeatherBinaryVotes;
  Win: Integer;
  TempC: Double;
  Icon: string;
begin
  // Weather1.Display.DensityMode := wdnmAdmin;  // 1 widget / województwo
  // po Refresh / OnDataReady:
  Votes := Weather1.Data.AreaBinaryVotes;          // lub AreaBinaryVotes(UsePointMask)
  Win := Votes.WinningBit;                         // remis: rain > clouds > sun > clear
  TempC := Weather1.Data.AverageCurrent(wpTemperature2m);
  Icon := WeatherBinaryStateIcon(Win, True, TempC); // = WeatherIconEmoji(WMO 0/1/3/61, …)
  Memo1.Lines.Add(Format(
    'CLEAR=%d SUN=%d CLOUDS=%d RAIN=%d SumBits=%d WinningBit=%d → %s %.0f°C',
    [Votes.Clear, Votes.Sun, Votes.Clouds, Votes.Rain, Votes.SumBits, Win, Icon, TempC]));
  // CreateWidgetAtCentroid używa tego samego: ikona=WinningBit, temp=średnia
  Weather1.CreateWidgetAtCentroid('mazowieckie');
end;

// Mapowanie WMO → bit (WeatherCodeToBinaryState):
//   0 → CLEAR, 1 → SUN, 2..48 → CLOUDS, ≥51 → RAIN
// AverageCurrent(wpWeatherCode) zwraca WMO zwycięskiego bitu (0/1/3/61), nie mean(codes).

Opcjonalne Charts (nie rdzeń)

// OPCJONALNIE — wykresy to inne komponenty / własne UI (Charts demoted)
Weather1.Charts.Enabled := True;
Weather1.Charts.ShowOnAreaClick := True;
Weather1.OnChartsRequest := Weather1ChartsRequest;

Active: zaznaczenie obszaru lub współrzędne → automatyczne zapytanie

Weather1.Active = True na mapie: wybór obszaru (przycisk nawigacji Zaznacz obszar, BeginAreaSelect; mysz lub palec, pan/drag mapy zablokowany) albo współrzędne (ApplyCoords / ApplyCoordsText / ApplyBounds) od razu wysyła zapytanie (RefreshAsync) do weather.imetroll.com. Zapytanie trwające dla starego obszaru jest porzucane / anulowane. Active = False → zmienia się tylko Area; zapytanie wywołujesz sam (Request).

Map.OnAreaSelected pozostaje Twoim zdarzeniem: TAircraft, TBoats i TWeather słuchają tej samej mapy równolegle (TMapCore.AddAreaSelectedListener, multicast) – jedno zaznaczenie może zasilić wszystkie trzy.

Weather1.Active := True;
Weather1.BeginAreaSelect;                      // rysuj na mapie → zapytanie
Weather1.ApplyCoords(52.23, 21.01, 40);            // współrzędne + promień [km] → zapytanie
if not Weather1.ApplyCoordsText(Edit1.Text) then ShowMessage('lat, lon[, km]');

weather.imetroll.com/v1/area – pogoda dla obszaru (GET)

GET https://weather.imetroll.com/v1/area?…&key= – pogoda dla obszaru (siatka punktów w jednym zapytaniu do Open-Meteo). Brak obszaru → HTTP 400; nigdy cały świat.

Delphi TWeather buduje siatkę po stronie klienta (GridResolutionKm, MaxPoints) i działa z każdym serwerem zgodnym z Open-Meteo; /v1/area służy aplikacjom HTML/JS i innym klientom.

Ikona obszaru (głosy binarne)

Przy DensityMode=admin / CreateWidgetAtCentroid / AreaAverage ikona nie jest średnią arytmetyczną weather_code (średnia 0 i 61 ≈ 30 — bez sensu). Zamiast tego:

1. Każdy punkt próbki w poligonie (województwo) dostaje jeden bit stanu: WBS_CLEAR=1, WBS_SUN=2, WBS_CLOUDS=4, WBS_RAIN=8 (mapowanie WMO: 0→clear, 1→sun, 2…48→clouds, ≥51→rain).
2. AreaBinaryVotes sumuje bity (SumBits) i liczy głosy per stan (Clear/Sun/Clouds/Rain).
3. WinningBit = stan z największą liczbą głosów (remis: rain > clouds > sun > clear) → emoji / WMO reprezentatywne (0/1/3/61).
4. Temperatura przy ikonie = zwykła średnia z próbek; pozycja = centroida poligonu (WeatherLabelAnchor).

API: TWeatherDataSet.AreaBinaryVotes, WeatherCodeToBinaryState, WeatherBinaryStateToWmoCode, WeatherBinaryStateIcon, AverageCurrent(wpWeatherCode) = WMO zwycięskiego bitu.

Votes := Weather1.Data.AreaBinaryVotes;
Win := Votes.WinningBit;                              // np. WBS_RAIN = 8
TempC := Weather1.Data.AverageCurrent(wpTemperature2m);
Icon := WeatherBinaryStateIcon(Win, True, TempC);
// CreateWidgetAtCentroid / PlaceMultiAreaWidgets robi to samo automatycznie
Weather1.Display.DensityMode := wdnmAdmin;
Weather1.CreateWidgetsForAreas;                       // 1 ikona / województwo

▶ Demo: Active + DensityMode=admin (głosy)

Kody WMO (weather_code)

Pole weather_code → WeatherIconEmoji / WeatherWmoCodeDesc. Rodzina UI: TWeatherScene, TWeatherHourStrip, TWeatherDayItems, TWeatherChart (AutoLink do TWeather, ApplyJSON na OnDataReady). Ikony: wbudowane albo UseCustomIcons + CustomIcons (code=url).

▶ Demo: popup Scene + pasek + dane

Pełna lista API

Generowana z deklaracji w kodzie (Source/*.pas): wszystkie opublikowane właściwości i zdarzenia TWeather (także dziedziczone), właściwości publiczne i metody publiczne.

Właściwości opublikowane (41)

Zdarzenia (7)

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

Metody publiczne (35)

Pełny opis wszystkich właściwości: dokumentacja komponentów map.

Zobacz też

VCLFMXniewidoczny

TWeatherPopup

Pełne okno prognozy (skórki iOS glass / Android / custom): nagłówek, pasek godzin, 7 dni i wykresy. Scene za szkłem.

▶ Demo na żywo

VCLFMXniewidoczny

TWeatherScene

Profesjonalna, realistyczna animacja tła aplikacji pogodowej (nie cartoon): dzień/noc, miękkie chmury, deszcz, słońce, wiatr, gwiazdy. Dane tylko z TWeather — Scene nigdy nie woła serwera.

▶ Demo na żywo

VCLFMXniewidoczny

TWeatherHourStrip

Pasek godzinowy prognozy (ikony WMO + temperatura). Wypełnia okno po danych z TWeather.

▶ Demo na żywo

VCLFMXniewidoczny

TWeatherDayItems

Prognoza 7 dni w kafelkach (ikona, min/max, opady). Część okna TWeatherPopup.

▶ Demo na żywo

VCLFMXniewidoczny

TWeatherChart

Wykresy pogodowe (temperatura, wilgotność, wiatr…). Serie z legendą w oknie prognozy.

▶ Demo na żywo

VCLkontrolka

TTileMapVCL

Mapa kafelkowa dla aplikacji Windows (VCL) – OpenStreetMap, zdjęcia satelitarne, mapa terenu.

▶ Demo na żywo

VCLkontrolka

T3DMapVCL

Mapa wektorowa 2D/3D z budynkami, motywem dziennym/nocnym i własnymi kaflami z mapa.imetroll.com.

▶ Demo na żywo

VCLFMXniewidoczny

T3DTerrain

Teren 3D (DEM) dla T3DMapVCL/FMX: rzeźba terenu całego świata z planet.pmtiles, „Pokaż wysokości” i etykiety m n.p.m.

▶ Demo na żywo

VCLFMXniewidoczny

TMapAreas

Granice admin-0/1/2 (ShowAdministrative), style per poziom, SettingsFile/AutoSave, cache GeoJSON.

▶ Demo na żywo