Iwan7 - TileExport / JobAPI

Für den Export von Kartenbildern in Tilebasierte Formate steht eine eigene API zur Verfügung. Generell ähnelt der Aufruf dem einer "normalen" Zeichenanforderung. Allerdings ist das Ziel dann eine Datenbank, die in einem Hintergrundprozess befüllt wird.

Für cardo4 steht eine einfache Anwendung zur Verfügung, die diese JobAPI einfach zugänglich macht.

Ausgabeformate

Aktuell sind die Ausgabeformate GeoPackage© Raster und MBTiles verfügbar.

Iwan7 kann das Format OGC GeoPackage© (Tile) lesen, MBTiles z.Z. nicht.

Arbeitsweise

Je nach Anzahl der Level, Größe des Gebiets etc. ist die Tile-Erstellung ein sehr rechenintensiver und lang dauernder Vorgang.

Der Export läuft daher als Hintergrundjob innerhalb des Servers. Der eigentliche Zeichenvorgang wird dabei in Chunks aufgeteilt, die dann mit mehreren Threads abgearbeitet werden.

Im Idealfall wird der ausführende Server dann mit 100% CPU Last laufen. Sie sollten daher den Export besser außerhalb der Produktivzeiten durchführen, denken Sie dabei auch an die erhöhte Last auf den beteiligten Datenquellen, bspw. Datenbanken etc.

Datenablage

Jeder Job wird über eine eindeutige ID, die vorgegeben werden kann, bestimmt. Im eingestellten Projekt-tempDir wird ein Unterordner TileJobs erstellt. In diesem werden die Datenbanken als Dateien dann nach dem Schema JobId.<gpkg|mbtiles> gespeichert.

Die JobID darf demzufolge keine Zeichen enthalten, die nicht in einem Dateinamen zulässig sind.

Beachten Sie, dass die Datei sehr groß werden kann. Stellen Sie sicher, dass genügend freier Festplattenplatz verfügbar ist.

In der cardo Anwendung werden Schätzungen zu der zu erwartenden Dateigröße und Dauer ausgegeben. Die Genauigkeit der Ausgabe setzt einen gewissen Füllstand voraus, d.h. anfangs schwankt diese stark und stabilisiert sich mit dem Füllstand der Datenbank.

Sollte der Platz zur Neige gehen, kann der Job pausiert werden. Passen Sie dann das Temp-Verzeichnis an und verschieben die Dateien manuell. Dann starten Sie den Job wieder.


Endpunkte

json/tile/createjob | json/tile/calcjob | json/tile/getjobstate | json/tile/getjobdef | json/tile/canceljob | json/tile/removejob | json/tile/resumejob | json/tile/resetjob | json/tile/getalljobs | json/tile/getjobresultfile | json/tile/getjobresultfileinfo

Erstellen eines neuen Job

Endpunkt: /json/tile/createjob

Encoding: POST (application/json)

Erwartet wird eine Anforderung als MapRenderRequestTileExport

Die Antwort ist der TileJobState

Berechnen der Tiles zu einem Job

Endpunkt: /json/tile/calcjob

Encoding: POST (application/json)

Erwartet wird eine Anforderung als MapRenderRequestTileExport

Die Antwort ist der TileJobState

Abrufen des Status zu einem laufendem Job

Endpunkt: /json/tile/getjobstate

Encoding: GET

Erwartet wird der Parameter JobId

Ist der Job nicht vorhanden, wir null zurückgegeben, sonst ein TileJobState.

Abrufen der Definition eines Jobs

Endpunkt: /json/tile/getjobdef

Encoding: GET

Erwartet wird der Parameter JobId.

Ist der Job nicht vorhanden, wir null zurückgegeben, sonst ein MapRenderRequestTileExport.

Anhalten eines laufenden Jobs

Endpunkt: /json/tile/canceljob

Encoding: GET

Erwartet wird der Parameter JobId.

Sendet ein Abbruchsignal, evtl. dauert es noch eine Weile, bis der Job wirklich angehalten wurde.

Ist der Job nicht vorhanden, wir false zurückgegeben, sonst true.

Fortführen eines zuvor angehaltenen Jobs

Endpunkt: /json/tile/resumejob

Encoding: GET (application/json)

Erwartet wird der Parameter JobId.

Nimmt die Arbeit eines zuvor mit cancelJob angehaltenen Jobs wieder auf.

Ist der Job nicht vorhanden, wird ein Fehler ausgelöst, sonst ein TileJobState.

Löschen eines Jobs

