1. Avant de commencer
Cet atelier de programmation vous explique comment créer votre première carte 3D à l'aide des cartes 3D photoréalistes dans Maps JavaScript. Vous découvrirez les bases du chargement des composants appropriés de l'API Maps JavaScript, de l'affichage de votre première carte 3D et du dessin d'éléments dessus.
Ce que vous allez créer
Dans cet atelier de programmation, vous allez créer une application Web 3D qui:
- Charge l'API Maps JavaScript de manière dynamique.
- Affiche une carte 3D centrée sur la tour CN de Toronto.
- Affiche une limite autour d'un lieu.
- Désactive les points d'intérêt sur la carte 3D.
- Extrude la limite pour couvrir l'emplacement.
Points abordés
- Premiers pas avec Google Maps Platform
- Charger dynamiquement l'API Maps JavaScript à partir de code JavaScript à l'aide de Dynamic Library Import
- Chargez une carte 3D à l'aide de la classe Map3DElement.
- Utilisation de polygones et d'extrusion pour dessiner sur la carte
2. Prérequis
Vous devez vous familiariser avec les éléments ci-dessous pour suivre cet atelier de programmation. Si vous maîtrisez déjà Google Maps Platform, passez directement à l'atelier !
Produits Google Maps Platform requis
Dans cet atelier de programmation, vous utiliserez les produits Google Maps Platform suivants :
- API Maps JavaScript
Oui, c'est tout ce dont vous avez besoin pour ajouter Maps 3D à votre page. Rien d'autre. C'est très simple !
Autres conditions requises pour cet atelier de programmation
Pour suivre cet atelier de programmation, vous aurez besoin des comptes, des services et des outils suivants :
- Un compte Google Cloud pour lequel la facturation est activée
- Une clé API Google Maps Platform pour laquelle l'API Maps JavaScript est activée
- Connaissances de base sur JavaScript, HTML et CSS
- Un éditeur de texte ou un IDE de votre choix, pour enregistrer et afficher un fichier modifié
- Un navigateur Web pour afficher le fichier pendant que vous travaillez
3. Configuration
Configurer Google Maps Platform
Si vous ne disposez pas encore d'un compte Google Cloud Platform et d'un projet pour lequel la facturation est activée, consultez le guide Premiers pas avec Google Maps Platform pour savoir comment créer un compte de facturation et un projet.
- Dans Cloud Console, cliquez sur le menu déroulant des projets, puis sélectionnez celui que vous souhaitez utiliser pour cet atelier de programmation.
- Activez les API et les SDK Google Maps Platform requis pour cet atelier de programmation dans Google Cloud Marketplace. Pour ce faire, suivez les étapes indiquées dans cette vidéo ou dans cette documentation.
- Générez une clé API sur la page Identifiants de Cloud Console. Vous pouvez suivre la procédure décrite dans cette vidéo ou dans cette documentation. Toutes les requêtes envoyées à Google Maps Platform nécessitent une clé API.
4. Charger l'API Maps JavaScript
Une fois que vous avez suivi toutes les étapes de la section "Configuration", vous pouvez commencer à créer votre première carte 3D.
Créez la page Web la plus simple que vous puissiez imaginer.
Nous allons d'abord créer une page Web très basique pour héberger tout notre code. Vous pouvez le faire dans n'importe quel éditeur ou plate-forme de votre choix.
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
</body>
</html>
Ajoutez le code et enregistrez le fichier dans un emplacement accessible sous un nom tel que 3dmap.html, puis ouvrez-le dans un navigateur Web pour afficher l'état actuel de la page et voir si vous rencontrez des erreurs.
Comme pour Maps 2D, Maps 3D repose sur l'API Maps JavaScript. Vous devez donc commencer par la charger.
Pour ce faire, vous pouvez utiliser plusieurs méthodes, que vous trouverez dans la section Charger l'API Maps JavaScript de la documentation.
Dans cette démonstration, nous allons utiliser la méthode d'importation de bibliothèque dynamique plus moderne, car elle vous permet de contrôler uniquement les éléments que vous devez charger, ce qui réduit la taille de téléchargement et les temps de démarrage.
Ajouter le chargeur dynamique
Pour utiliser le chargeur dynamique, assurez-vous d'ajouter la balise de script suivante à votre page Web, en ajoutant votre propre clé API à l'emplacement approprié (que vous avez obtenue à l'étape 2). Placez cette balise de script entre les sections "body" de la page Web de base.
<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>
Notez qu'à ce stade de la sortie du produit, nous utilisons la branche alpha de l'API pour accéder aux cartes 3D. Il contient les fonctionnalités les plus expérimentales des produits et vous permet de tester le code en accès anticipé pendant son développement afin de pouvoir l'utiliser dès sa sortie.
Vous devriez maintenant disposer d'une page Web de base contenant le chargeur dynamique (si vous ouvrez la page, la vue sera vide, mais ne devrait pas comporter d'erreurs). Vous pouvez maintenant ajouter la carte 3D.
Si, pour une raison quelconque, votre code ne fonctionne pas, vous pouvez passer à l'étape 6 et le comparer au résultat final pour identifier le problème.
Pour savoir pourquoi la page ne fonctionne pas, consultez la console d'erreurs de votre navigateur. La page d'erreur explique comment procéder pour différents navigateurs. Elle explique également les différents messages d'erreur et indique les raisons courantes pour lesquelles l'API peut ne pas fonctionner. Il s'agit d'une bonne ressource à utiliser tout au long du développement pour déterminer les problèmes potentiels d'implémentation.
5. Afficher une carte
Nous sommes maintenant prêts à ajouter notre première carte 3D à la page.
Les cartes 3D sont créées à l'aide de la classe google.maps.maps3d.Map3DElement, qui permet de créer et d'utiliser des instances de carte 3D. Dans cet atelier de programmation, nous allons utiliser directement l'objet Carte 3D plutôt que via la balise HTML.
Créer la fonction d'initialisation et charger la bibliothèque
Nous allons d'abord créer une fonction qui charge l'élément sur la page. En examinant le code, nous créons d'abord une fonction asynchrone, qui nous permet de nous assurer que l'ensemble de l'élément est chargé avant de continuer avec le reste du code. Nous exécutons ensuite la fonction init au moment du chargement de la page.
Ajoutez-le après le script de chargement dans la section "body" de la page.
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
}
init();
</script>
Notez que nous utilisons l'expression await pour nous assurer que la bibliothèque est chargée avant de continuer.
Créer l'élément de carte 3D et spécifier l'emplacement
Nous devons ensuite spécifier l'emplacement pour lequel nous souhaitons afficher la vue cartographique. Pour Maps 3D, vous pouvez utiliser différents paramètres pour définir la vue. Il s'agit des paramètres de la caméra virtuelle qui décrivent ce que vous regardez dans la scène.
Créons une vue de la tour CN qui ressemble à ceci.
Nous devons d'abord spécifier les coordonnées que nous souhaitons examiner. Ils sont composés de deux vues différentes :
- Point que nous voulons examiner, y compris son altitude.
- Distance et direction de la caméra virtuelle qui regarde le point.
L'image suivante vous donne une idée du fonctionnement de ces paramètres.
Le centre de l'élément correspond au point que vous regardez, la portée à la distance à laquelle vous vous trouvez de l'objet et l'inclinaison à l'angle sous lequel vous regardez l'image. Vous pouvez également définir le cap et le roulis de l'objet si vous souhaitez les contrôler également, mais nous n'utilisons pas cette fonctionnalité ici.
Nous allons maintenant créer la carte 3D sur la page. Ajoutez le code suivant à la section d'initialisation de la page une fois la bibliothèque importée.
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.HYBRID,
});
document.body.append(map3DElement);
Nous commençons par créer l'élément et définir les paramètres de position appropriés, puis nous ajoutons le composant sur la page (nous pourrions l'attribuer à une div existante si elle était présente).
Votre code devrait maintenant se présenter comme suit:
<!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>
Nous pouvons maintenant enregistrer le fichier et ouvrir la page dans un navigateur pour voir si elle fonctionne. La caméra doit être orientée vers le bas, comme illustré dans l'image. Jouez un peu avec la scène avant de continuer et d'ajouter un boîtier au-dessus de la tour.
6. Ajouter et extruder des éléments géographiques
Maintenant que nous avons une carte 3D, continuons et mettons en avant un objet pour indiquer aux utilisateurs qu'il s'agit d'un élément intéressant. Dans ce cas, nous allons utiliser un polygone et la fonction d'extrusion pour créer un cadre autour de la tour CN, afin qu'elle ressemble à la vue suivante.
Masquer l'encombrement
La première chose que vous remarquerez est que nous avons désactivé les points d'intérêt. Dans cette carte, nous voulons que la tour elle-même soit mise en avant. Nous devons donc supprimer les autres éléments visuels.
Pour ce faire, nous devons modifier le code pour masquer les libellés. Définissez la ligne de mode de la carte sur SATELLITE pour masquer les points.
mode: MapMode.SATELLITE,
Cette propriété désactive les libellés sur la carte, y compris les points d'intérêt, mais aussi les routes et les lignes de délimitation. Elle crée une vue "propre" de l'emplacement.
Ajouter et styliser le polygone
L'étape suivante consiste à ajouter le polygone à la page. Pour ce faire, procédez en deux étapes. Nous devons d'abord charger les fonctions contenant les informations requises, puis spécifier les détails de style du polygone, tels que sa couleur ou s'il s'affiche derrière d'autres éléments géographiques.
Nous commençons par ajouter les classes requises à la page à l'aide de la ligne de code suivante.
const { Polygon3DElement, AltitudeMode } = await google.maps.importLibrary("maps3d");
Cela charge les classes Polygon3DElement et AltitudeMode sur la page, qui sont nécessaires pour ajouter un objet polygone à la vue.
Un polygone peut avoir plusieurs paramètres différents qui peuvent contrôler la vue, de l'épaisseur du trait, de la couleur (par nom ou valeur hexadécimale) et de l'opacité des paramètres de limite et de remplissage, à la possibilité de l'afficher derrière d'autres éléments ou bâtiments, par exemple : dessiner des segments masqués. Pour en savoir plus, consultez la documentation de la classe Polygon3DElement.
L'autre fonctionnalité que nous devons définir est que le polygone doit être dessiné de manière extrudée. Cela signifie que vous devez dessiner un polygone à l'altitude définie, puis l'étendre jusqu'au sol. Cela donne au polygone une hauteur semblable à celle d'une boîte (comme illustré dans l'image ci-dessus). Nous devons également définir le mode d'altitude sur le polygone. C'est pourquoi nous avons dû charger les constantes AltitudeMode ci-dessus. Pour extruder un polygone, vous devez définir cette valeur sur ABSOLUTE ou RELATIVE_TO_GROUND afin d'obtenir la position correcte à partir des hauteurs des sommets du polygone.
Le code crée un objet littéral contenant ces propriétés, qui peuvent ensuite être utilisées pour créer l'objet Polygon3DElement comme indiqué:
const polygonOptions = {
strokeColor: "#EA433580",
strokeWidth: 4,
fillColor: "#0000FF80",
altitudeMode: "ABSOLUTE",
extruded: true,
drawsOccludedSegments: true,
}
const towerPolygon = new google.maps.maps3d.Polygon3DElement(polygonOptions);
Nous avons maintenant créé l'objet polygone et nous devons également définir ses coordonnées géographiques. Les polygones peuvent avoir des coordonnées internes et externes en fonction de leur représentation. innerCoordinates indique la forme des découpes dans le polygone, tandis que outerCoordinates définit la limite extérieure du polygone. Comme il s'agit d'un polygone et non d'une ligne, les coordonnées doivent commencer et se terminer au même point pour donner une forme complète.
Vous pouvez spécifier les coordonnées à l'aide d'un tableau d'objets ou de littéraux LatLng ou LatLngAltitude. Nous pouvons le voir pour notre polygone de base.
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 }
];
Maintenant que nous avons configuré le style et les coordonnées du polygone, nous pouvons l'ajouter à la page. Les polygones sont des éléments enfants de l'élément Map et doivent être ajoutés à un objet de carte existant sur la page. Ajoutez le code suivant à la page.
map3DElement.append(towerPolygon);
Une fois que vous aurez obtenu ces informations, vous devriez avoir l'implémentation complète suivante, comme illustré ci-dessous (à l'exception de votre propre clé API). Nous sommes prêts à exécuter la page et à voir le résultat.
<!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>
Si le code est correct, une page affichant la carte 3D et le polygone suivants doit s'afficher.
Vous avez créé votre première carte 3D à l'aide de Google Maps Platform, ce qui implique de charger l'API Maps JavaScript, de créer une carte 3D et d'ajouter un polygone extrudé.
7. Étape suivante
Dans cet atelier de programmation, vous avez découvert les principales fonctionnalités de l'API Maps JavaScript. Essayez ensuite d'ajouter les éléments suivants à la carte :
- Ajoutez un bouton pour activer ou désactiver les points d'intérêt.
- Ajoutez des lignes qui indiquent un itinéraire entre différents lieux.
- Définissez des restrictions de limites pour contrôler l'endroit où l'utilisateur peut déplacer la vue.
- Consultez les autres bibliothèques disponibles pour l'API Maps JavaScript et qui proposent des services supplémentaires, comme Places ou Directions.
Pour découvrir d'autres façons d'utiliser Google Maps Platform et la 3D sur le Web, consultez les liens suivants: