Rechercher dans le blog

Créez une carte 3D pour votre site web : paramétrage de la scène et choix de la basemap

Dans ce premier tutoriel de la série de prise en main de l'API JavaScript d'ArcGIS, nous allons voir ensemble comment initialiser un projet, comment afficher une scène 3D et paramétrer sa caméra et sa basemap. 
Voici le résultat auquel nous allons parvenir à l'issue de quelques courtes étapes :
Vous pouvez suivre le tutoriel pas à pas ci-dessous pour créer cela par vous-même, mais vous pouvez également vous rendre sur ce CodePen pour tester le code en mode bac à sable.

Initialiser le projet

Comme toute page web, notre projet sera constitué d'un HTML (.html), qui contient la structure de notre page web, d'un fichier CSS (.css), qui est la feuille de style permettant de personnaliser l'affichage de la page, et enfin d'un fichier JavaScript (.js) qui contient le code déclenchant des actions sur la page. Ici, en plus de nos propres fichiers .css et .js, nous ferons appel à ceux de l'API JavaScript, qui nous permettront de faire appel à ses services.
Voici un schéma de l'architecture de notre projet :

HTML

Il s'agit en soit d'un HTML classique, dans lequel vous devez référencer l'API JavaScript et sa feuille de style au sein de la balise <head> de la manière suivante :
En plus de cela, j'ajoute également un lien vers ma feuille de style personnalisée et vers mon propre fichier .js qui contiendra le gros du code.
La balise <body> du html doit également contenir une balise <div> qui contiendra la vue de ma carte. Pour ce projet, je lui donne l'identifiant "viewdiv".
Le code HTML complet du projet à cette étape est le suivant :  
Vous pouvez le récupérer ici sur Github.

CSS

La feuille de style n'est en soit pas indispensable pour créer de jolies cartes web, car l'API JavaScript d'ArcGIS utilise par défaut une feuille de style qui permet d'organiser et d'afficher de manière esthétique les différents éléments de l'API auxquels vous ferez appel dans votre application. Cependant, nous allons utiliser une feuille de style personnalisée, que vous pouvez aller récupérer sur Github.
Cette feuille de style me permet de mettre en forme les différents éléments de la page web, notamment le texte des crédits en bas à gauche. Elle intercepte également quelques éléments de la feuille de style de l'API JavaScript et les personnalise, mais nous en reparlerons en temps voulu.

JavaScript

Pour la suite des tutoriels, c'est dans le code JavaScript (.js) que nous allons travailler en priorité. C'est ici que nous allons pouvoir faire appel aux différents services offerts par l'API JavaScript d'ArcGIS pour ajouter de la géo à nos sites web. 
Pour initialiser le projet, nous  allons utiliser la directive require qui nous permet de charger les différents modules de l'API dont nous aurons besoin : pour l'instant, Map, Basemap et SceneView. Elle sera à compléter au fur et à mesure des semaines à chaque fois que nous aurons besoin d'un nouveau module.
require(["esri/Map", "esri/Basemap", "esri/views/SceneView"], (
  Map,
  Basemap,
  SceneView
) => {
// Nous ajouterons la suite du code ici
});

Configurer une carte : choix de la basemap

Maintenant que le projet est initialisé, nous allons pouvoir rentrer dans le dur du sujet et utiliser l'API JavaScript. Commençons par paramétrer une carte à afficher.
Nous allons faire appel à la classe Map de l'API. C'est cette classe Map qui contient des propriétés et des méthodes permettant de stocker, de gérer et de superposer des couches communes à la visualisation 2D et 3D.
Pour l'instant, nous allons seulement nous intéresser à sa propriété basemap pour choisir le fond de carte qui viendra donner un contexte à nos données. Des fonds de carte préconfigurés sont utilisable via une simple chaîne de caractère, que vous retrouverez dans la documentation. Attention, l'utilisation de certains d'entre eux nécessitent une clé d'API.
Ici, pour paramétrer la propriété basemap, nous allons faire appel à la classe Basemap de l'API. Celle-ci nous permet de créer notre propre fond de carte, en utilisant par exemple des éléments d'un portail ArcGIS via la propriété portalItem. Cette propriété prend en paramètre l'identifiant d'un élément d'un portail ArcGIS. Nous allons ici utiliser l'élément "Topographic" publié Esri. C'est un tout nouveau fond de carte 3D affichant les arbres et les bâtiments issus des données d'OpenStreetMap superposés à un fond de carte d'ArcGIS. Nous retrouvons l'identifiant de l'élément dans son url, que nous pouvons donc renseigner en paramètre de la propriété.
Voici donc le code utilisé pour configurer la carte et sa basemap :
  const map = new Map({
    basemap: new Basemap({
      portalItem: {
        id: "0560e29930dc4d5ebeb58c635c0909c9" // References the 3D Topographic Basemap
      }
    })
  });

Configurer une vue de scène (3D) : appel de la carte et paramétrage de la caméra

