Práticas recomendadas para o 3D Maps

Este guia mostra em detalhes os componentes da Web de mapas em 3D e considerações ao integrar com seu aplicativo.

Exemplo de Place Search e rotas.

Considerações sobre desempenho

Para garantir uma experiência tranquila e responsiva para interatividade e elementos visuais, considere as abordagens a seguir.

Carregar o mapa

A configuração inicial de carregamento e renderização dos mapas 3D combina técnicas de configuração do navegador e práticas recomendadas de interface para otimizar a experiência do usuário.

• Carregamento da API: use o carregamento dinâmico assíncrono dos Mapas 3D para carregar a API Maps JavaScript no carregamento inicial da página.
• Bibliotecas: carregue bibliotecas de forma programática quando necessário, como google.maps.importLibrary("maps3d"). Como alternativa, se você usar componentes da Web como <gmp-map-3d> diretamente na sua página HTML com carregamento direto de script, as bibliotecas serão carregadas automaticamente no momento apropriado.
• Gerenciar recursos do mapa de base:use um mapId personalizado para filtrar PDIs do mapa de base (modo HYBRID) e controlar a densidade deles, principalmente se o aplicativo tiver o próprio conjunto de elementos personalizados, como marcadores ou polilinhas. Isso evita poluição visual e possíveis sobreposições. Como alternativa, é possível desativar os recursos de blocos vetoriais do mapa de base, como PDIs, polilinhas de estradas, nomes de estradas e nomes de ruas (modo SATÉLITE).
• Eventos: detecte eventos gmp-steadystate ou gmp-error para criar sua lógica subsequente, como carregar marcadores e animar a câmera.

Tela de fundo > Blocos minificados > Malha de terreno > Malha de superfície (por exemplo, edifícios) > Pontos de interesse e rótulos de vias, elementos personalizados sendo carregados em paralelo (marcadores, modelos 3D etc.)

• Interação do usuário:aguarde o evento gmp-steadystate antes de fazer mudanças no conteúdo do mapa. Se um usuário começar a interagir (movimentar, dar zoom) com o mapa antes do evento gmp-steadystate inicial, o evento só será acionado depois que o usuário parar de interagir. Evite mostrar ou atualizar conteúdo de sobreposição (como marcadores ou polígonos) enquanto o usuário move ou aumenta o zoom no mapa. Para isso, use gmp-centerchange, gmp-headingchange, gmp-rangechange, gmp-rollchange e gmp-tiltchange.

• Use requestAnimationFrame() (rAF) para atualizações contínuas e separe estritamente os cálculos intensivos das chamadas de desenho.

  • Use rAF: sincroniza as atualizações com a taxa de exibição do navegador para uma animação suave de 60 QPS e consumo de energia reduzido.
  • Evite trabalho de desenho intensivo: não realize tarefas pesadas que não sejam de desenho durante a atualização final.
  • Lógica separada: execute toda a lógica intensiva antes das chamadas de atualização mínimas do componente da Web no loop rAF.

• Configurações iniciais da cena: as configurações da câmera <gmp-map-3d>, como a inclinação, afetam a velocidade de carregamento. Quanto mais a cena for ampliada ou inclinada, mais polígonos detalhados serão exibidos e precisarão ser carregados. O nível de detalhe também depende do local (por exemplo, uma cidade com muitos edifícios em comparação com uma área rural com apenas elementos naturais).

  • Prefira visualizações com menos zoom (alta altitude), baixas ou não inclinadas.
  • Adicione limites (exemplo) ao mapa para que os usuários se concentrem em uma área específica e os blocos possam ser carregados por completo.

• Visual do pré-carregador: embora o <gmp-map-3d> carregue de forma extremamente rápida, pode levar algum tempo para que ele seja exibido em resolução máxima para usuários com dispositivos de baixo desempenho (GPU baixa) ou largura de banda (4G lento). Nesse caso, você pode criar um pré-carregador com imagem, animação ou texto com a cena 3D carregando em segundo plano. Confira abaixo o evento principal que você pode usar:

Exemplo de pré-carregador

// create the map in the background and wait for gmp-steadystate event
async function initMap() {
    await google.maps.importLibrary("maps3d");
    const map = document.querySelector('gmp-map-3d');
    const div = document.querySelector('div'); // preloader "
    map.addEventListener('gmp-steadystate', ({isSteady}) => {
        if (isSteady) {
            div.style.display = 'none';
        }
    });
}
initMap();

• Mapa 2D:
  • Um mapa 2D alternativo (SATELLITE) pode ser enviado a esses usuários, incluindo seus dados geográficos, como marcadores.

• Como alternativa, um mapa estático 2D complementar no modo SATÉLITE pode ser exibido para que os usuários visualizem um determinado lugar durante o carregamento.

Observação: cada carregamento de mapa 2D e 3D é cobrado separadamente. Portanto, renderize o segundo mapa somente quando os usuários quiserem interagir com ele.

Performance e gerenciamento de elementos visuais

O 3D Maps oferece várias maneiras de mostrar elementos visuais, como marcadores, polilinhas e modelos 3D, com desempenho ideal e tempo mínimo de renderização, mesmo para recursos visuais de maior volume.

Marcadores

Cenário de exemplo: 150 a 300 ms para carregar 300 marcadores com 41 glifos de marcador SVG diferentes (laptop moderno: macOS M3 Pro, Chrome)

