Map Layers

The map layers are the geospatial data types supported by Mapfish Print. Map layers are typically defined in the request JSON as part of the map attribute. Since map layers are essentially attribute data specific to the map attribute, they follow the same pattern as all other attributes in that they have attribute values.

The documentation below describes each map layer listing its required and optional attributes. Here is an example of a map attribute with map layers defined.

Example request.json

    {
  "attributes": {
    "map": {
      "layers": [
        {
          "geoJson": "http://host.org/data.geojson",
          "type": "geojson"
        },
        {
          "baseURL": "http://host.org/tiles",
          "type": "OSM",
          "imageExtension": "png"
        }
      ],
      "projection": "EPSG:3857",
      "dpi": 128,
      "scale": 100000,
      "center": [
        -8233518.5005945,
        4980320.4059228
      ]
    }
  },
  "layout": "A4 landscape"
}
  

Geo Json Layer¶

Renders GeoJSON layers.

Type: geojson

Example

json_styling datasource_multiple_maps printwms_tyger_ny_EPSG_3857

Configuration

parser

Inputs

failOnError: Fail if a tile return an error.

geoJson: A geojson formatted string or url to the geoJson or the raw GeoJSON data.
The url can be a file url, however if it is it must be relative to the configuration directory.

name: The name of the layer.

opacity: The opacity of the image.

renderAsSvg: Indicates if the layer is rendered as SVG.
(will default to Configuration.defaultToSvg).

style: The style name of a style to apply to the features during rendering. The style name must map to a style in the template or the configuration objects.
If no style is defined then the default style for the geometry type will be used.

Geotiff Layer¶

Renders a GeoTIFF image as layer.

Type: geotiff

Inputs

failOnError: Fail if a tile return an error.

name: The name of the layer.

opacity: The opacity of the image.

style: A string identifying a style to use when rendering the raster.

url required: The url of the geotiff. It can be a file but if it is the file must be contained within the config directory.

Gml Layer¶

Renders GML layers.

Type: gml

Configuration

parser

Inputs

failOnError: Fail if a tile return an error.

name: The name of the layer.

opacity: The opacity of the image.

renderAsSvg: Indicates if the layer is rendered as SVG.
(will default to Configuration.defaultToSvg).

style: The style name of a style to apply to the features during rendering. The style name must map to a style in the template or the configuration objects.
If no style is defined then the default style for the geometry type will be used.

url required: A url to the gml or the raw Gml data.
The url can be a file url, however if it is it must be relative to the configuration directory.

Grid Layer¶

A layer which is a spatial grid of lines on the map.

Type: grid

Example

crosses_point_grid

Configuration

parser

Inputs

failOnError: Fail if a tile return an error.

font: Configuration for the font of the grid labels. The default is the default system font.

formatDecimalSeparator: The character used to separate the decimal part (for example ","). This parameter is only used if valueFormat is used. The default is the character of the default locale.

formatGroupingSeparator: The character used for the thousands separator (for example "'"). This parameter is only used if valueFormat is used. The default is the character of the default locale.

gridColor: The color of the grid points or lines. Default is gray ("gray")

gridType: The type of grid to render.
Can be LINES or POINTS. Default is LINES.

haloColor: The color of the halo around grid label text. The color is defined the same as colors in CSS. Default is white ("#FFF")

haloRadius: The size of the halo around the Grid Labels. The default is 1.

horizontalYOffset: Apply an Y offset to horizontal grid line labels, relative to the horizontal grid lines. Defaults to 0.

indent: The number of pixels to indent the grid labels from the end of the map. The default is 5.

labelColor: The color of the grid label text. Default is dark gray ("#444")

labelFormat: The formatting string used to format the label (for example "%1.2f %s"). By default the label is formatted according to the unit and label value. For the format syntax, see java.util.Formatter. If labelFormat is set, valueFormat, unitFormat and custom separator characters will be ignored.

labelProjection: The projection code to use for the labels. The value should be the string authority:code form identifying the projection. By default it will be the same projection as the map.

longitudeFirst: By default the normal axis order as specified in EPSG code will be used when parsing projections. However the requester can override this by explicitly declaring that longitude axis is first.

name: The name of the layer.

numberOfLines required: The x,y number of grid lines.
The x is the number of lines that run vertically along the page.

opacity: The opacity of the image.

origin: The x,y point of grid origin.
This is required if spacing is defined.

pointsInLine: The number of points that will be in the grid line (if the gridType is LINES). If the line will be curved (for certain projections) then the more points the smoother the curve.
The default number of points is 10000.

renderAsSvg: Indicates if the layer is rendered as SVG.
(will default to Configuration.defaultToSvg).

rotateLabels: If true (the default), the labels will be rotated to follow the lines they belong to. Otherwise they are orientated west to east.

spacing required: The x,y spacing between grid lines.
Either spacing or numberOfLines
If spacing is defined then origin must also be defined

