1. Antes de começar
Este codelab tem como objetivo ajudar você a entender como criar seu primeiro mapa 3D usando mapas 3D fotorrealistas na API Maps JavaScript. Você vai aprender os conceitos básicos sobre o carregamento dos componentes certos da API Maps JavaScript, exibir seu primeiro mapa 3D e desenhar recursos nele.
O que você vai criar.
Neste codelab, você vai criar um app da Web 3D que:
- Carrega a API Maps JavaScript de forma dinâmica.
- Mostra um mapa 3D centralizado na CN Tower em Toronto.
- Mostra um limite em torno de um local.
- Desativa os pontos de interesse no mapa 3D.
- Extrude a borda para cobrir o local.
O que você vai aprender
- Começar a usar a Plataforma Google Maps.
- Carregar a API Maps JavaScript dinamicamente pelo código JavaScript usando a importação de biblioteca dinâmica.
- Carregue um mapa 3D usando a classe Map3DElement.
- Usando polígonos e extrusão para desenhar no mapa.
2. Pré-requisitos
Você precisa se familiarizar com os itens aqui para concluir este codelab. Caso você já tenha trabalhado com a Plataforma Google Maps, avance para o codelab.
Produtos obrigatórios da Plataforma Google Maps
Neste codelab, você usará os seguintes produtos da Plataforma Google Maps:
- API Maps JavaScript
Sim, é só isso que você precisa para adicionar o Maps em 3D à sua página. Nada mais, muito simples!
Outros requisitos para este codelab
Para concluir este codelab, você precisará das seguintes contas, serviços e ferramentas:
- Uma conta do Google Cloud com o faturamento ativado
- Uma chave de API da Plataforma Google Maps com a API Maps JavaScript ativada
- Conhecimento básico de JavaScript, HTML e CSS
- Um editor de texto ou ambiente de desenvolvimento integrado de sua escolha para salvar e editar um arquivo para visualização
- Um navegador da Web para visualizar o arquivo enquanto você trabalha
3. Começar a configuração
Configurar a Plataforma Google Maps
Caso você ainda não tenha uma conta do Google Cloud Platform e um projeto com faturamento ativado, veja como criá-los no guia da Plataforma Google Maps.
- No Console do Cloud, clique no menu suspenso do projeto e selecione o projeto que você quer usar neste codelab.
- Ative as APIs e os SDKs da Plataforma Google Maps necessários para este codelab no Google Cloud Marketplace. Para fazer isso, siga as etapas descritas neste vídeo ou nesta documentação.
- Gere uma chave de API na página Credenciais do Console do Cloud. Siga as etapas indicadas neste vídeo ou nesta documentação. Todas as solicitações à Plataforma Google Maps exigem uma chave de API.
4. Carregar a API Maps JavaScript
Depois de seguir todas as etapas na seção de configuração, você já pode começar a criar seu primeiro mapa 3D.
Crie a página da Web mais simples que você conseguir imaginar.
Primeiro, vamos criar uma página da Web muito básica para hospedar todo o código. Você pode fazer isso em qualquer editor ou plataforma.
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
</body>
</html>
Adicione o código e salve o arquivo em um local acessível usando um nome como 3dmap.html. Em seguida, abra o arquivo em um navegador da Web para conferir o estado atual da página e verificar se há erros.
Assim como os mapas 2D, a base dos mapas 3D é a API Maps JavaScript. Portanto, primeiro você precisa fazer o carregamento dela.
Isso pode ser feito de várias maneiras, que você encontra na seção Carregar a API Maps JavaScript da documentação.
Nesta demonstração, vamos usar o método de importação de biblioteca dinâmica mais moderno, que permite controlar apenas os elementos que você precisa carregar, economizando no tamanho do download e nos tempos de inicialização.
Adicionar o carregador dinâmico
Para usar o carregador dinâmico, adicione a tag de script a seguir à página da Web, incluindo sua própria CHAVE DE API no local apropriado (que você obteve na etapa 2). Coloque essa tag de script entre as seções do corpo da página da Web básica.
<script async defer>
(g => { var h, a, k, p = "The Google Maps JavaScript API", c = "google", l = "importLibrary", q = "__ib__", m = document, b = window; b = b[c] || (b[c] = {}); var d = b.maps || (b.maps = {}), r = new Set, e = new URLSearchParams, u = () => h || (h = new Promise(async (f, n) => { await (a = m.createElement("script")); e.set("libraries", [...r] + ""); for (k in g) e.set(k.replace(/[A-Z]/g, t => "_" + t[0].toLowerCase()), g[k]); e.set("callback", c + ".maps." + q); a.src = `https://maps.${c}apis.com/maps/api/js?` + e; d[q] = f; a.onerror = () => h = n(Error(p + " could not load.")); a.nonce = m.querySelector("script[nonce]")?.nonce || ""; m.head.append(a) })); d[l] ? console.warn(p + " only loads once. Ignoring:", g) : d[l] = (f, ...n) => r.add(f) && u().then(() => d[l](f, ...n)) })({
key: "YOUR_API_KEY",
v: "alpha",
});
</script>
Neste estágio do lançamento do produto, estamos usando a versão alfa da API para ter acesso aos Mapas 3D. Ele contém os recursos mais experimentais dos produtos e permite testar o código de acesso antecipado conforme ele é desenvolvido para que você possa usá-lo no momento do lançamento.
Agora você tem uma página da Web básica que contém o carregador dinâmico. Se você abrir a página, a visualização vai estar em branco, mas não vai ter erros. Agora você pode adicionar o mapa 3D.
Se por algum motivo o código não funcionar, acesse a Etapa 6 e compare-o com o resultado final para saber o que está errado.
Para descobrir por que a página não está funcionando, analise o console de erros no navegador para depurar o motivo. A página de erros mostra instruções sobre como fazer isso em diferentes navegadores, explica várias mensagens de erro e apresenta alguns motivos comuns para a API não funcionar. Esse é um bom recurso para usar durante o desenvolvimento para descobrir o que pode estar errado em qualquer implementação.
5. Exibir um mapa
Agora estamos prontos para adicionar nosso primeiro mapa 3D à página.
Os mapas 3D são criados usando a classe google.maps.maps3d.Map3DElement, que permite criar e trabalhar com instâncias de mapa 3D. Neste codelab, vamos trabalhar com o objeto do mapa 3D diretamente, em vez de usar a tag HTML.
Criar a função de inicialização e carregar a biblioteca
Primeiro, vamos criar uma função que carregue o elemento na página. No código, primeiro criamos uma função assíncrona, que permite verificar se todo o elemento foi carregado antes de prosseguir com o restante do código. Em seguida, executamos a função init conforme a página é carregada.
Adicione isso depois do script de carregamento na seção do corpo da página.
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
}
init();
</script>
Usamos a expressão await para garantir que a biblioteca seja carregada antes de prosseguir.
Criar o elemento do mapa 3D e especificar o local
Em seguida, precisamos especificar o local em que queremos ter a visualização do mapa. Para os Mapas 3D, há vários parâmetros diferentes que podem ser usados para definir a visualização. Eles se referem aos parâmetros da câmera virtual que descrevem o que você está vendo na cena.
Vamos criar uma vista da CN Tower que se parece com esta.
Primeiro, precisamos especificar as coordenadas que queremos analisar. Eles são compostos por duas visualizações diferentes:
- O ponto que queremos analisar, incluindo a altitude dele.
- A distância e a direção da câmera virtual que está olhando para o ponto.
A imagem a seguir mostra como essas configurações funcionam.
O centro do elemento é o ponto que você está vendo, enquanto o alcance é a distância que você está do objeto e a inclinação é o ângulo em que você está vendo a imagem. Você também pode definir a inclinação e a rotação do objeto, se quiser controlá-los, mas não vamos usar isso aqui.
Agora vamos criar o mapa 3D na página. Adicione o código abaixo à página na seção de inicialização depois que a biblioteca for importada.
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.HYBRID,
});
document.body.append(map3DElement);
Primeiro, criamos o elemento e definimos os parâmetros de localização apropriados. Em seguida, adicionamos o componente à página. Se quisermos, podemos atribuir o componente a um div existente.
Seu código vai ficar parecido com o exemplo aqui:
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<script async defer>
(g => { var h, a, k, p = "The Google Maps JavaScript API", c = "google", l = "importLibrary", q = "__ib__", m = document, b = window; b = b[c] || (b[c] = {}); var d = b.maps || (b.maps = {}), r = new Set, e = new URLSearchParams, u = () => h || (h = new Promise(async (f, n) => { await (a = m.createElement("script")); e.set("libraries", [...r] + ""); for (k in g) e.set(k.replace(/[A-Z]/g, t => "_" + t[0].toLowerCase()), g[k]); e.set("callback", c + ".maps." + q); a.src = `https://maps.${c}apis.com/maps/api/js?` + e; d[q] = f; a.onerror = () => h = n(Error(p + " could not load.")); a.nonce = m.querySelector("script[nonce]")?.nonce || ""; m.head.append(a) })); d[l] ? console.warn(p + " only loads once. Ignoring:", g) : d[l] = (f, ...n) => r.add(f) && u().then(() => d[l](f, ...n)) })({
key: "YOUR_API_KEY",
v: "alpha",
});
</script>
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.HYBRID
});
document.body.append(map3DElement);
}
init();
</script>
</body>
</html>
Agora podemos salvar o arquivo e abrir a página em um navegador para conferir se está funcionando. A câmera deve estar apontada para a torre, como mostrado na imagem. Brinque um pouco antes de continuar e adicionar uma caixa sobre a torre.
6. Adicionar e extrair elementos
Agora que temos um mapa 3D, vamos destacar um objeto para os usuários, indicando que ele é um item de interesse. Neste caso, vamos usar um polígono e a função de extrusão para criar uma caixa ao redor da CN Tower, para que ela fique mais ou menos como na imagem a seguir.
Ocultar a desordem
A primeira coisa que você vai notar é que desativamos os pontos de interesse. Neste mapa, queremos que o foco seja a própria torre. Por isso, precisamos nos livrar dos outros elementos visuais.
Para fazer isso, precisamos mudar o código para ocultar os rótulos. Atualize a linha de modo do mapa para SATELLITE para ocultar os pontos.
mode: MapMode.SATELLITE,
A definição dessa propriedade desativa os rótulos no mapa, incluindo pontos de interesse, vias e linhas de fronteira, e cria uma visualização "limpa" do local.
Adicionar e estilizar o polígono
A próxima etapa é adicionar o polígono à página. Isso pode ser feito em duas etapas. Primeiro, precisamos carregar as funções que contêm as informações necessárias e, em seguida, especificar os detalhes de estilo do polígono, como a cor ou se ele aparece atrás de outros elementos.
Primeiro, adicionamos as classes necessárias à página usando a seguinte linha de código.
const { Polygon3DElement, AltitudeMode } = await google.maps.importLibrary("maps3d");
Isso carrega as classes Polygon3DElement e AltitudeMode na página, que são necessárias para adicionar um objeto de polígono à visualização.
Um polígono pode ter várias configurações diferentes que controlam a visualização, desde a largura do traço, a cor (por nome ou valor hexadecimal) e a opacidade das configurações de limite e preenchimento, até controlar se ele é mostrado atrás de outros elementos ou edifícios, por exemplo : desenhar segmentos ocultos. Confira mais detalhes na documentação da classe Polygon3DElement.
O outro recurso que precisamos definir é para que o polígono seja desenhado de forma extrudada. Isso significa desenhar um polígono na altitude definida e estendê-lo até o solo. Isso dá ao polígono uma quantidade de altura como uma caixa (que você pode ver na imagem acima). Isso também exige que definamos o modo de altitude no polígono, e é por isso que precisamos carregar as constantes AltitudeMode acima. Para extrair um polígono, ele precisa ser definido como ABSOLUTE ou RELATIVE_TO_GROUND para receber a posição correta das alturas nos vértices do polígono.
O código cria um objeto literal que contém essas propriedades, que podem ser usadas para criar o objeto Polygon3DElement, conforme mostrado:
const polygonOptions = {
strokeColor: "#EA433580",
strokeWidth: 4,
fillColor: "#0000FF80",
altitudeMode: "ABSOLUTE",
extruded: true,
drawsOccludedSegments: true,
}
const towerPolygon = new google.maps.maps3d.Polygon3DElement(polygonOptions);
Agora que criamos o objeto polígono, também precisamos definir as coordenadas geográficas dele. Os polígonos podem ter coordenadas internas e externas, dependendo de como são representados. As innerCoordinates definem a forma dos recortes dentro do polígono, e as outerCoordinates definem o limite externo do polígono. Como este é um polígono e não uma linha, as coordenadas precisam começar e terminar no mesmo ponto para formar uma forma completa.
É possível especificar as coordenadas usando uma matriz de objetos ou literais LatLng ou LatLngAltitude, e podemos conferir isso no nosso polígono básico.
towerPolygon.outerCoordinates = [
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 },
{ lat: 43.6421742, lng: -79.3869184, altitude: 600 },
{ lat: 43.643001, lng: -79.3866475, altitude: 600 },
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 }
];
Agora que definimos o estilo e as coordenadas do polígono, podemos adicioná-lo à página. Os polígonos são elementos filhos do elemento do mapa e precisam ser adicionados a um objeto de mapa existente na página. Adicione o seguinte código à página.
map3DElement.append(towerPolygon);
Depois disso, teremos a implementação completa mostrada aqui, exceto que ela terá sua própria chave de API. Agora podemos executar a página e conferir o resultado.
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<script async defer>
(g => { var h, a, k, p = "The Google Maps JavaScript API", c = "google", l = "importLibrary", q = "__ib__", m = document, b = window; b = b[c] || (b[c] = {}); var d = b.maps || (b.maps = {}), r = new Set, e = new URLSearchParams, u = () => h || (h = new Promise(async (f, n) => { await (a = m.createElement("script")); e.set("libraries", [...r] + ""); for (k in g) e.set(k.replace(/[A-Z]/g, t => "_" + t[0].toLowerCase()), g[k]); e.set("callback", c + ".maps." + q); a.src = `https://maps.${c}apis.com/maps/api/js?` + e; d[q] = f; a.onerror = () => h = n(Error(p + " could not load.")); a.nonce = m.querySelector("script[nonce]")?.nonce || ""; m.head.append(a) })); d[l] ? console.warn(p + " only loads once. Ignoring:", g) : d[l] = (f, ...n) => r.add(f) && u().then(() => d[l](f, ...n)) })({
key: "YOUR_API_KEY",
v: "alpha",
});
</script>
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.SATELLITE,
});
const { Polygon3DElement, AltitudeMode } = await google.maps.importLibrary("maps3d");
const polygonOptions = {
strokeColor: "#EA433580",
strokeWidth: 4,
fillColor: "#0000FF80",
fillOpacity: 0.2,
altitudeMode: "ABSOLUTE",
extruded: true,
drawsOccludedSegments: true,
}
const towerPolygon = new google.maps.maps3d.Polygon3DElement(polygonOptions);
towerPolygon.outerCoordinates = [
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 },
{ lat: 43.6421742, lng: -79.3869184, altitude: 600 },
{ lat: 43.643001, lng: -79.3866475, altitude: 600 },
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 }
];
map3DElement.append(towerPolygon);
document.body.append(map3DElement);
}
init();
</script>
</body>
</html>
Se o código estiver correto, você verá uma página com o mapa 3D e o polígono a seguir.
Você criou seu primeiro mapa 3D usando a Plataforma Google Maps, incluindo o carregamento da API Maps JavaScript, a criação de um mapa 3D e a adição de um polígono extrudado.
7. A seguir
Neste codelab, você viu as noções básicas do que é possível fazer com a API Maps JavaScript. Agora, tente incluir alguns destes recursos no mapa:
- Adicione um botão para ativar e desativar os pontos de interesse.
- Adicione algumas linhas que mostrem uma rota de e para lugares diferentes.
- Defina algumas restrições de limite para controlar para onde o usuário pode mover a visualização.
- Confira as outras bibliotecas disponíveis para a API Maps JavaScript que ativam outros serviços, como o Places ou o Directions.
Para continuar aprendendo mais maneiras de trabalhar com a Plataforma Google Maps e o 3D na Web, confira estes links: