Наземные наложения

Выберите платформу: Android iOS JavaScript

Наземные наложения – это графические объекты, которые привязываются к определенным точкам на карте и, следовательно, меняют свои размеры и положение на экране при перетаскивании и масштабировании карты.

Примеры кода

Репозиторий ApiDemos в GitHub содержит примеры, демонстрирующие использование наземных наложений.

  • GroundOverlayDemoActivity (Java): как реализовать свойства и прослушиватели для наземного наложения на Java.
  • GroundOverlayDemoActivity (Kotlin): как реализовать свойства и прослушиватели для наземного наложения на Kotlin.

Введение

Наземное наложение – это графический объект, закрепленный в определенном месте карты. В отличие от маркера, его ориентация рассчитывается относительно земной поверхности, а не относительно экрана, поэтому она меняется при вращении, наклоне и приближении карты. Наземные наложения применяются в случаях, когда необходимо закрепить одно изображение на небольшом участке карты. Если вы хотите добавить большое изображение, покрывающее обширный участок карты, используйте наложение фрагмента карты.

Как добавить наложение

Прежде чем добавить наложение (объект GroundOverlay), вам необходимо создать объект GroundOverlayOptions и определить в нем как само изображение, так и его координаты. При желании вы также можете задать в нем настройки позиционирования. Чтобы добавить изображение на карту, передайте созданный объект методу GoogleMap.addGroundOverlay(). Метод addGroundOverlay() возвращает объект GroundOverlay. Сохраните ссылку на этот объект, чтобы вы могли изменить его позже.

Пошаговые инструкции:

  1. Создайте новый экземпляр объекта GroundOverlayOptions.
  2. Определите изображение как BitmapDescriptor.
  3. Установите положение изображения с помощью одного из доступных методов:
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. При необходимости задайте дополнительные свойства, такие как transparency.
  5. Чтобы добавить изображение на карту, вызовите метод GoogleMap.addGroundOverlay().

Показанный ниже код добавляет наземное наложение в существующий объект GoogleMap.

Java


LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

Kotlin


val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

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

Java


// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

Kotlin


// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

Как удалить наложение

Чтобы удалить наложение, вызовите метод GroundOverlay.remove().

Java


imageOverlay.remove();

Kotlin


imageOverlay?.remove()

Как изменить наложение

Добавленное наземное наложение можно изменить с помощью метода GroundOverlay.setImage(BitmapDescriptor).

Java


// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

Kotlin


// Update the GroundOverlay with a new image of the same dimension

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

Метод setImage() позволяет заменить существующее изображение на другое с теми же размерами.

Как задать позицию наложения

Указать положение наземного наложения можно двумя способами:

  • определить его центр с помощью объекта LatLng и указать размеры в метрах;
  • определить северо-восточный и юго-западный углы изображения с помощью объекта LatLngBounds.

Позицию наложения необходимо указать до того, как вы добавите его на карту.

Как задать положение с помощью координат

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

Показанный ниже код размещает изображение шириной 8,6 км и высотой 6,5 км в точке 40.714086, -74.228697. Координаты изображения зафиксированы по его нижнему левому углу.

Java


GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

Kotlin


val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

Как задать положение с помощью объекта LatLngBounds

В этом случае создается объект LatLngBounds, определяющий границы изображения. В объекте LatLngBounds задаются северо-восточный и юго-западный углы изображения. При размещении изображения на карте оно будет повернуто так, чтобы уместиться в заданные границы. Если границы не соответствуют исходным пропорциям изображения, оно будет искажено.

Показанный ниже код добавляет на карту изображение, юго-западный угол которого имеет координаты 40.712216,-74.22655, а северо-восточный – 40.773941, -74.12544.

Java


LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);

Kotlin


val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

Связь данных с наземным наложением

Связать произвольный объект данных с наземным наложением можно с помощью метода GroundOverlay.setTag(), а извлечь его значение – с помощью метода GroundOverlay.getTag().

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

Java


GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

Kotlin


val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

Возможность сохранять и получать данные о наземных наложениях может пригодиться в разных ситуациях, например:

  • Вы хотите, чтобы нажатия на наложениях разных типов обрабатывались в приложении по-разному.
  • Наложения связаны с разными объектами из другой системы, причем у каждого объекта есть уникальный идентификатор.
  • Вам необходимо сохранять данные, от которых будет зависеть Z-индекс наложения.

Обработка событий для наземных наложений

По умолчанию наземные наложения не кликабельны. Чтобы включить или отключить кликабельность, необходимо вызвать метод GroundOverlay.setClickable(boolean).

Чтобы отслеживать клики в активных наземных наложениях, используйте прослушиватель OnGroundOverlayClickListener. Чтобы добавить его на карту, вызовите метод GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Когда пользователь нажимает на наземное наложение, вы получаете обратный вызов метода onGroundOverlayClick(GroundOverlay).