TBoats

Opis

Komponent niewidoczny z palety „Maps” – middleware jak TAircraft/TWeather, ale dla ruchu morskiego. Domyślny serwer https://boatsea.imetroll.com (proxy AIS Digitraffic + sample, auth key=). Mapa z BoatsInfo=True rysuje ruchome ikony statków (wbudowane SVG lub własne). Klik → TMapInfoWindow + przycisk Pokaż trasę → /v1/tracks + okno z wykresem prędkości. Alias typu: TShips = TBoats.

Moduł: MapCommon.Boats (+ Boats.Types / Client / Overlay) · Klasa bazowa: TComponent · Platformy: VCL + FMX

Demo na żywo

Live AIS (boatsea.imetroll.com + key=): Active + prostokąt/koło/współrzędne/area= → states; klik → info → Pokaż trasę → chart SOG.

Funkcje

• Middleware: Request/RefreshAsync → GET /v1/states + key= → OnDataReady(JSON) / setBoats.
• Obszar wymagany (jak fly): prostokąt lamin…lomax, koło lat/lon/radius_km lub area=gdansk. Brak → HTTP 400; nigdy cały świat.
• Active = auto query: zaznaczenie obszaru na mapie (prostokąt / koło) lub ApplyCoords(Lat, Lon[, RadiusKm]) → od razu RefreshAsync.
• Auth: RequireApiKey=True (domyślnie); bez ApiKey → bekUnauthorized; serwer 401 bez key=.
• Klasy statków z AIS: kontenerowiec, masowiec, tankowiec, chemikaliowiec, gazowiec, pasażerski, rybacki, okręt wojenny, straż, holownik, pilot, żaglowiec… → ikona + kolor + etykieta (tabela).
• Ikony: wg klasy (Display.TypeIcons, boatsea /static/ships/) albo wbudowane SVG / Display.IconDataURL (obrót po heading); Display.ClassFilter.
• Map.Boats / Boats.Map AutoLink; Map.BoatsInfo steruje rysowaniem.
• InfoWindow: klik statku → Title/Body; przycisk Pokaż trasę → ShowRouteAsync.
• Trasa: /v1/tracks?mmsi= → polyline na mapie + okno small/large z wykresem SOG (kn).
• Provider bpBoatseaProxy (live) / bpSample (demo).

Właściwości

Zdarzenia

Metody

Przykłady

TBoats + mapa + InfoWindow + key=

Boats1.ApiKey := GetEnvironmentVariable('BOATS_API_KEY'); // &key=
Boats1.RequireApiKey := True;
Boats1.BaseURL := 'https://boatsea.imetroll.com';
Boats1.Area.South := 53.5; Boats1.Area.West := 14;   // or Kind := bakRadius / AreaId := 'gdansk'
Boats1.Area.North := 55.5; Boats1.Area.East := 20.5;
Boats1.IntervalSec := 10;
TileMap1.Boats := Boats1;
TileMap1.BoatsInfo := True;
Boats1.InfoWindow := MapInfoWindow1;  // klik → Okno/Dymek
Boats1.OnBoatsClick := BoatsClick;
Boats1.OnRouteReady := BoatsRouteReady;
Boats1.Active := True;  // lub Boats1.Request;
// Active: zaznaczenie na mapie / współrzędne → zapytanie od razu
Boats1.BeginAreaSelect;                  // lub BeginAreaSelect(bakRadius)
Boats1.ApplyCoords(54.52, 18.65, 30);    // lat/lon/radius_km

Active: BeginAreaSelect / ApplyCoords / ApplyAreaId

// Active = True: zaznaczenie / współrzędne / ApplyAreaId → RefreshAsync od razu
Boats1.ApiKey := GetEnvironmentVariable('BOATS_API_KEY');
Boats1.RequireApiKey := True;
Boats1.BaseURL := 'https://boatsea.imetroll.com';
Boats1.UseMapAreaSelection := True;
Boats1.AutoRequestOnAreaSelect := True;
Boats1.ShowAreaOnMap := True;
Boats1.IntervalSec := 10;
TileMap1.Boats := Boats1;
TileMap1.BoatsInfo := True;
Boats1.InfoWindow := MapInfoWindow1;
Boats1.Active := True;

// A) rysuj na mapie (pan zablokowany) → GET /v1/states?lamin=… lub lat/lon/radius_km
Boats1.BeginAreaSelect;                 // prostokąt
Boats1.BeginAreaSelect(bakRadius);      // koło

