Слои и источники

Слой (Layer) - это способ организации данных на карте.

Слои могут быть растровыми или векторными. Растровые слои состоят из растровых изображений, которые представляют собой сетку пикселей, в то время как векторные слои состоят из векторных геометрий.

TileLayer

Тайловый слой (TileLayer) - слой с источниками, которые предоставляют предварительно отрендеренные, разбитые на тайлы (плитки) изображения в сетках, организованных по уровням масштабирования для определенных разрешений.

Для получения более подробной информации см. документацию TileLayer.

TileLayer поддерживает следующие источники:

OsmSource

Источник для загрузки тайлов с сервера OpenStreetMap и из сервисов XYZ tile. Для получения более подробной информации смотрите документацию OSM.

Следующий пример демонстрирует, как отобразить тайловый слой OpenStreetMap.

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

XyzSource

Источник для тайловых данных с URL-адресами в заданном формате XYZ, которые определены в шаблоне URL. По умолчанию используется широко распространенная сетка Google, где x 0 и y 0 находятся в левом верхнем углу. XyzSource может загружать тайлы из сервисов XYZ tile. Для получения более подробной информации смотрите документацию XYZ.

Следующий пример демонстрирует, как отобразить тайловый слой Thunderforest.

<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

Источник для тайловых данных с WMS (Web Map Service) серверов. Для получения более подробной информации смотрите документацию TileWMS.

Следующий пример демонстрирует, как отобразить тайловый слой с 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

Источник тайловых данных с серверов WMTS (Web Map Tile Service). Подробности смотрите в документации WMTS.

Сервисы WMTS публикуют предварительно отрисованные тайлы с использованием набора тайловых матриц. Чтобы настроить WmtsSource, укажите URL сервиса и идентификатор слоя, затем выберите один из поддерживаемых режимов конфигурации тайловой сетки:

  • tileGrid - явно задает разрешения, идентификаторы матриц, начало координат и размер тайла.

  • webMercatorTileGrid - автоматически создает стандартную тайловую сетку EPSG:3857.

  • capabilities - загружает документ WMTS GetCapabilities и получает конфигурацию источника из него.

Следующий пример демонстрирует WmtsSource с явно настроенной тайловой сеткой:

<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>

Для сервисов Web Mercator используйте webMercatorTileGrid, чтобы не перечислять все разрешения и идентификаторы матриц вручную:

<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>

По умолчанию webMercatorTileGrid генерирует идентификаторы матриц в формате {matrixSet}:{zoom}, например EPSG:900913:0. Если ваш WMTS-сервер использует числовые идентификаторы матриц, такие как 0, 1, 2, установите numericMatrixIds="true".

Чтобы настроить источник на основе документа WMTS capabilities, добавьте элемент capabilities. Если документ capabilities нельзя получить из URL источника, укажите его явно с помощью атрибута url:

<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>

Режим capabilities загружает документ асинхронно во время открытия экрана. Если документ не удается загрузить или указанный слой не найден, ошибка записывается в лог, а экран карты остается доступным без этого источника.

Следующие свойства приложения влияют только на режим capabilities:

Свойство Тип Значение по умолчанию Описание

jmix.maps.ui.wmts-capabilities-timeout

Duration

10s

Тайм-аут загрузки документа WMTS GetCapabilities.

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

Duration

10m

Время кэширования загруженного документа GetCapabilities для каждого URL. Установите 0, чтобы отключить кэширование.

ImageLayer

Растровый слой (ImageLayer) используется для работы со статическими изображениями или WMS-изображениями.

ImageStaticSource

Источник для отображения одного статического изображения. Для получения более подробной информации смотрите документацию Static.

Пример показа изображения по URL. Этот пример взят из 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>

Чтобы отобразить изображение из classpath, определите XML таким же образом, как показано в примере выше:

<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>

Дополнительно этого можно достичь в Java-контроллере с помощью 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

Источник для WMS серверов, предоставляющих одиночные, не разбитые на тайлы изображения. Для получения более подробной информации смотрите документацию ImageWMS.

Пример использования ImageWmsSource взят из 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

Векторный слой (VectorLayer) используется для работы с геометриями. На карту можно добавить несколько векторных слоев.

VectorSource

Источник для работы с объектами (features). Для получения более подробной информации смотрите документацию VectorSource.

Следующий пример демонстрирует, как отобразить векторный слой с VectorSource. Сначала определите карту в XML-дескрипторе:

<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>

Затем откройте контроллер экрана и добавьте созданный маркер на карту:

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

@Subscribe
protected void onInit(final InitEvent event) {
    vectorSource.addFeature(new MarkerFeature(createPoint(0, 0)));(1)
}
1 Добавляет объект-маркер в источник.

DataVectorSource

DataVectorSource позволяет выполнять привязку данных к контейнерам данных Jmix через атрибуты dataContainer и property. Атрибут property может принимать как простое свойство, так и путь к свойству (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>