• Escolha ideal de personalização:
  • PinElement:para mudanças básicas no marcador (cor, escala, borda, glifo de texto), use o elemento <gmp-pin> ou a classe PinElement. Esse é o método de personalização mais eficiente.
  • Use marcadores HTMLImageElement ou SVGElement com moderação:use para mais personalização, como adicionar transparência ou injetar uma imagem, como um ícone, em um SVGElement (requer codificação base64). Eles serão rasterizados no carregamento e envolvem sobrecarga de desempenho. HTMLImageElement e SVGElement precisam ser agrupados no elemento <template> antes de serem atribuídos ao slot padrão do Marker3DElement.
  • No momento, não é possível adicionar HTML ou CSS simples.
• Gerenciar o comportamento em caso de conflito: use a propriedade collisionBehavior do marcador. Para marcadores críticos que precisam estar sempre visíveis, defina o comportamento adequadamente. Para marcadores menos importantes, permita que eles sejam ocultados para manter uma experiência de mapa mais limpa e menos confusa, especialmente em níveis de zoom altos.
• Somente PDIs críticos: use drawsWhenOccluded (ou defina a propriedade de forma programática) apenas para marcadores que precisam ser vistos através de edifícios ou terrenos (por exemplo, um alvo de resgate, uma linha de utilidade enterrada ou o avatar de um usuário).
• Testar oclusão:como o mapa é 3D, os marcadores podem ser visualmente obscurecidos (ocluídos) por edifícios ou terrenos. Teste diferentes ângulos de câmera e altitudes de marcadores para garantir que os PDIs importantes permaneçam visíveis ou implemente uma lógica para ajustar a visibilidade e a altitude quando houver oclusão.
• Aproveite a altitude:em mapas 3D, os marcadores precisam usar a posição com um valor de altitude. Para marcadores associados ao terreno ou a edifícios, use altitudeMode: 'RELATIVE_TO_GROUND', 'RELATIVE_TO_MESH' ou configurações semelhantes para garantir que o marcador seja fixado corretamente quando o mapa for inclinado ou girado.

Polígonos e polilinhas

Cenário de exemplo: 100 a 150 ms para carregar 1.000 polígonos (laptop moderno: macOS M3 Pro, Chrome)

• Simplificar geometria: antes de renderizar, aplique um algoritmo de simplificação aos dados do caminho. Isso reduz o número de vértices, mas mantém a forma geral, melhorando drasticamente a velocidade de renderização, especialmente para limites ou rotas complexas.
• Decimação por nível de zoom: para conjuntos de dados muito grandes, considere carregar geometria com mais detalhes apenas quando o usuário estiver com zoom na área. Em um nível de zoom baixo, apenas uma versão altamente simplificada da polilinha ou do polígono é necessária.
• Pré-calcular para polígonos extrudados: se os polígonos forem extrudados (extruded: true), os dados do caminho vão definir um volume 3D (uma malha). O processamento de polígonos complexos com muitos vértices é computacionalmente caro. Verifique se os dados de origem dos polígonos são os mais simples possíveis.
• Teste o desempenho de polilinhas e polígonos:ao adicionar polilinhas/polígonos numerosos ou complexos, especialmente quando extrudados para 3D, verifique se eles não causam quedas na taxa de frames. Limite o número de vértices ou use algoritmos de simplificação, se necessário.
• Ao atualizar uma forma, modifique toda a matriz de caminho em uma única operação, em vez de repetir e modificar elementos individuais. Uma única operação de atribuição (por exemplo, polyline.path = newPathArray;) é muito mais eficiente do que várias atualizações iterativas.
• Evite polilinhas extrudadas (quando possível): embora as polilinhas possam usar um valor de altitude para serem colocadas no espaço 3D, a extrusão de uma polilinha (por exemplo, com uma largura de traço e um grande intervalo de altitude) pode ser graficamente intensa. Sempre que possível, use polilinhas 2D no chão (RELATIVE_TO_GROUND) ou uma largura de traço mínima para melhorar o desempenho.
• Use drawsOccludedSegments apenas para elementos de trajeto críticos. Para formas de plano de fundo ou contextuais, permita que elas sejam naturalmente ocultadas pela geometria 3D do mapa. Mostrar geometria oculta não crítica adiciona complexidade de renderização desnecessária.

Modelos 3D

A renderização e a interatividade do modelo 3D .glb, como o evento de clique gmp-click, são muito rápidas em <gmp-map-3d>.

Exemplo de cenário: leva cerca de 2 segundos para exibir 1.000 ocorrências de um modelo 3D leve (200 KB) se movendo ao longo de um trajeto. (laptop moderno: macOS M3 Pro, Chrome)

• Minimize o tamanho do arquivo com compactação: para garantir um carregamento rápido, especialmente em redes móveis, mantenha os arquivos de modelo .glb complexos com menos de 5 MB (idealmente menos). O principal método para isso é aplicar a compactação Draco aos dados de malha nos arquivos .glb, o que pode reduzir significativamente o tamanho do arquivo (geralmente em mais de 50%) com perda mínima de qualidade visual.
• Origem do modelo central:verifique se o software de modelagem 3D exporta o modelo com a origem (ponto 0, 0, 0) centralizada na base do modelo. Isso simplifica o posicionamento e a rotação no mapa, garantindo que o modelo seja fixado corretamente nas coordenadas de latitude e longitude.
• Gerenciar o CORS: se os arquivos do modelo estiverem hospedados em um domínio ou CDN diferente do aplicativo da Web, você precisará configurar o servidor de hospedagem para incluir os cabeçalhos de compartilhamento de recursos entre origens (CORS) necessários (por exemplo, Access-Control-Allow-Origin: *). Caso contrário, o mapa não poderá carregar o modelo.