Android google maps map overlay

Наложение фрагментов карты

Мозаичное наложение, иногда называемое мозаичным слоем, представляет собой набор изображений, отображаемых поверх фрагментов базовой карты.

Примеры кода

В репозитории ApiDemos на сайте GitHub доступен пример, где демонстрируется использование наложения:

• TileOverlayDemoActivity – Java: функции наложения, реализованные с помощью Java.
• TileCoordinateDemoActivity – Java: система координат для наложений, реализованная с помощью Java.
• TileOverlayDemoActivity – Kotlin: функции наложения, реализованные с помощью Kotlin.
• TileCoordinateDemoActivity – Kotlin: система координат для наложений, реализованная с помощью Kotlin.

Введение

Класс TileOverlay определяет набор изображений, отображаемых поверх фрагментов базовой карты.

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

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

Вы также можете накладывать прозрачные фрагменты, чтобы добавлять на карту дополнительные объекты. Для этого можно использовать прозрачные изображения или задавать коэффициент прозрачности фрагмента программным образом.

Координаты фрагментов и уровни масштабирования

Google Maps API разбивает изображения на каждом уровне масштабирования на набор квадратных фрагментов карты, расположенных в виде сетки. Когда карта перемещается к новому местоположению или изменяется уровень масштабирования, Maps API определяет необходимые фрагменты и создает список фрагментов, которые нужно получить.

Фрагмент с координатами (0,0) всегда находится в северо-западном углу карты, при этом значения X увеличиваются в направлении с запада на восток, а значения Y увеличиваются в направлении с севера на юг. Фрагменты индексируются с использованием координат X, Y относительно исходной точки.

На уровне масштабирования 0 карта всего мира отображается как один фрагмент. На каждом уровне масштабирования выполняется увеличение с коэффициентом 2. Следовательно, на уровне масштабирования 1 карта будет отображаться в виде сетки фрагментов 2 x 2. На уровне масштабирования 2 это будет сетка 4 x 4. На уровне масштабирования 3 это будет сетка 8 x 8 и так далее.

Например, на уровне масштабирования 2 земная поверхность делится на 16 фрагментов. Каждый фрагмент можно описать с помощью уникальной комбинации координат X, Y и масштаба:

При создании изображений для мозаичного слоя вам потребуется создать по одному изображению для каждого фрагмента на каждом уровне масштабирования, который вы хотите поддерживать. В Google Картах при отображении фрагментов используется размер 256 dp (аппаратно-независимых пикселей). Для устройств с экранами высокого разрешения рекомендуется использовать фрагменты с большим значением dpi (512 x 512 пикселей). Дополнительные сведения о поддержке экранов с различными размерами и плотностью пикселей приведены в документации для разработчиков Android.

Примечание. Уровни масштабирования, поддерживаемые камерой, зависят от различных факторов и не имеют отношения к уровням, которые будут поддерживаться вашими фрагментами.

1. GoogleMap.getMaxZoomLevel() возвращает максимальный уровень масштабирования, доступный при текущем положении камеры. При этом учитывается используемый тип карты. Например, у спутниковых карт или карт рельефа может быть меньший максимальный уровень масштабирования, чем у фрагментов базовых карт.
2. GoogleMap.getMinZoomLevel() возвращает минимальный уровень масштабирования, который будет одинаковым для каждого места (в отличие от максимального уровня), но может различаться в зависимости от используемых устройств и размеров карт.

Как добавить накладываемый фрагмент карты

Самый простой и распространенный способ создания мозаичного наложения – указать URL-адрес соответствующего изображения фрагмента. UrlTileProvider – частичная реализация класса TileProvider , позволяющая указывать фрагменты изображений с помощью URL. При использовании этого класса необходимо, чтобы у всех изображений были одинаковые размеры.

Вам потребуется реализовать метод UrlTileProvider.getTileUrl() , который принимает координаты фрагмента (X, Y, масштаб) и возвращает URL изображения, которое будет использовано для этого фрагмента карты. Этот метод должен возвращать значение null, если для указанных координат X, Y и масштаба нет соответствующего фрагмента. URL может указывать на веб-ресурс, ресурс Android или файл на локальном диске.

Создайте комплект изображений на сервере так, чтобы каждому сочетанию координат X, Y и масштаба, которое вы хотите поддерживать, соответствовало определенное изображение фрагмента. Затем добавьте накладываемый фрагмент:

