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

Выберите платформу: 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.

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)

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

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

Kotlin



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

Java


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

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

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

Kotlin



imageOverlay?.remove()

Java


imageOverlay.remove();

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

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

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

Java


// 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. Координаты изображения зафиксированы по его нижнему левому углу.

Kotlin



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

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

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

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

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

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)

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

Как связать данные с наземным наложением

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

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

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"

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");

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

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

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

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

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