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

The starting point for the generation of a large-format map is typically the map template. Initially, this should Template can be downloaded and unpacked. Then we recommend renaming the template directory to a descriptive name.

Create map:

The initially created map will often not yet meet expectations. Here starts the process of iterative revision.

Improve map:

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. It's recommended to work through the definition file (text editor) and to create the default map by applying the action sequence 'create, upload, order, state ... state, download'.

Program start

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

  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

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 "map objects"

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

Helper "map grid"

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).