style: The style name of a style to apply to the features during rendering. The style name must map to a style in the template or the configuration objects.
If no style is defined then the default grid style will be used. The default will depend if the type is point or line and will respect gridColor and haloColor and haloRadius. If gridType is GridType.POINTS then the style will be crosses with a haloRadius sized halo around the cross. If GridType.LINES then the style will be a dashed line with no halo.

unitFormat: The formatting string used to format the unit part of a label (for example " %s"). This parameter is ignored if labelFormat is set. valueFormat must be set to use this parameter. For the format syntax, see java.util.Formatter.

valueFormat: The formatting string used to format the decimal part of a label (for example "###,###"). This parameter is ignored if labelFormat is set. For the format syntax, see DecimalFormat.

verticalXOffset: Apply an X offset to the vertical grid line labels, relative to the vertical grid lines. Defaults to 0.

Image Layer¶

Renders an image as layer.

Type: image

Inputs

baseURL required: The base URL for the image file. Used for making request.

extent required: The extent of the image. Used for placing image on map.

failOnError: Fail if a tile return an error.

imageFormat: The format of the image. for example image/png, image/jpeg, etc...

name: The name of the layer.

opacity: The opacity of the image.

style: The styles to apply to the image.

Osm Layer¶

Renders OpenStreetMap or other tiled layers.

Type: osm

Example

print_osm_new_york_EPSG_3857

Inputs

baseURL required

The URL used for the tile requests.

Supported formats:

The base part of the URL, for example 'http://tile.openstreetmap.org'. This results in an URL like 'http://tile.openstreetmap.org/12/123/456.png'.
An URL template with the placeholders '{x}', '{y}' or '{-y}', and '{z}'. For example: 'http://tile.openstreetmap.org/{z}/{x}/{y}.png'.

The placeholder '{-y}' provides support for OSGeo TMS tiles.

customParams

Custom query parameters to use when making http requests. customParams.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

dpi: The DPI of the OSM tiles.

failOnError: Fail if a tile return an error.

imageExtension: The image extension. for example png, jpeg, etc...

maxExtent: The maximum extent of the osm layer. Must have 4 coordinates, minX, minY, maxX, maxY
Default: [-20037508.34, -20037508.34, 20037508.34, 20037508.34]

name: The name of the layer.

opacity: The opacity of the image.

rasterStyle: The name of the style (in Configuration or Template) to use when drawing the layer to the map. This is separate from the style in that it indicates how to draw the map. It allows one to apply any of the SLD raster styling.

resolutionTolerance: The amount of difference between a resolution and a target resolution to consider the two equal. The value is a value from 0-1.

resolutions: The allowed resolutions for this layer.

tileSize: The size of each tile. Must have 2 values: width, height
Default: [256, 256]

Tiled Wms Layer¶

Renders tiled WMS layers.

Type: tiledwms

Example

printtiledwms

Inputs

baseURL required: The base URL for the WMS. Used for making WMS requests.

customParams

Custom query parameters to use when making http requests. These are related to mergeableParams except they are the parameters that will prevent two layers from the same server from being merged into a single request with both layers. See mergeableParams for a more detailed example of the difference between mergeableParams and customParams.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

failOnError: Fail if a tile return an error.

imageFormat: The format of the image. for example image/png, image/jpeg, etc...

layers required: The wms layer to request in the GetMap request. The order is important. It is the order that they will appear in the request.
As with the WMS specification, the first layer will be the first layer drawn on the map (the bottom/base layer) of the map. This means that layer at position 0 in the array will covered by layer 1 (where not transparent) and so on.

mergeableParams

Custom query parameters that can be merged if multiple layers are merged together into a single request.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

For example in WMS the style parameter can be merged. If there are several wms layers that can be merged except they have different style parameters they can be merged because the style parameter can be merged.

Compare that to DPI parameter (for QGIS wms mapserver). if two layers have different DPI then the layers cannot be merged. In this case the DPI should NOT be one of the mergeableParams it should be one of the customParams.

method: The HTTP verb to use for fetching the images. Can be either "GET" (the default) or "POST".
In case of "POST", the parameters are send in the body of the request using an "application/x-www-form-urlencoded" content type. This can be used when the parameters are too long. Tested only with GeoServer.

name: The name of the layer.

opacity: The opacity of the image.

rasterStyle: The name of the style (in Configuration or Template) to use when drawing the layer to the map. This is separate from the style in that it indicates how to draw the map. It allows one to apply any of the SLD raster styling.

serverType: The server type ("mapserver", "geoserver" or "qgisserver"). By specifying the server type vendor specific parameters (like for the DPI value) can be used when making the request.

styles: The styles to apply to the layers. If this is defined there should be the same number as the layers and the style are applied to the layer in the layers field.

tileBufferSize: A two element array of integers indicating the width and height tile buffer.

tileSize required: A two element array of integers indicating the x and y size of each tile.

