Printmaps stellt für die Nutzung des Webservices den universellen CLI-Client (Command Line Interface Client) "printmaps" zur Verfügung. Hiermit läßt sich in kurzer Zeit eine reproduzierbare Karte erzeugen.

Download

Der CLI-Client steht für verschiedene Betriebssysteme als ausführbares Programm zur Verfügung:

Der Client ist eine Kommandozeilenanwendung die in einem Terminalfenster ausgeführt werden muss.

Konzept

Ausgangspunkt für die Erzeugung einer großformatigen Karte ist typischerweise das Kartentemplate. Initial sollte somit das Template heruntergeladen und entpackt werden. Anschließend empfiehlt sich das Umbenennen des template-Verzeichnisses in einen beschreibenden Namen.

Erzeugen einer Karte:

In der Regel wird die initial erzeugte Karte noch nicht den Erwartungen entsprechen. Jetzt beginnt der Prozess der iterativen Überarbeitung.

Verbessern einer Karte:

Oft beziehen sich die Verbesserungen auf die Platzierung und Darstellung der benutzerdefinierten Karten- und Datenelemente. Schnelle Turn-Around-Zeiten ergeben sich bei Nutzung des Kartenstils 'raster10'. Dieser Stil teilt die Karte in 10x10 Rechtecke auf, liest jedoch keinerlei Kartendaten aus der Datenbank.

Definitionsdatei

Die Definitionsdatei 'map.yaml' enthält alle Parameter die für die Erzeugung der Karte erforderlich sind. Mittels dieser Datei kann die Karte jederzeit reproduziert werden. Das Verständnis der Definitionsparameter ist somit essentiell. Es empfiehlt sich die erzeugte Datei durchzuarbeiten (Texteditor) und über die Aktionsfolge 'create, upload, order, state ... state, download' zunächst die Templatekarte zu erzeugen.

Programmstart

Wird der CLI-Client ohne Argumente gestartet, gibt er eine Benutzungshife aus:

  Program:
  Name         : printmaps
  Release      : v0.6.0 - 2020/08/03
  Purpose      : Printmaps Command Line Interface Client
  Info         : Creates large-sized maps in print quality.

Usage:
  printmaps <action>

Example:
  printmaps create

Actions:
  Primary      : create, update, upload, order, state, download
  Secondary    : data, delete, capabilities
  Helper       : unzip
  Helper       : passepartout, rectangle, cropmarks
  Helper       : latlongrid, utmgrid
  Helper       : latlon2utm, utm2latlon
  Helper       : bearingline, latlonline, utmline
  Helper       : runlua

Remarks:
  create       : creates the meta data for a new map
  update       : updates the meta data of an existing map
  upload       : uploads a list of user supplied files
  order        : places a map build order
  state        : fetches the current state of the map
  download     : downloads a successful build map
  data         : fetches the current meta data of the map
  delete       : deletes all artifacts (files) of the map
  capabilities : fetches the capabilities of the map service
  unzip        : unzips the downloaded map file
  passepartout : calculates wkt passe-partout from base values
  rectangle    : calculates wkt rectangle from base values
  cropmarks    : calculates wkt crop marks from base values
  latlongrid   : creates lat/lon grid in geojson format
  utmgrid      : creates utm grid in geojson format
  latlon2utm   : converts coordinates from lat/lon to utm
  utm2latlon   : converts coordinates from utm to lat/lon
  bearingline  : creates geographic line in geojson format
  latlonline   : creates geographic line in geojson format
  utmline      : creates geographic line in geojson format
  runlua       : run lua 5.1 script for generating labels

Files:
  map.id       : unique map identifier
  map.yaml     : map definition parameters

How to start:
  - Download and unzip the 'template' map from 'printmaps-osm.de'.
  - Build the 'template' map by running the actions:
    'create', 'upload', 'order', 'state', 'download', 'unzip'
  - View the map with an appropriate application.
  - Modify the map definition file 'map.yaml' to your needs.

Workflow

Primäre Aktionen

Die primären Aktionen werden benötigt um eine Karte zu erzeugen. Sie sind im Kapitel "Workflow" entsprechend beschrieben.

Sekundäre Aktionen

