Layers and Sources

Layer is a way to organize data on a map.

Layers can be raster or vector. Raster layers consist of raster images, which are a grid of pixels, while vector layers consist of vector geometries.

TileLayer

Layer with sources that provide pre-rendered, tiled images in grids that are organized by zoom levels for specific resolutions.

For more details see TileLayer documentation.

TileLayer supports the following sources:

OsmSource

Source for loading tiles from an OpenStreetMap tile server and from XYZ tile services. For more details, see OSM documentation.

The following example demonstrates how to display an OpenStreetMap tile layer.

<maps:geoMap id="map"
             height="100%"
             width="100%">
    <maps:layers>
        <maps:tile>
            <maps:osmSource/>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

XyzSource

Source for tile data with URLs in a set XYZ format that are defined in a URL template. By default, this follows the widely-used Google grid where x 0 and y 0 are in the top left. XyzSource can load tiles from XYZ tile services. For more details see XYZ documentation.

The following example demonstrates how to display a Thunderforest tile layer.

<maps:geoMap id="mapxyz"
             width="100%"
             height="100%">
    <maps:layers>
        <maps:tile>
            <maps:xyzSource
                    url="https://tile.thunderforest.com/cycle/{z}/{x}/{y}.png?apikey=YOUR_API_KEY">
            </maps:xyzSource>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

WmsSource

Source for tile data from WMS (Web Map Service) servers. For more details see TileWMS documentation.

The following example demonstrates how to display a tile layer with WmsSource.

<maps:geoMap id="mapwms"
             width="100%"
             height="100%">
    <maps:layers>
        <maps:tile>
            <maps:tileWmsSource url="https://ahocevar.com/geoserver/wms"
                                serverType="GEO_SERVER">
                <maps:parameters>
                    <maps:parameter name="LAYERS" value="topp:states"/>
                    <maps:parameter name="TILED" value="true"/>
                </maps:parameters>
            </maps:tileWmsSource>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

WmtsSource

Source for tile data from WMTS (Web Map Tile Service) servers. For more details see WMTS documentation.

WMTS services publish pre-rendered tiles using a tile matrix set. To configure WmtsSource, specify the service URL and layer identifier, then choose one of the supported tile grid configuration modes:

  • tileGrid - defines resolutions, matrix identifiers, origin and tile size explicitly.

  • webMercatorTileGrid - creates a standard EPSG:3857 tile grid automatically.

  • capabilities - downloads the WMTS GetCapabilities document and derives the source configuration from it.

The following example demonstrates a WmtsSource with an explicitly configured tile grid:

<maps:geoMap id="mapWmts"
             width="100%"
             height="100%">
    <maps:mapView centerX="0" centerY="0" zoom="2"/>
    <maps:layers>
        <maps:tile>
            <maps:wmtsSource url="https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi"
                             layer="BlueMarble_ShadedRelief_Bathymetry"
                             matrixSet="GoogleMapsCompatible_Level8"
                             format="image/jpeg"
                             style="default"
                             requestEncoding="KVP">
                <maps:projection code="EPSG:3857"/>
                <maps:tileGrid resolutions="156543.03392804097, 78271.51696402048, 39135.75848201024"
                               matrixIds="0, 1, 2">
                    <maps:origin x="-20037508.342789244" y="20037508.342789244"/>
                    <maps:tileSize width="256" height="256"/>
                </maps:tileGrid>
            </maps:wmtsSource>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

For Web Mercator services, use webMercatorTileGrid to avoid listing all resolutions and matrix identifiers manually:

<maps:geoMap id="mapWmtsWebMercator"
             width="100%"
             height="100%">
    <maps:mapView centerX="0" centerY="0" zoom="4"/>
    <maps:layers>
        <maps:tile>
            <maps:wmtsSource url="https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi"
                             layer="BlueMarble_ShadedRelief_Bathymetry"
                             matrixSet="GoogleMapsCompatible_Level8"
                             format="image/jpeg"
                             style="default">
                <maps:webMercatorTileGrid maxZoom="8"
                                          numericMatrixIds="true"/>
            </maps:wmtsSource>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

By default, webMercatorTileGrid generates matrix identifiers in the {matrixSet}:{zoom} format, for example EPSG:900913:0. If your WMTS server uses numeric matrix identifiers such as 0, 1, 2, set numericMatrixIds="true".

To configure the source from the WMTS capabilities document, add the capabilities element. If the capabilities document cannot be derived from the source URL, specify it explicitly using the url attribute:

<maps:geoMap id="mapWmtsCapabilities"
             width="100%"
             height="100%">
    <maps:mapView centerX="0" centerY="0" zoom="4"/>
    <maps:layers>
        <maps:tile>
            <maps:wmtsSource url="https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/wmts.cgi"
                             layer="BlueMarble_ShadedRelief_Bathymetry">
                <maps:capabilities url="https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/1.0.0/WMTSCapabilities.xml"/>
            </maps:wmtsSource>
        </maps:tile>
    </maps:layers>
</maps:geoMap>

The capabilities mode loads the document asynchronously while the view opens. If the document cannot be loaded or the specified layer is not found, the error is written to the log and the map view remains available without this source.

The following application properties affect only the capabilities mode:

Property Type Default Description

jmix.maps.ui.wmts-capabilities-timeout

Duration

10s

Timeout for downloading a WMTS GetCapabilities document.

jmix.maps.ui.wmts-capabilities-cache-ttl

Duration

10m

How long a downloaded GetCapabilities document is cached per URL. Set to 0 to disable caching.

ImageLayer

ImageLayer is used to work with static images or WMS images.

ImageStaticSource

Source for displaying a single, static image. For more details see Static documentation.

Example of showing an image from a URL. This example is taken from OpenLayers → Examples → Static image.

<maps:geoMap id="mapimagestatic"
             width="100%"
             height="100%">
    <maps:mapView centerX="512" centerY="479" zoom="2">
        <maps:projection code="static-image"
                         units="PIXELS">
            <maps:extent minX="0" minY="0" maxX="1024" maxY="968"/>
        </maps:projection>
    </maps:mapView>
    <maps:layers>
        <maps:image id="imageLayer">
            <maps:imageStaticSource url="https://imgs.xkcd.com/comics/online_communities.png">
                <maps:projection code="static-image"/>
                <maps:imageExtent minX="0" minY="0" maxX="1024" maxY="968"/>
            </maps:imageStaticSource>
        </maps:image>
    </maps:layers>
</maps:geoMap>

To display an image from the classpath, define the XML in the same way as shown in the example above:

<maps:geoMap id="declarativeMap"
             width="100%"
             height="100%">
    <maps:mapView centerX="450" centerY="522" zoom="2">
        <maps:projection code="static-image"
                         units="PIXELS">
            <maps:extent minX="0" minY="0" maxX="900" maxY="1044"/>
        </maps:projection>
    </maps:mapView>
    <maps:layers>
        <maps:image id="dImageLayer">
            <maps:imageStaticSource id="classpathSource"
                                    url="maps/map.png">
                <maps:projection code="static-image"/>
                <maps:imageExtent minX="0" minY="0" maxX="900" maxY="1044"/>
            </maps:imageStaticSource>
        </maps:image>
    </maps:layers>
</maps:geoMap>

Additionally, you can achieve this in the Java controller using DownloadHandler:

@ViewComponent("programmaticMap.pImageLayer.programmaticSource")
private ImageStaticSource programmaticSource;

@Subscribe
protected void onInit(final InitEvent event) {
    programmaticSource.setDownloadHandler(
            DownloadHandler.forClassResource(getClass(),"/META-INF/resources/maps/map.png"));
}

ImageWmsSource

Source for WMS servers providing single, untiled images. For more details see ImageWMS documentation.

The example of using ImageWmsSource is taken from OpenLayers → Examples → Single Image WMS:

<maps:geoMap id="mapimagewms"
             width="100%"
             height="100%">
    <maps:layers>
        <maps:tile>
            <maps:osmSource/>
        </maps:tile>
        <maps:image>
            <maps:imageWmsSource url="https://ahocevar.com/geoserver/wms"
                                 ratio="1"
                                 serverType="GEO_SERVER">
                <maps:parameters>
                    <maps:parameter name="LAYERS" value="topp:states"/>
                </maps:parameters>
            </maps:imageWmsSource>
            <maps:extent minX="-124.43" minY="24.57" maxX="-66.58" maxY="49.22"/>
        </maps:image>
    </maps:layers>
</maps:geoMap>

VectorLayer

A vector layer is utilized to work with geometries. It’s possible to add multiple vector layers to a map.

VectorSource

Source for working with features. For more details see VectorSource documentation.

The following example demonstrates how to display a vector layer with VectorSource. Initially, define a map in the XML descriptor:

<maps:geoMap id="mapwithvector"
             width="100%"
             height="100%">
    <maps:layers>
        <maps:tile>
            <maps:osmSource/>
        </maps:tile>
        <maps:vector id="vectorLayer">
            <maps:vectorSource id="vectorSource"/>
        </maps:vector>
    </maps:layers>
</maps:geoMap>

Subsequently, open the view controller and add the created marker to the map:

@ViewComponent("mapwithvector.vectorLayer.vectorSource")
private VectorSource vectorSource;

@Subscribe
protected void onInit(final InitEvent event) {
    vectorSource.addFeature(new MarkerFeature(createPoint(0, 0)));(1)
}
1 Adds a marker feature to the source.

DataVectorSource

DataVectorSource allows data binding to Jmix data containers through the dataContainer and property attributes. The property attribute can take both a simple property and a property path.

<maps:geoMap id="map" height="100%" width="100%">
    <maps:layers>
        <maps:tile>
            <maps:osmSource/>
        </maps:tile>
        <maps:vector id="vectorLayer">
            <maps:dataVectorSource id="dataVectorSource"
                                   dataContainer="locationDc"
                                   property="building"/>
        </maps:vector>
    </maps:layers>
    <maps:mapView centerY="51.0">
        <maps:extent minX="-15.0"
                     minY="30.0"
                     maxX="40.0"
                     maxY="60.0"/>
    </maps:mapView>
</maps:geoMap>
<maps:vector id="vectorLayer">
    <maps:dataVectorSource dataContainer="ordersDc"
                           property="customer.address.point"/>
</maps:vector>