useNativeAngle: If true transform the map angle to customParams.angle for GeoServer, and MapServer.

version: The WMS version to use when making requests.

WMTS Layer¶

Renders WMTS layers.

Type: wmts

Example

printwmts_tyger_ny_EPSG_3857

Inputs

baseURL required

The ‘ResourceURL’ available in the WMTS capabilities.

Example (for requestEncoding: "KVP"):

 baseUrl: "http://domain.com/wmts"

Example (for requestEncoding: "REST"):

 baseUrl: "http://domain.com/wmts/roads/{TileMatrixSet}/{TileMatrix}/{TileCol}/{TileRow}.png"

The following URL template variables are replaced:

{Layer}
{style}
{TileMatrixSet}
{TileMatrix}
{TileRow}
{TileCol}
{[DIMENSION.IDENTIFIER]}

customParams

Custom query parameters to use when making http requests. These are related to mergeableParams except they are the parameters that will prevent two layers from the same server from being merged into a single request with both layers. See mergeableParams for a more detailed example of the difference between mergeableParams and customParams.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

dimensionParams: Dictionary of dimensions name (Must be uppercase) => value.

dimensions: The "sample" dimensions or image color bands to retrieve.
This can be null, if so then the default dimensions will be returned. If specified they must be dimensions supported by the server.
These are keys to the dimensionParams.

failOnError: Fail if a tile return an error.

imageFormat: The format of the image. for example image/png, image/jpeg, etc...

layer required: The layer name.

matrices required

Array of matrix ids.

Example:

 [{
   "identifier": "0",
   "matrixSize": [1, 1],
   "scaleDenominator": 4000,
   "tileSize": [256, 256],
   "topLeftCorner": [420000, 350000]
   }, ...]

matrixSet required: Reference/Identifier to a tileMatrixSet and limits.

mergeableParams

Custom query parameters that can be merged if multiple layers are merged together into a single request.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

For example in WMS the style parameter can be merged. If there are several wms layers that can be merged except they have different style parameters they can be merged because the style parameter can be merged.

Compare that to DPI parameter (for QGIS wms mapserver). if two layers have different DPI then the layers cannot be merged. In this case the DPI should NOT be one of the mergeableParams it should be one of the customParams.

name: The name of the layer.

opacity: The opacity of the image.

rasterStyle: The name of the style (in Configuration or Template) to use when drawing the layer to the map. This is separate from the style in that it indicates how to draw the map. It allows one to apply any of the SLD raster styling.

requestEncoding: The way to make the requests. Either KVP or REST (default).

style: The style name (for styles on the WMTS server).

version: The WMTS protocol version to use.

Wms Layer¶

Renders WMS layers as single image.

Type: wms

Example

printwms_tyger_ny_EPSG_3857 printwms_UsaPopulation_EPSG_4326

Inputs

baseURL required: The base URL for the WMS. Used for making WMS requests.

customParams

Custom query parameters to use when making http requests. These are related to mergeableParams except they are the parameters that will prevent two layers from the same server from being merged into a single request with both layers. See mergeableParams for a more detailed example of the difference between mergeableParams and customParams.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

failOnError: Fail if a tile return an error.

imageFormat: The format of the image. for example image/png, image/jpeg, etc...

layers required: The wms layer to request in the GetMap request. The order is important. It is the order that they will appear in the request.
As with the WMS specification, the first layer will be the first layer drawn on the map (the bottom/base layer) of the map. This means that layer at position 0 in the array will covered by layer 1 (where not transparent) and so on.

mergeableParams

Custom query parameters that can be merged if multiple layers are merged together into a single request.

The json should look something like:

 {
     "param1Name": "value",
     "param2Name": ["value1", "value2"]
 }

For example in WMS the style parameter can be merged. If there are several wms layers that can be merged except they have different style parameters they can be merged because the style parameter can be merged.

Compare that to DPI parameter (for QGIS wms mapserver). if two layers have different DPI then the layers cannot be merged. In this case the DPI should NOT be one of the mergeableParams it should be one of the customParams.

method: The HTTP verb to use for fetching the images. Can be either "GET" (the default) or "POST".
In case of "POST", the parameters are send in the body of the request using an "application/x-www-form-urlencoded" content type. This can be used when the parameters are too long. Tested only with GeoServer.

name: The name of the layer.

opacity: The opacity of the image.

rasterStyle: The name of the style (in Configuration or Template) to use when drawing the layer to the map. This is separate from the style in that it indicates how to draw the map. It allows one to apply any of the SLD raster styling.

serverType: The server type ("mapserver", "geoserver" or "qgisserver"). By specifying the server type vendor specific parameters (like for the DPI value) can be used when making the request.

styles: The styles to apply to the layers. If this is defined there should be the same number as the layers and the style are applied to the layer in the layers field.

useNativeAngle: If true transform the map angle to customParams.angle for GeoServer, and MapServer.

version: The WMS version to use when making requests.