Die sekundären Aktionen dienen der Kontrolle der Kartendaten oder zur Ermittlung der Eigenschaften des Services. Darüberhinaus kann eine Karte vom Server gelöscht werden.

Hilfsfunktionen "Kartenobjekte"

Die Hilfsfunktion "passepartout" erzeugt die Definition des Kartenrahmens, "rectangle" eine beliebige rechteckige Box, und "cropmarks" sogenannte Schneidemarken.

Hilfsfunktionen "Kartengitter"

Die Hilfsfunktionen "latlongrid, utmgrid" erlauben die Erzeugung von Kartengittern. Die Hilfsfunktionen generieren GeoJSON-Dateien die anschließend als Benutzerobjekte auf die Karte gerendert werden können.

Hilfsfunktionen "Koordinatenumrechnung"

Die Hilfsfunktionen "latlon2utm, utm2latlon" erlauben die Umrechnung von Koordinaten.

Hilfsfunktionen "Linien"

Die Hilfsfunktionen "bearingline, latlonline, utmline" erlauben die Erzeugung einer Linie. Jede Hilfsfunktion generiert eine GeoJSON-Datei die anschließend als Benutzerobjekt auf die Karte gerendert werden kann. Die Hilfsfunktionen werden typischerweise verwendet um einen Maßstabsbalken zu erzeugen.

Hilfsfunktion "Besonderes"

Die Hilfsfunktion "runlua" stellt einen eingebetteten Lua-Interpreter (5.1) zur Verfügung. Hiermit ist es möglich selbsterstellte Lua-Programme auszuführen. Diese fortgeschrittene Funktion kann zum Beispiel Definitionen für die Beschriftung von Koordinatengittern erzeugen, oder sogar die Gitterlinien selbst generieren. Siehe auch Kartenbeispiele.

Nutzungsbeispiele

Nahezu jede Karte verfügt über einen Kartenrahmen und einen Maßstabsbalken. Deshalb soll nachfolgend beispielhaft die Nutzung der beiden Hilfsfunktionen "passepartout" und "bearingline" erläutert werden. Ergänzend wird die Erzeugung eines Koordinatengitters mithilfe der Funktion "latlongrid" gezeigt.

Kartenrahmen

Die Hilfsfunktion "passepartout" erzeugt einen Rechteckrahmen im WKT-Format. Das erzeugte Ergebnis kann direkt als Kartenrahmen und Kartenrand verwendet werden. 

Usage:
  printmaps passepartout  width  height  left  top  right  bottom

Example:
  printmaps passepartout  420.0  594.0  20.0  20.0  20.0  20.0

Remarks:
  width = map width in millimeters
  height = map width in millimeters
  left = size of left border in millimeters
  top = size of top border in millimeters
  right = size of right border in millimeters
  bottom = size of bottom border in millimeters

Hints:
  useful to create the map frame

Anwendungsbeispiel

printmaps passepartout 420.0 594.0 20.0 20.0 20.0 20.0

well-known-text (wkt) as rectangle with hole (frame) (probably what you want) ...
POLYGON((0.0 0.0, 0.0 594.0, 420.0 594.0, 420.0 0.0, 0.0 0.0), (20.0 20.0, 20.0 574.0, 400.0 574.0, 400.0 20.0, 20.0 20.0))

well-known-text (wkt) as rectangle outlines (outer and inner) ...
LINESTRING(0.0 0.0, 0.0 594.0, 420.0 594.0, 420.0 0.0, 0.0 0.0)
LINESTRING(20.0 20.0, 20.0 574.0, 400.0 574.0, 400.0 20.0, 20.0 20.0)

Die Ausgabe "POLYGON((0.0 ... 20.0))" beschreibt den Rechteckrahmen (Passepartout) und kann als Polygon auf die Karte gezeichnet werden. Die Ausgabe "LINESTRING(20.0 ... 20.0)" (inner) beschreibt eine rechteckige Linie, die als Trennlinie zwischen Kartenbild und Kartenrahmen verwendet werden kann.

Maßstabsbalken