1. Определите класс UrlTileProvider , который будет предоставлять изображения фрагментов.
2. Переопределите метод getTileUrl() так, чтобы он создавал URL для каждого изображения фрагмента.
3. Предоставьте объект TileOverlayOptions , содержащий параметры:
   • fadeIn : тип Boolean. Указывает, должны ли фрагменты появляться постепенно. Значение по умолчанию – true . Постепенное появление можно отключить, если переключение между мозаичными наложениями выполняется слишком быстро. Информация о связи между прозрачностью и постепенным появлением приведена в разделе Прозрачность далее в этой статье.
   • tileProvider : объект TileProvider , который будет использоваться для этого фрагмента.
   • transparency : тип Float. Устанавливает коэффициент прозрачности накладываемых изображений. Значение должно быть в диапазоне [0.0f, 1.0f] . 0.0f (значение по умолчанию) соответствует полной непрозрачности, а 1.0f – полной прозрачности. В разделе Прозрачность далее в этой статье приводится пример кода и описывается взаимосвязь между прозрачностью и постепенным появлением изображений.
   • visible : тип Boolean. Указывает, является ли накладываемый фрагмент карты видимым. Если фрагмент невидимый (значение false ), он не отображается на карте, но сохраняет все остальные свойства. Значение по умолчанию – true .
   • zIndex : определяет порядок прорисовки мозаичного наложения относительно других наложений, включая наземные наложения, круги, ломаные линии и многоугольники. Наложения с более высокими значениями z-index прорисовываются выше наложений с меньшими значениями z-index. Порядок наложений с одинаковыми значениями z-index будет произвольным. По умолчанию z-индекс равен 0. Обратите внимание, что маркеры всегда располагаются поверх всех остальных наложений (независимо от значений z-индекса для этих наложений).
4. Чтобы добавить накладываемое изображение на карту, вызовите метод GoogleMap.addTileOverlay() .

Kotlin

Чтобы лучше понять, как действует UrlTileProvider , посмотрите реализацию TileOverlayDemoActivity в примере кода, прилагаемом к SDK сервисов Google Play.

Как настроить прозрачность накладываемых фрагментов карты

Прозрачные мозаичные наложения на карте применяются для того, чтобы пользователи могли видеть исходную карту под наложенными фрагментами. Для этого можно использовать собственные прозрачные фрагменты или установить коэффициент прозрачности мозаичных наложений программным образом.

В следующем примере кода показано, как изменить значение прозрачности с 0.5f на 0.0f или обратно.

Kotlin

Прозрачность реализуется как множитель альфа-канала для изображений фрагментов. Чтобы задать прозрачность накладываемого фрагмента, предоставьте объект TileOverlayOptions , где поле transparency имеет значение в диапазоне [0.0f, 1.0f] , как показано в примере выше. При значении 0.0f фрагмент полностью непрозрачен, а при значении 1.0f – полностью прозрачен. Значение по умолчанию – 0.0f (полная непрозрачность).

Получить значение прозрачности можно с помощью метода TileOverlay.getTransparency() , а изменить это значение – с помощью метода TileOverlay.setTransparency() .

Прозрачность, анимация и постепенное появление

При изменении прозрачности анимация не применяется. Параметр прозрачности используется вместе с параметром fadeIn.

Параметр Fade-in отвечает за анимацию прозрачности при загрузке фрагмента. Если установить значение прозрачности, фрагменты будут появляться постепенно – от полной прозрачности до ее установленного значения. Если изменить прозрачность во время постепенного появления, анимация будет продолжаться до нового заданного значения прозрачности.

Как удалить накладываемый фрагмент карты

Удалить накладываемый фрагмент карты можно с помощью метода TileOverlay.remove() .

Kotlin

Как удалить устаревшие фрагменты

Если фрагменты, используемые в мозаичном наложении, «устаревают», их можно обновить, вызвав метод clearTileCache() . В результате все фрагменты в этом наложении будут перезагружены. Например, если фрагменты, предоставленные с помощью TileProvider , изменились, нужно вызвать метод clearTileCache() , чтобы прежние фрагменты не отображались.

Kotlin

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Источник

Tile Overlays

A tile overlay, sometimes called a tile layer, is a collection of images that are displayed on top of the base map tiles.

Code Samples

The ApiDemos repository on GitHub includes a sample that demonstrates the tile overlay feature:

• TileOverlayDemoActivity — Java: Tile overlay features in Java
• TileCoordinateDemoActivity — Java: The coordinate system used for tile overlays in Java
• TileOverlayDemoActivity — Kotlin: Tile overlay features in Kotlin
• TileCoordinateDemoActivity — Kotlin: The coordinate system used for tile overlays in Kotlin

Introduction

A TileOverlay defines a set of images that are added on top of the base map tiles.

You need to provide the tiles for each zoom level that you want to support. If you have enough tiles at multiple zoom levels, you can supplement Google’s map data for the entire map.

Tile overlays are useful when you want to add extensive imagery to the map, typically covering large geographical areas. In contrast, ground overlays are useful when you wish to fix a single image at one area on the map.

You can also use transparent tile overlays to add extra features to the map, by setting a transparency factor on the tile overlay programmatically or by providing transparent tile images.

Tile coordinates and zoom levels

The Google Maps API breaks up the imagery at each zoom level into a set of square map tiles arranged in a grid. When a map moves to a new location, or to a new zoom level, the Maps API determines which tiles are needed and translates that information into a set of tiles to retrieve.

