Sobreposições de solo

São sobreposições de imagem vinculadas a coordenadas de latitude/longitude. Portanto, elas se movimentam quando você arrasta o mapa ou aplica zoom a ele.

Amostras de código

O repositório ApiDemos no GitHub inclui um exemplo que demonstra sobreposições de solo:

Introdução

Uma sobreposição de solo é uma imagem fixa em um mapa. Diferentemente dos marcadores, essas sobreposições são orientadas contra a superfície da Terra e não da tela, então um giro, uma inclinação ou um zoom no mapa altera a orientação da imagem. Elas são úteis quando você quer corrigir uma única imagem em uma área do mapa. Para adicionar imagens abrangentes que cobrem uma parte grande do mapa, considere usar uma sobreposição de blocos.

Adicionar uma sobreposição

Para incluir um GroundOverlay, crie um objeto GroundOverlayOptions que define uma imagem e uma posição. Também é possível especificar configurações adicionais que afetam o posicionamento da imagem no mapa. Após definir as opções necessárias, transfira o objeto ao método GoogleMap.addGroundOverlay() para incluir a imagem no mapa. O método addGroundOverlay() retorna um objeto GroundOverlay. Mantenha uma referência a esse objeto se quiser editá-lo mais tarde.

Instruções:

  1. Instancie um novo objeto GroundOverlayOptions.
  2. Especifique a imagem como um BitmapDescriptor.
  3. Defina a posição dela usando um dos métodos disponíveis:
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. Defina propriedades opcionais (por exemplo: transparency), se for o caso.
  5. Chame GoogleMap.addGroundOverlay() para adicionar a imagem ao mapa.

O exemplo abaixo demonstra como incluir uma sobreposição de solo em um objeto GoogleMap existente.

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

Se você quiser alterar ou remover uma sobreposição desse tipo depois de adicioná-la ao mapa, mantenha o objeto GroundOverlay. Você pode modificar a sobreposição mais tarde, fazendo alterações nesse objeto.

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

Remover uma sobreposição

Você pode remover uma sobreposição de solo com o método GroundOverlay.remove().

imageOverlay.remove();
    

Alterar uma sobreposição

É possível alterar a imagem da sobreposição de solo após ela ter sido adicionada ao mapa com o método 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));
    

O método setImage() substituirá a imagem existente por outra com as mesmas dimensões.

Posicionar uma sobreposição de solo

Há duas formas de especificar a posição da sobreposição de solo:

  • Usando um LatLng para centralizar a sobreposição e definir as dimensões em metros, especificando o tamanho da imagem.
  • Utilizando um LatLngBounds para indicar os cantos nordeste e sudoeste da imagem.

Você precisa especificar a posição da sobreposição de solo antes de adicioná-la ao mapa.

Usar a localização para posicionar uma imagem

Ao adicionar uma imagem, você especifica um LatLng em que a âncora será fixada e a largura da sobreposição (em metros). A anchor irá para o centro da imagem, que é o padrão. Também é possível informar a altura da sobreposição (em metros). Se você não fornecer esse valor, ele será calculado automaticamente para preservar as proporções da imagem.

Com o código a seguir, uma imagem é inserida na posição 40.714086, -74.228697, que tem 8,6 km de largura por 6,5 km de altura. A imagem está fixada no canto inferior esquerdo.

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

Usar LatLngBounds para posicionar uma imagem

Você informa uma LatLngBounds, que contém a imagem. A LatLngBounds define os cantos nordeste e sudoeste da imagem. Quando inserida no mapa, ela é girada para se encaixar nos limites. Se os limites não corresponderem à proporção original, a imagem será distorcida.

Com o código a seguir, uma imagem é inserida no mapa com o canto sudoeste 40.712216,-74.22655 e o canto nordeste 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);
    

Associar dados a uma sobreposição de solo

Você pode chamar GroundOverlay.setTag() para armazenar um objeto de dados arbitrários com uma sobreposição de solo e recuperar esse objeto usando GroundOverlay.getTag().

Na amostra de código a seguir, há uma descrição de string armazenada com uma sobreposição de solo:

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

Veja alguns exemplos de situações em que é útil armazenar e recuperar dados com sobreposições de solo:

  • Seu app pode oferecer várias sobreposições de solo, e você quer tratá-las de forma diferente quando o usuário clicar nelas.
  • Você está interagindo com um sistema que tem identificadores de registros exclusivos, em que as sobreposições representam registros específicos.
  • Os dados da sobreposição podem indicar uma prioridade para determinar o Z-index dela.

Lidar com eventos de sobreposição de solo

Por padrão, essas sobreposições não são clicáveis. Para ativar e desativar a clicabilidade, chame GroundOverlay.setClickable(boolean).

Use um OnGroundOverlayClickListener para detectar os eventos de clique em uma sobreposição de solo clicável. Para definir esse listener no mapa, chame GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Quando um usuário clicar em uma sobreposição desse tipo, você receberá um callback onGroundOverlayClick(GroundOverlay).