Die Erzeugung eines längengerechtes Maßstabsbalkens stellt eine besondere Herausforderung dar. Die hierfür beste Methode ist die Konstruktion einer Linie definierter Länge (z.B. 1000 Meter). In der Regel soll der Maßstabsbalken in West-Ost-Richtung verlaufen. Wurde als Projektion "Web-Mercator" (EPSG:3857) gewählt, so bietet sich die Nutzung der Hilfsfunktion "bearingline" an. 

Usage:
  printmaps bearingline  lat  lon  angle  length  linelabel  filename

Example:
  printmaps bearingline  51.98130  7.51479  90.0  1000.0  "1000 Meter" scalebar-1000

Remarks:
  lat = line start point in decimal degrees
  lon = line start point in decimal degrees
  angle = angle in degrees
  length = line length in meters
  linelabel = name of line
  filename = name of file (extension .geojson will be added)

Hints:
  useful to create a scalebar (webmercator)
  useful to create a declination line

Anwendungsbeispiel

printmaps bearingline 53.49777 9.93321 90.0 1000.0 "1000 Meter" scalebar-1000

Die Hilfsfunktion erzeugt eine GeoJSON-Datei "scalebar-1000.geojson". Diese Datei enthält eine Linie mit einer exakten Länge von 1000 Metern. Die GeoJSON-Datei kann anschließend als Benutzerobjekt auf die Karte gerendert werden, wobei die Länge der Maßstabsbalkens automatisch an den Kartenmaßstab (z.B. 1:25000) angepaßt wird.

Koordinatengitter

Die Hilfsfunktion "latlongrid" erzeugt ein Koordinatengitter bestehend aus Breitengrad- und Längengradlinien. Es werden zwei Dateien (latgrid.geojson, longrid.geojson) im GeoJSON-Format erzeugt, die als Benutzerdaten über die Karte gelegt werden können. 

Usage:
  printmaps latlongrid  latmin  lonmin  latmax  lonmax  distance

Example:
  printmaps latlongrid  53.4  9.9  53.6  10.1  0.01

Remarks:
  latmin lonmin = lower left / south west start point in decimal degrees
  latmax lonmax = upper right / north east end point in decimal degrees
  distance = grid distance in decimal degrees
  fractional digits of coord labels = fractional digits of grid distance

Hints:
  useful to create a geographic lat/lon grid

Die Koordinaten der beiden Kartenecken erhält man, indem zunächst die Karte in gewünschter Größe und Maßstab testweise erzeugt wird. Sobald die Kartenerzeugung abgeschlossen ist, werden die Koordinaten der Kartenecken über das Kommando "printmaps state" ausgewiesen. 

...
"MapBuildBoxWGS84": {
    "LonMin": 9.92010711546,
    "LatMin": 53.4925129255,
    "LonMax": 10.0470928845,
    "LatMax": 53.59921982
}
...

Für die Generierung des Koordinatengitters empfiehlt es sich, die beiden Eckpunkte etwas größer als die Karte zu wählen. So lassen sich für die Gitterlinien geeignete "glatte" Werte verwenden. 

printmaps latlongrid  53.4  9.9  53.6  10.1  0.01

Allgemeine Hinweise

Die Erzeugung einer Karte ("printmaps order") erfolgt in einem parallelen Prozess. Über das Kommando "printmaps state" kann der aktuelle Erzeugungsstatus ermittelt werden.

Der Start des Buildvorganges wird im Feld "mapBuildStarted" dokumentiert. Sobald der Vorgang abgeschlossen ist, wird das Feld "mapBuildCompleted" aktualisiert. Die Felder "mapBuildSuccessful" und "mapBuildMessage" signalisieren den Erfolg / Misserfolg des Buildvorganges.

Somit ist das Kommando "printmaps state" wiederholt auszuführen. Der Download der Karte ist nur möglich, nachdem das Feld "mapBuildSuccessful" den Wert "yes" aufweist.

Das Hochladen ("printmaps upload") von Benutzerdaten ist optional. Dieser Schritt ist vor dem Buildvorgang ("printmaps order") auszuführen. Er ist nur erforderlich, wenn Benutzerdaten zusätzlich auf der Karte angezeigt werden sollen. Die Namen der hochzuladenden Dateien werden in der Kartensteuerdatei (map.yaml) definiert.