Endpunkt: /json/tile/removejob

Encoding: GET

Erwartet wird der Parameter JobId.

Löscht den Job und die erstellten Daten.

Wenn der Job zu diesem Zeitpunkt aktiv ist, wird ein Fehler ausgelöst, sonst false, wenn der Job nicht vorhanden war oder true, wenn er gelöscht wurde.

Zurücksetzen eines Jobs

Endpunkt: /json/tile/resetjob

Encoding: GET

Erwartet wird der Parameter JobId.

Löscht die erstellten Daten des Jobs, behält aber die Definition bei (der Job kann damit neu gestartet werden).

Wenn der Job zu diesem Zeitpunkt aktiv ist, wird ein Fehler ausgelöst, sonst false, wenn der Job nicht vorhanden war oder true, wenn er gelöscht wurde.

Abrufen aller Jobs

Endpunkt: /json/tile/getalljobs

Encoding: GET (application/json)

Gibt ein TileJobState[] zurück.

Abrufen der Ergebnisdatei eines Jobs

Endpunkt: /json/tile/getjobresultfile

Encoding: GET

Erwartet wird der Parameter JobId

Liefert den Datenstrom (Download) der Datei, die vom Job produziert wurde. Ist der Job nicht vorhanden, hat noch keine Datei erstellt oder wenn der Job zu diesem Zeitpunkt aktiv ist, wird ein Fehler ausgelöst.

Abrufen von Informationen zur Ergebnisdatei eines Jobs

Endpunkt: /json/tile/getjobresultfileinfo

Encoding: GET

Erwartet wird der Parameter JobId.

Ist der Job nicht vorhanden, hat noch keine Datei erstellt, wird ein Fehler ausgelöst. Sonst ist die Antwort ein FileInfo:

{
 uint64_t length;

 Core::String filePath;
}

Formate

MapRenderRequestTileExport

siehe auch Basisklasse MapRenderRequest, abzüglich der Angaben width, height, mapScale***, und zu MapRenderLayer

struct MapRenderRequestTileExport : MapRenderRequest
{
/// <summary>
/// Optionales XML für das Tilematrix-Set.
/// So etwas: &lt;TileMatrixSet xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0.0" xmlns="http://www.opengis.net/wmts/1.0"&gt;
/// </summary>
std::unique_ptr<Core::String>tileMatrixSetXml;

/// <summary>
/// Wenn kein TileMatrixSetXml, dann hier die Min-Scale der Level (Große Zahl)
/// </summary>
Core::Optional<double>minOgcScale;

/// <summary>
/// Wenn kein TileMatrixSetXml, dann hier die Max-Scale der Level (kleine Zahl)
/// </summary>
Core::Optional<double>maxOgcScale;

/// <summary>
/// Name der Ergebnistabelle
/// </summary>
Core::String tableName;

/// <summary>
/// Beschreibung (bei GeoPackage)
/// </summary>
std::unique_ptr<Core::String>description;


/// <summary>
/// Der Anzeigename (des Jobs!)
/// </summary>
Core::String title;

/// <summary>
/// Format, MBTiles oder GPKG
/// </summary>
std::unique_ptr<Core::String>format;

/// <summary>
/// Image-Format, png oder jpeg
/// </summary>
std::unique_ptr<Core::String>imageFormat;
}

TileJobState

struct TileJobState
{
/// <summary>
/// Job-Id
/// </summary>
Core::String jobId;

/// <summary>
/// Job-Titel
/// </summary>
Core::String title;

/// <summary>
/// Job-Beschreibung
/// </summary>
Core::String description;

/// <summary>
/// Tile-Status, wird während isActive ist fortgeschrieben
/// </summary>
TileProgress tileState;

/// <summary>
/// Verbaler Status
/// </summary>
Core::String message;

/// <summary>
/// Zeitpunkt des Starts (des Threads!)
/// </summary>
Core::Datetime started{ Core::Datetime::Ctor::UtcNow };

/// <summary>
/// Zeitpunkt der Beendigung (des Threads!)
/// </summary>
Core::Optional<Core::Datetime> finished;

/// <summary>
/// true, wenn gerade als Thread läuft
/// </summary>
bool isActive;

/// <summary>
/// Laufzeit gesamt (aufsummiert)
/// </summary>
int64_t totalMilliseconds;

/// <summary>
/// Bytes erstellt (aufsummiert)
/// </summary>
int64_t bytesCreatedTotal;
}

Zuletzt geändert: 13.03.2024 12:40:13 (erstmals erstellt 22.12.2020)