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

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

Примеры кода

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

Введение

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

Добавление наложения

Чтобы добавить такое наложение (объект 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.

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

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

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

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

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

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

Удаление наложения

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

imageOverlay.remove();

Изменение наложения

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

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

// Update the GroundOverlay with a new image of the same dimensions.
imageOverlay = map.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1975));

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

Позиционирование наземного наложения

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

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

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

Позиционирование наложения с помощью координат

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

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

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.

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

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

private GoogleMap mMap;
private GroundOverlay mSydneyGroundOverlay;

mSydneyGroundOverlay = mMap.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206))
    .clickable(true));

mSydneyGroundOverlay.setTag("Sydney");

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

  • Ваше приложение может обрабатывать различные типы наземных наложений, и вам нужно, чтобы они обрабатывались по-разному, когда пользователь нажимает на них.
  • Возможно взаимодействие с системой, в которой имеются уникальные идентификаторы записей, где наложения представляют собой особые записи.
  • Данные наложения могут указывать на приоритет при определении параметра z-index для него.

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

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

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