Map Configuration
By default MapStore is able to open maps with this path in the URL:
1 |
|
Where:
maptype
can beleaflet
openlayers
orcesium
.mapId
can be a number or a string.- A number represents standard maps, stored on the database.
- A string instead represents a static json file in the root of the application.
The first case can be used to load a map from the maps database, using its id.
There is a special mapId, 0 (zero), that is used to load a basic OSM map for demo purposes.
1 |
|
The configuration of this map is stored in the static config.json
file in the root of the project.
The second case can be used to define standard map contexts.
This is used for the new map. If you're logged in and allowed to create maps, when you try to create a new map you will see the the application will bring you to the URL:
1 |
|
This page uses the new.json
file as a template configuration to start creating a new map. You can find this file in web/client/configs
directory for standard MapStore or in configs/
folder for a custom projects.
You can edit new.json
to customize this initial template. It typically contains the map backgrounds you want to use for all the new maps (identified by the special property "group": "background"
).
If you have enabled the datadir, then you can externalize the new.json or config.json files. (see here for more details)
new.json
and config.json
are special cases, but you can configure your own static map context creating these json files in the root of the project, for instance mycontext.json
and accessing them at the URL:
1 |
|
important note: new.json
and config.json
are special files and don't require the version. For other map context, you must specify the version of the map file type in the root of the json file:
1 2 3 4 |
|
These static map contexts are accessible by anyone. If you want to customize standard maps (that are listed in home page and where you can define) manually, you will have to edit the maps using the GeoStore REST API.
Map options
The following options define the map options (projection, position, layers):
projection: {string}
expressed in EPSG valuesunits: {string}
uom of the coordinatescenter: [object]
center of the map with starting point in the bottom-left cornerzoom: {number}
level of zoomresolutions: {number[]}
resolutions for each level of zoomscales: {number[]}
scales used to compute the map resolutionsmaxExtent: {number[]}
max bbox of the map expressed [minx, miny, maxx, maxy]layers: {object[]}
list of layers to be loaded on the mapgroups {object[]}
: contains information about the layer groups
i.e.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
|
Note
The option to configure a list of scale denominators allow to have them in human friendly format, and calculate the map resolutions from scales.
Warning
If the scales and resolutions property are declared, in the same json object, the scales have priority. In the array, the values have be in descending order.
Warning
Actually the custom resolution values are valid for one single CRS. It's therefore suggested to avoid to add this parameter when multiple CRSs in the same map configuration are needed.
Additional map configuration options
Map configuration also contains the following additional options:
catalogServices
object describing services configuration for CatalogwidgetsConfig
configuration of map widgetsmapInfoConfiguration
map info configuration optionsdimensionData
contains map time informationcurrentTime
currently selected time; the beginning of a time range if offsetTime is setoffsetTime
the end of a time range
timelineData
timeline optionsselectedLayer
selected layer id; if not present time cursor will be unlocked
Layers options
Every layer has it's own properties. Anyway there are some options valid for every layer:
title
:{object|string}
the title of the layer, can be an object to support i18n.type
:{string}
the type of the layer. Can bewms
,wmts
,osm
...name
:{string}
the name is used as general reference to the layer, or as title, if the title is not specified. Anyway, it's usage depends on the specific layer type.group
:{string}
: the group of the layer (in the TOC). Nested groups can be indicated using/
. i.e.Group/SubGroup
. A special group,background
, is used to identify background layers. These layers will not be available in the TOC, but only in the background switcher, and only one layer of this group can be visible.thumbURL
:{string}
: the URL of the thumbnail for the layer, used in the background switcher ( if the layer is a background layer )visibility
:{boolean}
: indicates if the layer is visible or notqueriable
:{boolean}
: Indicates if the layer is queriable (e.g. getFeatureInfo). If not present the default is true for every layer that have some implementation available (WMS, WMTS). Usually used to set it explicitly to false, where the query service is not available.hideLoading
: {boolean}. If true, loading events will be ignored ( useful to hide loading with some layers that have problems or trigger errors loading some tiles or if they do not have any kind of loading.).minResolution
:{number}
: layer is visible if zoom resolution is greater or equal than this value (inclusive)maxResolution
:{number}
: layer is visible if zoom resolution is less than this value (exclusive)disableResolutionLimits
:{boolean}
: this property disables the effect of minResolution and maxResolution if set to true
i.e.
1 2 3 4 5 6 7 |
|
Localized titles: In these configuration files you can localize titles using an object instead of a string in the title
entry. In this case the title
object has this shape:
1 2 3 4 5 6 |
|
Layer types
wms
: WMS - Web Mapping Service layersosm
: OpenStreetMap layers formattileprovider
: Some other mixed specific tile providerswmts
: WMTS: Web Map Tile Service layersbing
: Bing Maps layersgoogle
: Google Maps layersmapquest
: MapQuest layersgraticule
: Vector layer that shows a coordinates grid over the map, with optional labelsempty
: special type for empty background3dtiles
: 3d tiles layersterrain
: layers that define the elevation profile of the terrain
WMS
i.e.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
You can also configure a WMS layer also as background, like this:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Multiple URLs
This feature is not yet fully supported by all the plugins, but OpenLayers supports it so if you put an array of urls instead of a single string in the layer url. Some other feature will break, for example the layer properties will stop working, so it is safe to use only on background layers.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
special case - The Elevation layer (deprecated)
Note
See the terrain
layer section for a more versatile way of handling elevation.
WMS layers can be configured to be used as a source for elevation related functions.
This requires:
- a GeoServer WMS service with the DDS/BIL plugin
- A WMS layer configured with BIL 16 bit output in big endian mode and -9999 nodata value
- a static layer in the Map plugin configuration (use the additionalLayers configuration option):
in localConfig.json
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
The layer will be used for:
- showing elevation in the MousePosition plugin (requires showElevation: true in the plugin configuration)
- as a TerrainProvider if the maptype is Cesium
in localConfig.json
1 2 3 4 5 6 7 |
|
WMTS
WMTS Layer require a source object in the sources
object of the map configuration where to retrieve the tileMatrixSet
. The source is identified by the capabilitiesURL
. (if capabilitiesURL
is not present it will use the url
, in case of multiple URLs, the first one.).
A WMTS layer can have a requestEncoding
that is RESTful or KVP. In case of RESTful the URL is a template where to place the request parameters ( see the example below ), while in the KVP the request parameters are in the query string. See the WMTS standard for more details.
e.g. (RESTful):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
|
e.g. (KVP)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 |
|
Bing
TODO
Note
The use of Google maps tiles in MapStore is not enabled and maintained due to licensing reasons. If your usage conditions respect the google license, you can enable the google layers by:
- Adding
<script src="https://maps.google.com/maps/api/js?v=3"></script>
to allhtml
files you need it. - Add your API-KEY to the request
- Fix the code, if needed.
example:
1 2 3 4 5 6 7 8 |
|
OSM
example:
1 2 3 4 5 6 7 8 |
|
TileProvider
TileProvider is a shortcut to easily configure many different layer sources.
It's enough to add provider
property and 'tileprovider' as type property to the layer configuration object. provider
should be in the form of ProviderName.VariantName
.
i.e.
1 2 3 4 5 6 7 8 |
|
Options passed in configuration object, if already configured by TileProvider, will be overridden.
Openlayers' TileProvider at the moment doesn't support minZoom
configuration property and high resolution map.
In case of missing provider
or if provider: "custom"
, the tile provider can be customized and configured internally.
You can configure the url
as a template, than you can configure options add specific options (maxNativeZoom
, subdomains
).
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Providers and variants
This is a not maintained list of providers and variants. For the most updated list check the code here
Some of them may need some additional configuration or API keys.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
|
Vector
The layer type vector is the type used for imported data (geojson, shapefile) or for annotations. Generally speaking, any vector data added directly to the map. This is the typical fields of a vector layer
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
|
features
: features in GeoJSON format.style
: the style object.styleName
: name of a style to use (e.g. "marker").hideLoading
: boolean. if true, the loading will not be taken into account.
WFS Layer
A vector layer, whose data source is a WFS service. The configuration has properties in common with both WMS and vector layers. it contains the search entry that allows to browse the data on the server side. The styling system is the same of the vector layer.
This layer differs from the "vector" because all the loading/filtering/querying operations are applied directly using the WFS service, without storing anything locally.
1 2 3 4 5 6 7 8 9 10 |
|
Vector Style
The vector
and wfs
layer types are rendered by the client as GeoJSON features and it possible to apply specific symbolizer using the style
property available in the layer options. The style object is composed by these properties
format
the format encoding used by style bodybody
the actual style rules and symbolizers
example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
The default format used by MapStore is "geostyler" that is an encoding based on the geostyler-style specification that could include some variations or limitations related to the map libraries used by MapStore app. We suggest to refer to following doc for the rule/symbolizer properties available in MapStore.
Ths style body
is composed by following properties:
name
style namerules
list of rule object that describe the style
A rule
object is composed by following properties:
name
rule name that could be used to generate a legendfilter
filter expressionsymbolizers
list of symbolizer object that describe the rule (usually one per rule)
The filter
expression define with features should be rendered with the symbolizers listed in the rule
example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Available logical operators:
||
OR operator&&
AND operator
Available comparison operators:
==
equal to*=
like (for string type)!=
is not<
less than<=
less and equal than>
grater than>=
grater and equal than
The symbolizer
could be of following kinds
:
Mark
symbolizer propertieskind
must be equal toMark
color
fill color of the markfillOpacity
fill opacity of the markstrokeColor
stroke color of the markstrokeOpacity
stroke opacity of the markstrokeWidth
stroke width of the markradius
radius size in px of the mark-
wellKnownName
rendered shape, one of Circle, Square, Triangle, Star, Cross, X, shape://vertline, shape://horline, shape://slash, shape://backslash, shape://dot, shape://plus, shape://times, shape://oarrow or shape://carrow -
Icon
symbolizer properties kind
must be equal toIcon
image
url of the image to use as iconsize
size of the iconopacity
opacity of the icon-
rotate
rotation of the icon -
Line
symbolizer properties kind
must be equal toLine
color
stroke color of the lineopacity
stroke opacity of the linewidth
stroke width of the line-
dasharray
array that represent the dashed line intervals -
Fill
symbolizer properties kind
must be equal toFill
color
fill color of the polygonfillOpacity
fill opacity of the polygonoutlineColor
outline color of the polygonoutlineOpacity
outline opacity of the polygon-
outlineWidth
outline width of the polygon -
Text
symbolizer properties kind
must be equal toText
label
text to show in the label, the {{propertyKey}} notetion allow to access feature properties (eg. 'feature name is {{name}}')font
array of font family namessize
font size of the labelfontStyle
font style of the label: normal or italicfontWeight
font style of the label: normal or boldcolor
font color of the labelhaloColor
halo color of the labelhaloWidth
halo width of the labeloffset
array of x and y values offset of the label
Legacy Vector Style (deprecated)
The style
or styleName
properties of vector layers (wfs, vector...) allow to apply a style to the local data on the map.
style
: a style object/array. It can have different formats. In the simplest case it is an object that uses some leaflet-like style properties:weight
: width in pixel of the border / line.radius
: radius of the circle (valid only for Point types)opacity
: opacity of the border / line.color
: color of the border / line.fillOpacity
: opacity of the fill if any. (Polygons, Point)fillColor
: color of the fill, if any. (Polygons, Point)styleName
: if set tomarker
, thestyle
object will be ignored and it will use the default marker.
In case of vector
layer, style can be added also to the specific features. Other ways of defining the style for a vector layer have to be documented.
Advanced Vector Styles (deprecated)
To support advanced styles (like multiple rules, symbols, dashed lines, start point, end point) the style can be configured also in a different format, as an array of objects and you can define them feature by feature, adding a "style" property.
Warning
This advanced style functionality has been implemented to support annotations, at the moment this kind of advanced style options is supported only as a property of the single feature object, not as global style.
SVG Symbol (deprecated)
The following options are available for a SVG symbol.
symbolUrl
: a URL (also a data URL is ok) for the symbol to use (SVG format). You can anchor the symbol using:iconAnchor
: array of x,y position of the offset of the symbol from top left corner.anchorXUnits
,anchorYUnits
unit of theiconAnchor
(fraction
orpixels
).size
: the size in pixel of the square that contains the symbol to draw. The size is used to center and to cut the original svg, so it must fit the svg.dashArray
: Array of line, space size, in pixels. ["6","6"] Will draw the border of the symbol dashed. It is applied also to a generic line or polygon geometry.
Markers and glyphs (deprecated)
These are the available options for makers. These are specific of annotations for now, so allowed values have to be documented.
iconGlyph
: e.g. "shopping-cart"iconShape
: e.g. "circle"iconColor
: e.g. "red"iconAnchor
: [0.5,0.5]
Multiple rules and filtering (deprecated)
In order to support start point and end point symbols, you could find in the style these entries:
geometry
: "endPoint"|"startPoint", identify how to get the geometry fromfiltering
: if true, the geometry filter is applied.
Example (deprecated)
Here an example of a layer with:
- a point styled with SVG symbol,
- a polygon with dashed style
- a line with start-end point styles as markers with icons
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 |
|
Result:
Graticule
i.e.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
3D tiles
This type of layer shows 3d tiles version 1.0 inside the Cesium viewer. This layer will not be visible inside 2d map viewer types: openlayer or leaflet. See specification for more info about 3d tiles here.
i.e.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
The style body object for the format 3dtiles accepts rules described in the 3d tiles styling specification version 1.0 available here.
Terrain
terrain
layer allows the customization of the elevation profile of the globe mesh in the Cesium 3d viewer. Currently Mapstore supports three different types of terrain providers. If no terrain
layer is defined the default elevation profile for the globe would be the ellipsoid that provides a rather flat profile.
The other two available terrain providers are the wms
(that supports DDL/BIL
types of assets) and the cesium
(that support resources compliant with the Cesium terrain format).
In order to create a wms
based mesh there are some requirements that need to be fulfilled:
- a GeoServer WMS service with the DDS/BIL plugin
- A WMS layer configured with BIL 16 bit output in big endian mode and -9999 nodata value
The layer configuration needs to point to the geoserver resource and define the type of layer and the type of provider:
1 2 3 4 5 6 7 8 9 |
|
The terrain
layer of cesium
type allows using Cesium terrain format compliant services (like Cesium Ion resources or MapTiler meshes). The options attributte allows for further customization of the terrain properties (see available options on the Cesium documentation for the cesium terrain provider)
1 2 3 4 5 6 7 8 9 |
|
In order to use these layers they need to be added to the additionalLayers
in localConfig.json
. The globe only accepts one terrain provider so in case of adding more than one the last one will take precedence and be used to create the elevation profile.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Layer groups
Inside the map configuration, near the layers
entry, you can find also the groups
entry. This array contains information about the groups in the TOC.
A group entry has this shape:
id
: the id of the group.expanded
: boolean that keeps the status (expanded/collapsed) of the group.title
: a string or an object (for i18n) with the title of the group. i18n object format is the same of layer's title.
1 2 3 4 5 6 7 8 |
|
i.e.
1 2 3 4 5 |
|
Other supported formats
The JSON format above is the standard MapStore format. Anyway MapStore allows to import/export different kinds of formats for maps.
Web Map Context
MapStore provides support for OGC Web Map Context(WMC) files. They can be imported either using Import plugin functionality, or from within a context using Map Templates plugin. MapStore maps can also be exported in WMC format through Export plugin.
The important thing to remember when exporting MapStore maps to WMC format is that it only supports WMS layers, meaning any non-WMS layers(such as tiled OSM backgrounds for example) will not be preserved in the resulting WMC file. The exact way in which the conversion happens is described in further detail throughout this document.
WMC File Structure
WMC context file generated by MapStore is an XML file with the following structure:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
|
More information about each of the elements in the example above can be looked up in OGC WMC implementation specification
Apart from standard WMC XML elements, MapStore provides support for various extensions. These are placed inside
Extension
tag, and are not gueranteed to be supported outside MapStore, as they are not a part of OGC
Web Map Context specification. MapStore provides two types of extensions: openlayers and mapstore-specific elements.
WMC can have an Extension
element inside General
, and each of the Layer
elements. Supported extensions in General
are:
Openlayers:
maxExtent
if present, it's attributes are used as map's bounding box, instead of the values specified inBoundingBox
tag. The values are assumed to be in a projection, specified in SRS attribute ofBoundingBox
1 |
|
MapStore specific:
GroupList
defines a mapstore group list. ContainsGroup
elements that describe a particular layer group:
1 2 3 |
|
center
defines a center of map view
1 |
|
zoom
map zoom level
1 |
|
Supported extensions for each Layer
element are:
Openlayers:
maxExtent
if present, used for the value of layer's bbox. Values are assumed to be in a projection, specified in SRS attribute of "BoundingBox"singleTile
specifies layer's "singleTile" property valuetransparent
is layer transparent or not, true by defaultisBaseLayer
if true, the layer is put into "backgrounds" groupopacity
layer's opacity value
1 2 3 4 5 |
|
Cesium:
tileDiscardPolicy
sets a policy for discarding (missing/broken) tiles (https://cesium.com/learn/cesiumjs/ref-doc/TileDiscardPolicy.html). If it is not specified the NeverTileDiscardPolicy will be used. If "none" is specified, no policy at all will be set.
MapStore specific:
group
specifies to which group, among listed in "GroupList" element, the layer belongs tosearch
JSON describing a filter that is applied to the layerDimensionList
containsDimension
elements that describe dimensions that cannot be described using standard "Dimension" tag. Currently supports dimensions of multidim-extension type:CatalogServices
containsService
elements that describe services available for use in Catalog.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
Note, that during the exporting process, some sort of fallback for dimensions, listed as extensions, is provided inside the standard
DimensionList
tag whenever possible, to ensure interoperability with other geospatial software. When such a context is
imported back into MapStore, the values of dimensions inside extensions will override the ones specified inside the standard
DimensionList
tag.
Also note, that the extension elements would be read correctly only if they belong to appropriate XML namespaces:
http://openlayers.org/context
for openlayers extensionshttp://geo-solutions.it/mapstore/context
for mapstore specific extensions
Usage inside MapTemplates plugin
As stated previously, WMC files can be used as map templates inside contexts. New WMC templates can be uploaded in context creation tool, after enabling the MapTemplates plugin for a context. When the context is loaded, for every template inside MapTemplates there are two options available:
Replace map with this template
replace the currently loaded map with the one described by the template. Upon loading, the map will zoom to the extent specified inmaxExtent
extension or inBoundingBox
tag. If the template has no visible background layers available, the default empty background will be added and set to be visible automatically.Add this template to map
merges layers and groups inside the template with the current map configuration. If the WMC template does not containGroupList
extension, a new group with the name extracted fromTitle
tag of the template will be created and will contain all the layers of the template. Zoom and projection will remain unchanged.
Other considerations
Due to the limitations posed by WMC format the conversion process will not preserve the map state in it's entirety. The only supported way to do this is to export to MapStore JSON format. The WMC export option presumably should be used in cases when the WMS layers inside a MapStore map need to be used in some way with a different geospatial software suite, or to import such layers from outside MapStore or if you already have WMC context files that you want to use.