Afin d'afficher la carte dans notre page web, nous allons faire appel à la classe SceneView, qui permet de créer une vue 3D de la carte. Son équivalent MapView permet de créer des vues pour vos applications 2D, nous ne l'utiliserons pas ici mais son fonctionnement est sensiblement identique.
Nous allons commencer par signaler dans quelle balise du document html la vue sera contenue en configurant le paramètre container. Nous le paramétrons ici à "viewDiv", car c'est l'identifiant attribué à notre balise html lors de la première étape d'initialisation du projet.
Nous indiquons ensuite sur quelle carte nous souhaitons créer la vue avec le paramètre map. Ici, il s'agit de la carte map que nous venons de créer à l'étape précédente.
Enfin, nous paramétrons la camera, qui définira quel sera le point de vue de l'utilisateur sur notre scène. Celle-ci se configure avec les paramètres suivants : une position (contenant elle-même les paramètres longitude, latitude et z), un heading (son orientation par rapport au Nord) et un tilt (son inclinaison). Ici, nous faisons en sorte que la configuration initiale de la caméra offre un joli point de vue sur le Sacré Cœur.
Voici le code de cette dernière partie :
  const view = new SceneView({
    container: "viewDiv",
    map: map,
    camera: {
      position: {
        longitude: 2.340861136194503,
        latitude: 48.88276594605576,
        z: 178.8139155479148
      },
      heading: 29.620133897254565,
      tilt: 65.59724234196116
    }
  });
A partir de maintenant, vous devriez voir apparaître la carte 3D dans votre page web, et donc arriver à la fin de ce premier tutoriel. 

Comment définir les paramètres de sa caméra ?

Afin de trouver les bons paramètres pour les propriétés de votre caméra, vous pouvez utiliser cette application : naviguez au point de vue souhaité puis copiez/collez les paramètres qui s'affichent à l'écran (n'hésitez pas à consulter l'application en mode plein écran en suivant ce lien).
C'est tout pour ce premier tutoriel ! Vous pouvez retrouver sur Github ce à quoi devrait ressembler votre code JavaScript complet à l'issue de ce premier tutoriel, ou le retrouver sur CodePen pour modifier interactivement les paramètres.

Rendez-vous la semaine prochaine, où nous apprendrons à ajouter des données issues d'un fichier GeoJSON à notre carte !

8 commentaires:

  1. Bonjour. Merci déjà pour cette série de tuto ! Je me posai une question par rapport au paramétrage de la vue par défaut de la scène. Est-ce qu'ile existe un moyen simple (outil, app, ...) de trouver la bonne combinaison de paramètres pour le Z, Heading et Title autrement qu'en testant "au feeling" ?

    RépondreSupprimer
    Réponses
    1. Bonjour !
      Voici la technique que j'utilise :
      Côté HTML, j'ajoute un bouton (blogger ne me laisse pas mettre d'html en commentaire ; mais tout sera dans le tuto #6 où nous ajouterons plusieurs points de vue)
      Et côté JavaScript, je relie ce bouton à une impression des paramètres de la caméra avec un console.log :
      let btn = document.getElementById("btn");
      btn.addEventListener("click", (ev) => {
      console.log("parametres camera :", view.viewpoint.camera);
      });
      J'initialise ensuite la scène avec des lat/long approximatifs, puis navigue dans la scène pour obtenir le point de vue qui m'intéresse. Je clique sur le bouton que j'ai créé et j'inspecte la page web pour obtenir les paramètres qui m'intéressent dans la console du navigateur (heading et tilt son visibles directement, il faut aller rechercher latitude, longitude et z en dépliant la propriété position).
      En espérant que cela vous sera utile

      Supprimer
    2. Merci beaucoup pour votre réponse (sorry pour le retour tardif mais je n'ai pas été notifié de vitre réponse) ! Vivement la suite des tutos :)

      Supprimer
    3. Bonjour ! En complément de ma réponse précédente, votre commentaire m'a fait remarquer qu'en effet, il manquait une app permettant de retrouver facilement les paramètres de caméra; j'en ai donc développé une que vous pouvez retrouver ici :https://japalenos.github.io/JS-API/Scene-Camera-Parameters/ cela évitera les étapes un peu fastidieuses décrites ci-dessus...
      Merci beaucoup pour l'intérêt que vous portez à cette série :)

      Supprimer
  2. Bonjour et merci pour ces tutos, je vois que les formations Java Esri passées ensemble portent leurs fruits ;) . Petite question, la basemap que tu utilises est acutellement seulement disponible sur AGOL (si je ne me trompe pas). Sais tu si elle est dispo sur AGE 11.1 ? Merci beaucoup!

    RépondreSupprimer
    Réponses
    1. Bonjour, ravie de retrouver un camarade de formation ici ! En effet cette basemap fait partie des nouveautés d'ArcGIS Online de Juin ; elle n'est pas encore disponible sur Enterprise (généralement les nouveautés arrivent d'abord sur Online puis sur Enterprise et la version 11.1 d'AGE date d'avril). On peut peut-être espérer la voir arriver en 11.2, ou dans l'une des versions suivantes. Cependant, il est normalement possible de l'utiliser avec l'API sans AGOL ou AGE en référençant son identifiant comme dans le tuto

      Supprimer
  3. Merci de ton retour, je vais réessayer.

    RépondreSupprimer