The tile with coordinates (0,0) is always at the northwest corner of the map, with x values increasing from west to east and y values increasing from north to south. Tiles are indexed using x,y coordinates from that origin.

At zoom level 0, the entire world is rendered in a single tile. Each zoom level increases the magnification by a factor of two. So, at zoom level 1 the map will be rendered as a 2×2 grid of tiles. At zoom level 2, it’s a 4×4 grid. At zoom level 3, it’s an 8×8 grid, and so on.

For example, at zoom level 2 the earth is divided into 16 tiles. Each tile can be referenced by a unique combination of x, y and zoom:

When creating images for a tile layer, you will need to create an image for each tile at each zoom level that you wish to support. Google Maps targets 256 dp (device-independent pixels) when displaying tiles. For high resolution devices, it is recommended that you return high dpi tiles (512×512 px). Refer to the Android Developers documentation for information on supporting different screen sizes and densities.

Note: The zoom levels supported by the camera depend on various factors, and are not related to the zoom levels that your tiles will support.

1. GoogleMap.getMaxZoomLevel() returns the maximum zoom level available at the current camera position. This takes into account the map type currently being used. For example, a satellite or terrain map may have a lower maximum zoom level than the base map tiles.
2. GoogleMap.getMinZoomLevel() returns the minimum zoom level, which is the same for every location (unlike the maximum zoom level) but may vary between devices and map sizes.

Add a tile overlay

The simplest and most common way of creating a tile overlay is to provide a URL pointing to the relevant tile image. UrlTileProvider is a partial implementation of TileProvider that provides image tiles based on a URL. This class requires that all the images have the same dimensions.

You will need to implement UrlTileProvider.getTileUrl() , which accepts the tile coordinates (x, y, zoom), and returns a URL pointing to the image to be used for the tile. The method should return null if there is no tile for the given x, y and zoom. A URL can point to a web resource, an Android asset, or a file on the local disk.

Set up your stock of tile images on a server, defined for all the x,y coordinates and zoom levels that you intend to support. Then add the tile overlay:

1. Define a UrlTileProvider to supply the tile images.
2. Override getTileUrl() to construct the URL for each tile image.
3. Provide a TileOverlayOptions object with the relevant options:
   • fadeIn : Boolean. Specifies whether the tiles should fade in. The default value is true . You may find it useful to turn off the fade-in when switching between tile overlays quickly. For information on the relationship between transparency and fade-in, see the section on transparency below.
   • tileProvider : The TileProvider to use for this overlay.
   • transparency : Float. Sets a transparency factor for tile images. The value must be in the range [0.0f, 1.0f] where 0.0f means fully opaque (default) and 1.0f means fully transparent. See the section on transparency below for a code sample and the relationship between transparency and fade-in.
   • visible : Boolean. Specifies the visibility of the tile overlay. An invisible tile overlay (value false ) is not drawn on the map, but retains all of its other properties. The default is true .
   • zIndex : Determines the order in which the tile overlay will be drawn in relation to other overlays, including ground overlays , circles, polylines and polygons. Overlays with a higher z-index are drawn on top of those with lower z-indexes. The order of overlays with the same z-index is arbitrary. The default z-index is 0. Note that markers are always drawn above other overlays, regardless of the z-index of the other overlays.
4. Call GoogleMap.addTileOverlay() to add the overlay to the map.

Kotlin

To see an example of a UrlTileProvider in action, refer to the TileOverlayDemoActivity in the sample code that is bundled with the Google Play services SDK.

Set transparency for tile overlays

It can be useful to overlay transparent tiles on the map, so that users can see the base map below the overlaid tiles. You can do this by providing your own transparent tiles, or by setting a transparency factor on the tile overlay programmatically.

The following code sample toggles the tile overlay’s transparency between 0.5f and 0.0f :

Kotlin

The transparency is implemented as an alpha channel multiplier for tile images. To set the transparency of a tile overlay, provide a TileOverlayOptions object with a transparency in the range [0.0f, 1.0f] as shown in the above sample. A value of 0.0f means the tile overlay is fully opaque and 1.0f means it’s fully transparent. The default value is 0.0f (opaque).

You can access the tile overlay’s transparency by calling TileOverlay.getTransparency() , and you can change it by calling TileOverlay.setTransparency() .

Transparency, animation, and fade-in

There is no animation when the transparency is changed. The transparency option operates alongside the fadeIn option.

Fade-in provides animation of transparency upon tile loading. If you set a transparency value, the tiles fade in from fully transparent to the defined transparency value. If you change the transparency during fade-in, the animation continues toward the new target transparency.

Remove a tile overlay

You can remove a tile overlay with the TileOverlay.remove() method.

Kotlin

Clear stale tiles

If the tiles provided by the tile overlay become ‘stale’, you can call clearTileCache() to force a refresh. This will cause all the tiles on this overlay to be reloaded. For example, if the tiles provided by the TileProvider change, you must call clearTileCache() afterwards to ensure that the previous tiles are no longer rendered.

Kotlin

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Источник