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:900913",
      "dpi": 128,
      "scale": 100000,
      "center": [
        -8233518.5005945,
        4980320.4059228
      ]
    }
  },
  "layout": "A4 landscape"
}

Geo Json Layer

Renders GeoJSON layers.

Type: geojson

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

Configuration

parser

Inputs

DEFAULT_UNIT_FORMAT required
Grid label default format pattern for the unit (if valueFormat is used).
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 ()
gridType
The type of grid to render. By default it 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 ()
haloRadius
The size of the halo around the Grid Labels. The default is .
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 .
labelColor
The color of the grid label text. Default is dark gray ()
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 requestor 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 .
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.
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

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, jpg, etc...
imageFormat required
Deprecated. 
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.
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.
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 customParams.map_angle for MapServer.
version
The WMS version to use when making requests.

WMTS Layer

Renders WMTS layers.

Type: wmts

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

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.
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 customParams.map_angle for MapServer.
version
The WMS version to use when making requests.