Printmaps provides the universal cli client (command line interface client) "printmaps" for easy use of the web service. This allows the generation of a reproducible map in a very short time.

Download

The cli client (executable program) is available for various operating systems:

The cli client is a command-line application that must be executed in a terminal window.

Concept

In the most cases the initial generated map will not yet meet the expectations. Here begins the process of iterative revisions:

Often the improvements relate to the placement and presentation of custom map and data elements. For fast turn-around times it's recommended to use map style 'raster10'. This design only divides the map into 10x10 rectangles, but does not read any data from the database.

Definition file

The definition file 'map.yaml' contains all the parameters required for the creation of the map. With this file the map can be reproduced at any time. The understanding of the definition parameters is therefore essential. The action 'template' creates a fully functional, simple definition file. It's recommended to work through the definition file (text editor) and to create the default map by applying the action sequence 'create, order, state, download'.

Program start

If the cli client is started without arguments, it issues this usage informations:

Program:
  Name    : ../printmaps
  Release : 0.3.0 - 2018/12/04
  Purpose : Printmaps Command Line Interface Client
  Info    : Creates large-sized maps in print quality.

Usage:
  ../printmaps 

Example:
  ../printmaps create

Actions:
  Primary   : create, update, upload, order, state, download
  Secondary : data, delete, capabilities
  Helper    : template
  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
  template     : creates a template file for building a map
  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      : careates 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

How to start:
  - Start with creating a new directory on your local system.
  - Change into this directory and run the 'template' action.
  - This creates the default map definition file 'map.yaml'.
  - You have now a full working example for building a map.
  - Build the map in order to get familiar with this client.
  - Run the actions 'create', 'order', 'state' and 'download'.
  - Unzip the file and view it with an appropriate application.
  - Modify the map definition file 'map.yaml' to your needs.

Workflow

1. define map or download sample

2. create map

3. improve map

Primary actions

The primary actions are needed to create a map. They are described accordingly in the chapter "Workflow".

Secondary actions

The secondary actions are used to control the map data or to determine the characteristics of the service. In addition, a map can be deleted from the server.

Helper "template"

The auxiliary function "template" creates a definition file (map.yaml) for a sample map with many standard elements. The definition file can then be adapted to your own requirements.

Helper "map objects"

The helper function "passepartout" generates the definition of the map frame,     "rectangle" any rectangular box, and "cropmarks" so-called cutting marks.

Hilfsfunktionen "Kartengitter"

The auxiliary functions "latlongrid, utmgrid" allow the generation of map grids.     The helper functions generate GeoJSON files which can then be rendered as user objects on the map.

Helper "coordinate conversion"

The auxiliary functions "latlon2utm, utm2latlon" allow the conversion of coordinates.

Helper "lines"

The auxiliary functions "bearingline, latlonline, utmline" allow the generation of a line. Each helper generates a GeoJSON file which can then be rendered as a user object on the map. The helper functions are typically used to generate a scale bar.

Helper "miscellaneous"

The auxiliary function "runlua" provides an embedded Lua interpreter (5.1). This makes it possible to execute self-created Lua programs. This advanced function can, for example, generate definitions for the labeling of coordinate grids, or even generate the grid lines themselves. See also map examples.

Examples of use

Nearly every map has a map frame and a scale bar. Therefore, the use of the two auxiliary functions "passepartout" and "bearing line" will be explained below by way of example. In addition, the creation of a coordinate grid using the function "latlongrid" is shown.

Map frame

The auxiliary function "passepartout" creates a rectangular frame in the WKT format. The generated result can be used directly as a map frame and map edge.

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

Example

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)

The output "POLYGON ((0.0 ... 20.0))" describes the rectangle frame (Passepartout) and can be drawn as a polygon on the map. The output "LINESTRING (20.0 ... 20.0)" (inner) describes a rectangular line, which can be used as a dividing line between map area and map frame.

Scale bar

The generation of a length-appropriate scale bar represents a special challenge. The best method for this is to construct a line of defined length (e.g., 1000 meters). As a rule, the scale bar should run in a west-east direction. If "Web-Mercator" (EPSG: 3857) was chosen as the projection, the use of the auxiliary function "bearingline" is appropriate.

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

Example

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

The helper function generates a GeoJSON file "scalebar-1000.geojson". This file contains a line with an exact length of 1000 meters. The GeoJSON file can then be rendered to the map as a user object, the length of the scale bar being automatically adjusted to the map scale (e.g. 1:25000).

Coordinate grid

The auxiliary function "latlongrid" generates a coordinate grid consisting of latitude and longitude lines. Two files (latgrid.geojson, longrid.geojson) are created in GeoJSON format, which can be placed over the map as user data.

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

The coordinates of the two map corners are obtained by first creating the map in the desired size and scale as a test. As soon as the map generation is completed, the coordinates of the map corners are indicated by the command "printmaps state".

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

For the generation of the coordinate grid, it is recommended to choose the two corner points slightly larger than the map. Thus, suitable "smooth" values can be used for the grid lines.

printmaps latlongrid  53.4  9.9  53.6  10.1  0.01

Hints

The build of a map ("printmaps order") takes place in a parallel process. The command "printmaps state" can be used to determine the current build status.

The start of the build process is documented in the field "mapBuildStarted". When the process is complete, the "mapBuildCompleted" field is updated. The fields "mapBuildSuccessful" and "mapBuildMessage" indicate the success / failure of the build process.

The "printmaps state" command is to be executed repeatedly. The download of the map is only possible if / after the field "mapBuildSuccessful" has the value "yes".

Uploading ("printmaps upload") of user data is optional. This step must be executed before the build ("printmaps order"). It is only required if user data is to be additionally printed on the map. The names of the files to upload are defined in the map control file (map.yaml).