Raster Layers

Raster layers consist of raster images that are a grid of pixels. Raster layer usually serves as a base background layer of a map. You can download raster images using different providers: tile servers and WMS services.

The add-on supports the following types of layers:

  • Tile layer is used to display tiles provided by XYZ tiles services.

  • Web Map Service (WMS) layer is used to display tiles from Web Map Service.

  • Image layer is used for displaying an image over specific bounds of a map.

Tile Layer

TileLayer is used to load and display tiles that are served through a web server with URL like http://…​/{z}/{x}/{y}.png. For example, OpenStreetMap tiles URL pattern is: https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png.

To add a tile layer on a map, declare it in the XML descriptor:

<maps:layers>
    <maps:tile id="tileLayer"
               urlPattern="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
               attribution="&#169; &lt;a href=&quot;https://www.openstreetmap.org/copyright&quot;&gt;
                   OpenStreetMap&lt;/a&gt; contributors"/>
</maps:layers>

id and urlPattern are required if tileProvider is not specified.

Most tile servers require attribution, which you can set in attribution parameter. In our example, the credit ©OpenStreetMap contributors will appear in the lower-right corner.

In subDomains parameter, you can specify comma-separated values for {s} placeholder in the urlPattern. Default values are "a,b,c" which are used by most tile services including OpenStreetMap.

OpenStreetMap tile provider comes out of the box, so you can use it like this:

<maps:tile id="tileLayer" tileProvider="map_OpenStreetMap"/>

Additionally you can perform the tile layer in the screen controller using io.jmix.mapsui.component.layer.TileLayer class:

@Autowired
private GeoMap map;

@Subscribe
public void onBeforeShow(BeforeShowEvent event) {
    TileLayer tileLayer = new TileLayer("tileLayer");
    tileLayer.setUrl("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png");
    tileLayer.setAttributionString("&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors");
    map.addLayer(tileLayer);
}

Create Bean Providing Tiles

In order not to clutter the XML descriptors with the URL and attribution strings you can create Spring bean and use tileProvider attribute:

  1. Move tile server settings to the bean implementing io.jmix.mapsui.component.layer.TileProvider interface.

    @Component(CartoTileProvider.NAME)
public class CartoTileProvider implements TileProvider {
    public static final String NAME = "sample_CartoTileProvider";

    private static final String URL_PATTERN = "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png";
    private static final String ATTRIBUTION = "&copy; <a href=\"http://www.openstreetmap.org/copyright\">OpenStreetMap</a> &copy;" +
            " <a href=\"https://carto.com/attributions\">CARTO</a>";

    @Override
    public String getUrlPattern() {
        return URL_PATTERN;
    }

    @Override
    public String getAttributionString() {
        return ATTRIBUTION;
    }
}

  2. Specify a bean name in a tileProvider attribute of the tile element.

    <maps:tile id="tileLayer" tileProvider="sample_CartoTileProvider"/>

WMS Layer

WMSTileLayer uses various WMS services as a map provider. You can declare it in the XML descriptor:

<maps:layers>
    <maps:wms id="wmsLayer"
              url="http://ows.terrestris.de/osm/service?"
              layers="OSM-WMS"
              format="image/png"/>
</maps:layers>

id, url and layers are required parameters. Other parameters have default values, which can be redefined.

Also, you can perform a layer in the screen controller using io.jmix.mapsui.component.layer.WMSTileLayer class:

@Autowired
private GeoMap map;

@Subscribe
public void onBeforeShow(BeforeShowEvent event) {
    WMSTileLayer wmsTileLayer = new WMSTileLayer("wmsLayer");
    wmsTileLayer.setUrl("http://ows.terrestris.de/osm/service?");
    wmsTileLayer.setLayers("OSM-WMS");
    wmsTileLayer.setFormat("image/png");
    map.addLayer(wmsTileLayer);
}

Image Layer

Image layer is used for displaying an image over specific bounds of a map.

ImageLayer can be declared in the XML descriptor:

<maps:layers>
    <maps:image id="imageLayer"
                image="url:https://legacy.lib.utexas.edu/maps/historical/newark_nj_1922.jpg"
                opacity="0.5"
                topLeftX="-116.982422"
                topLeftY="48.899394"
                bottomRightX="-104.326172"
                bottomRightY="42.656586"/>
</maps:layers>

  • image parameter describes a path to the image. The path should start with one of the following prefixes defining the source of an image:

    • url: — the image will be loaded from the given URL.

    • file: — the image will be served from the file system.

      image="file:D:/myImage.png"

    • classpath: — the image will be served from the classpath, for example, com/company/demo/web/myImage.png:

      image="classpath:/com/company/demo/web/myImage.png"

    • theme: — the image will be served from the current theme directory, for example, web/themes/hover/awesomeFolder/myImage.png:

      image="theme:awesomeFolder/myImage.png"

    You can also load the image programmatically by declaring the geoImageDelegate function:

    @Install(to = "map.imageLayer", subject = "geoImageDelegate")
private GeoImage mapImageLayerGeoImageDelegate(ImageLayer imageLayer) {
    String url = "https://legacy.lib.utexas.edu/maps/historical/newark_nj_1922.jpg";
    return GeoImage.fromUrl(url);
}

  • topLeft parameter defines the north-west point of the image.

  • bottomRight parameter defines the south-east point of the image.

In case of using an SVG image in the ImageLayer, make sure that SVG document contains width/height or viewBox attributes, which are needed for the SVG image to behave correctly on zooming a map.