// B) współrzędne
Boats1.ApplyCoords(54.52, 18.65, 30);   // Zatoka Gdańska, 30 km
Boats1.ApplyCoords(60.15, 24.95, 20);   // Helsinki – dobre pokrycie Digitraffic
if not Boats1.ApplyCoordsText(Edit1.Text) then
  ShowMessage('oczekiwano lat, lon[, km]');

// C) prostokąt / nazwany obszar z katalogu GET /v1/areas
Boats1.ApplyBounds(53.5, 14, 55.5, 20.5);  // lamin…lomax
Boats1.ApplyAreaId('gdansk');             // area=gdansk
Boats1.ApplyAreaId('finland-gulf');

Parametry Area + Display

// Parametry Area → query boatsea (zawsze wymagany obszar)
Boats1.Area.Kind := bakRectangle;   // → lamin lomin lamax lomax
Boats1.Area.South := 53.5; Boats1.Area.West := 14;
Boats1.Area.North := 55.5; Boats1.Area.East := 20.5;

Boats1.Area.Kind := bakRadius;      // → lat lon radius_km
Boats1.Area.CenterLat := 54.52;
Boats1.Area.CenterLon := 18.65;
Boats1.Area.RadiusKm := 30;

Boats1.Area.AreaId := 'gdansk';      // → area=gdansk (nadpisuje Kind przy ApplyAreaId)

// Display
Boats1.Display.Visible := True;
Boats1.Display.IconSize := 28;
Boats1.Display.ShowLabels := True;
Boats1.Display.AnimateMoves := True;
Boats1.RouteWindowSize := brwsLarge;
Boats1.RouteColor := '#00695C';
Boats1.Provider := bpBoatseaProxy;  // lub bpSample

OnDataReady – JSON ships[]

// OnDataReady — surowy JSON boatsea (ships[])
procedure TForm1.Boats1DataReady(Sender: TObject; const JSON: string);
var
  Root, Ships: TJSONValue;
  Arr: TJSONArray;
  I: Integer;
  O: TJSONObject;
begin
  MemoRaw.Text := JSON;
  Root := TJSONObject.ParseJSONValue(JSON);
  try
    Caption := Format('źródło %s · %d statków',
      [(Root as TJSONObject).GetValue('source').Value,
       (Root as TJSONObject).GetValue('count').AsInteger]);
    Arr := (Root as TJSONObject).GetValue('ships') as TJSONArray;
    for I := 0 to Arr.Count - 1 do
    begin
      O := Arr.Items[I] as TJSONObject;
      Memo1.Lines.Add(Format('%s  %s  sog=%.1f kn  %s',
        [O.GetValue('mmsi').Value,
         O.GetValue('name').Value,
         O.GetValue('sog').AsDouble,
         O.GetValue('destination').Value]));
    end;
  finally
    Root.Free;
  end;
end;

Klik i trasa

procedure TForm1.BoatsClick(Sender: TObject; const State: TBoatsState);
begin
  Memo1.Lines.Add(State.Name + ' ' + State.Mmsi);
end;

procedure TForm1.BtnShowRouteClick(Sender: TObject);
begin
  Boats1.ShowRouteAsync(LastMmsi); // trasa + wykres prędkości (SOG) na mapie
end;

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

Boats1.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 / ApplyAreaId) od razu wysyła zapytanie (RefreshAsync) do boatsea.imetroll.com/v1/states. 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.

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

boatsea.imetroll.com – GET (area-scoped jak fly)

GET https://boatsea.imetroll.com/v1/states?…&key= – statki tylko w żądanym obszarze (Digitraffic AIS; brak pokrycia → sample przefiltrowany, pole note). Brak obszaru → HTTP 400; nigdy cały świat. Auth: ?key= (jak weather/fly). Publiczne: /v1/health, /v1/areas.

GET /v1/states?lamin=53.5&lomin=14&lamax=55.5&lomax=20.5&key=YOUR_KEY
GET /v1/states?lat=54.52&lon=18.65&radius_km=30&key=YOUR_KEY
GET /v1/states?area=gdansk&key=YOUR_KEY
GET /v1/tracks?mmsi=230661000&time=0&key=YOUR_KEY
GET /v1/areas   // publiczny katalog

Pełna dokumentacja serwera: boatsea.imetroll.com · demo: ▶ TBoats Active + area=

Klasy statków z AIS: kontenerowiec, tankowiec, chemikaliowiec, rybacki, okręt…

Każdy statek dostaje klasę (TBoatsState.ShipClass, JSON ship_class) – ikona na mapie (obrót po heading), kolorowa etykieta, odznaka w oknie info i legenda w demo. Typ AIS (ITU-R M.1371) jest zgrubny (70 = cargo, 80 = tanker), więc kontenerowiec / masowiec / chemikaliowiec / gazowiec wynikają z cyfry ładunku niebezpiecznego (x1–x4 = kat. A–D) i nazwy statku; okręty i straż – z typu 35/55 albo prefiksu nazwy. Te same reguły ma serwer (ship_classes.py) i Delphi (BoatsClassifyShip – fallback, gdy serwer nie poda ship_class). Pole class_basis: ais | ais+name | ais+hazard | name | mmsi.

Ikona	ship_class	TBoatsShipClass	Etykieta	Źródło (AIS / MMSI / nazwa)
	container	bscContainer	Kontenerowiec	AIS 70–79 + nazwa armatora (MSC, MAERSK, CMA CGM, EVER…, CONTAINER/FEEDER)
	bulk	bscBulk	Masowiec	AIS 70–79 + nazwa (BULK, ORE, COAL, GRAIN)
	cargo	bscCargo	Statek towarowy	AIS 70–79
	tanker	bscTanker	Tankowiec	AIS 80–89
	chemical	bscChemical	Chemikaliowiec	AIS 81–84 (ładunek niebezpieczny kat. A–D) lub nazwa CHEM/STOLT/ODFJELL…
	gas	bscGas	Gazowiec (LNG/LPG)	AIS 80–89 + nazwa LNG/LPG/GAS
	passenger	bscPassenger	Pasażerski / prom	AIS 60–69
	hsc	bscHsc	Szybki (HSC)	AIS 40–49
	fishing	bscFishing	Rybacki	AIS 30
	military	bscMilitary	Okręt wojenny	AIS 35 lub prefiks nazwy ORP/HMS/HNLMS/FGS/USS…
	law	bscLaw	Straż / policja	AIS 55 lub nazwa KBV/SG/POLICE/COAST GUARD
	sar	bscSar	Ratowniczy (SAR)	AIS 51
	tug	bscTug	Holownik	AIS 31, 32, 52
	pilot	bscPilot	Pilotówka	AIS 50
	dredger	bscDredger	Pogłębiarka	AIS 33
	special	bscSpecial	Jednostka specjalna	AIS 34, 53, 54, 56–59
	sailing	bscSailing	Żaglowiec	AIS 36
	pleasure	bscPleasure	Rekreacyjny / jacht	AIS 37
	wig	bscWig	Ekranoplan (WIG)	AIS 20–29
	aton	bscAton	Znak nawigacyjny (AtoN)	MMSI 99xxxxxxx
	beacon	bscBeacon	SART / MOB / EPIRB	MMSI 970/972/974
	other	bscOther	Inny	AIS 90–99 / inne
	unknown	bscUnknown	Nieznany	brak typu AIS

// tylko tankowce, chemikaliowce i gazowce, etykieta = klasa
Boats1.Display.ClassFilter := [bscTanker, bscChemical, bscGas];
Boats1.Display.LabelField := blfShipClass;

procedure TForm1.Boats1BoatsClick(Sender: TObject; const S: TBoatsState);
begin
  Caption := S.Name + ' – ' + BoatsShipClassLabel(S.ShipClass) +
    IfThen(S.Hazard <> '', ' (ładunek niebezp. kat. ' + S.Hazard + ')', '');
end;

JSON: ships[].ship_class, ship_class_label, ship_class_label_en, ship_class_color, icon_url, hazard, ais_type_desc, class_basis, length_m, beam_m; katalog GET /v1/ship-classes?key=; ikony publiczne /static/ships/<klasa>.svg.

Pełna lista API

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

Właściwości opublikowane (19)

Zdarzenia (5)

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

Metody publiczne (19)

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

Zobacz też

VCLFMXniewidoczny

TAircraft

Middleware ADS-B: forma/mapa ↔ TAircraft ↔ fly.imetroll.com (GET + key=) → samoloty na mapie, InfoWindow, trasa + wykres wysokości.

▶ 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

TWeather

Middleware pogody: forma/mapa ↔ TWeather ↔ weather.imetroll.com (GET + key=) → JSON (current/hourly/daily7). Ikony+temp na obszarach; wykresy opcjonalne.

▶ Demo na żywo

VCLFMXniewidoczny

TGeoFencing

Strefy geograficzne (okręgi i wielokąty) ze zdarzeniami wejścia i wyjścia – osobny pakiet GeoFencing.

▶ Demo na żywo