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

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

Примеры кода

Репозиторий 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-index для него.

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

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

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